FCAST(1)

NAME
fcast - send or receive files using the MultiCast Library (MCL) using the ALC protocol

SYNOPSIS
fcast [-h[elp]] [-send] [-recv] [-a address[/port]] [-if address] [-demux demux_level] [-l nb_of_layers] [-singlelayer] [-v verbosity_level] [-stat stat_level] [-silent] [-tmp tmp_dir_string] [-p low|med|high|lan] [-p size[/rate]] [-o speed/space/cpu] [-P] [-t ttl] [-R] [-cont] [-repeat n] [-fec n] [-huge] [-src address [-int] [-never] [-force] [file list or directory]

DESCRIPTION
fcast is a multicast file distribution application built over the MultiCast Library (MCL) which uses the ALC (Asynchronous Layered Coding) reliable multicast protocol. fcast can run both as a sender or a receiver. fcast has many features like the ability to send recursively all the files of a given directory and its subdirectories, the ability to favor reception speed, memory requirements or CPU load at the receiver, and last but not least the possibility to be used in ``on-demand'' or ``push'' mode. fcast communicates many meta-data information along with the files in order to precisely re-construct the file at the receiver. An application-level checksum (using the same algorithm as that of TCP) is also used in order to detect possible transmission errors.

OPTIONS
The following arguments can be provided both at a sending or receiving fcast.

-h[elp]
    Gives the credits, the compilation parameters and all the possible fcast arguments.

-send or -recv
    Set the Fcast application mode to sender OR to receiver. You must ALWAYS specify one of these two modes.

-a address[/port]
    Specifies the unicast or multicast IPv4 address of the base layer and its UDP port number (if specified). If no -a and/or /port argument is provided, then the default target address (usually that of the loopback interface) and port number of MCL are used. With multicast addresses, the address and port number of layers 1 and above are derived from that of the base layer by MCL (usually by incrementing the address and port number). (communicated to MCL)

-if address
    The network interface to use is the one attached to the local address specified (or hostname specified). This option is only required on multi-homed hosts or on routers as the default interface chosen by the system without this option to send/receive multicast may not be the one you want to use. (communicated to MCL)

-demux N
    Sets the LCT Transport Session Identifier (or TSI) to N. At a sender this TSI is included in each packet sent. At a receiver <src_addr; TSI> are used to fully identify the ALC session and to filter incoming packets. If no -demux argument is provided, then any packet matching the source address (if provided) will be accepted with the risk they belong to other sessions (e.g if they use the same <multicast address, port> tuple). This demux label is also usefull to make sure that the current session will not get confused by packets from previous incarnation session. The receivers and the sender must of course agree beforehand and use the same value. By default a value of 0 is used. (communicated to MCL)

-l number_of_layers
    Specifies the maximum number of layers to use. If not specified, the default value of MCL is used instead. Note that a receiver is anyway constrained by the number of layers offered by the source. (communicated to MCL)

-singlelayer
    Set the single layer mode. If not specified, the default value of MCL is used instead. This argument must be used both at the source and receivers. The -l argument must not be used (implicitely equal to 1). This argument is compatible with the -p low/med/high/lan argument which specifies the datagram size and transmission rate. This datagram size and transmission rate can also be specified directly with the -p size[/rate] argument. This argument is also compatible with the -o space/speed/cpu argument which determines the optimization profile. (communicated to MCL) WARNING: it is important that the transmission and reception profiles match, so use it on both ends.

-v verbosity_level
    Specifies the level of verbosity desired from the MCL library. This option also automatically enables the -stat 2 option to add statistics. Note that full verbosity requires that the MCL library be compiled in DEBUG mode. (communicated to MCL)

-stat stat_level
    Specifies the level of statistics desired from the MCL library. Level 0 (default) means nothing, level 1 means that only the final statistics (at end of session) will be displayed, level 2 means that each time an object is fully received, statistics are displayed. (communicated to MCL)

-silent
    Enables the silent mode (nothing sent to stdout).

-tmp tmp_dir_string
    Set the MCL temporary directory to be tmp_dir_string rather than its default (usually "/tmp" with Unix). The argument is a string, e.g. : -tmp/home/roca/tmp (communicated to MCL)

-p low|med|high|lan
    Specifies the transmission profile. Possible values are: low (LOW_RATE_INTERNET), med (MID_RATE_INTERNET), hig (HIGH_SPEED_INTERNET), and high (HIGH_SPEED_LAN). If not specified, the default value of MCL is used instead. The -p size[/rate] argument can be used instead (but not at the same time). (communicated to MCL) WARNING: it is important that the transmission and reception profiles match, so use it on both ends.

-p size[/rate]
    Specifies the datagram size (in bytes) (at a sender or receiver), and optionally the transmission rate (in bits/s) (only at a sender). This argument cannot be used along with one of the -p low|med|high|lan arguments. (communicated to MCL) WARNING: it is important that the transmission and reception profiles match, so use it on both ends (only -p size at a receiver).

-o space/speed/cpu
    Specifies the optimization profile (in particular the order in which packets are sent on each layer). Possible values are: space to optimize the maximum memory space required at a receiver, speed to optimize the reception speed, and cpu to differ CPU intensive tasks at a receiver (recommanded on a CPU bounded host). If not specified, the default value of MCL is used instead. (communicated to MCL) WARNING: it is important that the transmission and reception optimization match, so use it on both ends.

-P  If enabled, causes fcast to make a pause before exiting (WIN32 only). Used to prevent the closing of console window when fcast done, thus giving some time to read outputs.

The following arguments are specific to a sender.

-t ttl
    Specifies the time to live (ttl) value of the IP header. If not specified, the default value of MCL is used instead (usually 1). Use -t 1 if all the receivers are attached to the same LAN as the source. (communicated to MCL)

-R  Enables the recursive mode. Using this flag, fcast recursively sends the whole directory tree given as a parameter. At the receiver side, the same directory tree is created in the CURRENT directory (fcast never goes upward).

-cont
    Set the continuous mode for "on-demand" transmissions (i.e. receivers arrive at their discretion, download the file and leave). By default it is not set. (communicated to MCL)

-repeat n
    repeat n times the packet sequence on each layer. Note that -repeat 0 means that data is sent once. By default, data is sent only once (no repeat) on a given layer in ``push'' mode, and data is sent continuously in ``on-demand'' mode. This parameter is usefull to increase the probability of good reception at optimal speed by all receivers when working in ``push'' mode. (communicated to MCL)

-fec n
    Set the FEC ratio to n. This FEC ratio is the N/K ratio, of the total number of symbols after FEC encoding (data + FEC) to the number of source symbols (data). A default value of 2 is used, meaning that the same amount of FEC symbols as original source symbols is produced. Using -fec 1 means that no FEC packets will be produced. A limitation in this version is that this ratio must be an integer. (communicated to MCL)

-huge
    When huge file(s) must be sent (i.e. file(s) whose size, after FEC encoding is largely superior to the available physical memory size), this argument informs the MCL library to take appropriate measures. By default this is flag is FALSE. (communicated to MCL)

The following arguments are specific to a receiver.

-src address
    Specifies the unicast IPv4 address or name of the source. At a receiver <src_addr; TSI> are used to fully identify the ALC session and to filter incoming packets. If no -src argument is provided, then any packet matching the TSI (if provided) will be accepted with the risk they belong to other sessions (e.g if they use the same <multicast address, port> tuple). (communicated to MCL)

-int -never or -force
    Sets the overwriting mode for an receiver when a file to save already exists. int stands for interactive mode, meaning that the user will always be asked before overwriting a file. Using never , files are never overwritten. Finally force means that any existing file will be automatically overwritten. Default is int mode where the answer will quickly disappear!).

EXAMPLE
Here is a simple example where we send the file "foo.bar" on group 225.1.2.3 (and above) :
fcast -send -a225.1.2.3/2323 -v1 ./foo.bar
A more complex example is the following, sending the whole directory "foobar/" :
fcast -send -a225.1.2.3/2323 -demux123 -stat1 -phigh -ospeed -l8 -R foobar/
A receiver for the previous exemple:
fcast -recv -R -a225.1.2.3/2323 -demux123 -stat1 -phigh -ospeed -never
Here is a session where we completely specify the transmission parameters (1024 bytes of payload per packet, and 1Mbps transmission rate):
fcast -send -a225.1.2.3/2323 -v1 -p1024/1000000 ./foo.bar
fcast -recv -a225.1.2.3/2323 -v1 -p1024

COPYRIGHTS
Copyright (c) 1999-2002 INRIA - Universite Paris 6 -
All rights reserved
(main authors: Vincent ROCA    - vincent.roca@inrialpes.fr
               Julien  LABOURE - julien.laboure@inrialpes.fr)
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

SEE ALSO
fcastn(1)fortheNORMversion, mcl_ctl(3), MCL documentation, the INRIA Research Report 4411 (March 2002) titled "Improving the Efficiency of a Multicast File Transfer Tool Based on ALC"

AUTHORS
Vincent ROCA (INRIA Rhone-Alpes, Planete project)
Julien LABOURE (INRIA Rhone-Alpes, Planete project)
$Id: fcast.man.1,v 1.2 2003/07/10 15:31:41 roca Exp $