NAME

SYNOPSIS

DESCRIPTION

When started fsp attempts to read a startup file (see FILES below). If the input is a terminal, it then enters interactive mode, and awaits user commands. If no host has been specified on the command line, then one must be specified before any remote commands can be executed. If the input is not a tty, then commands are read until end-of-file is reached. If an unquoted `|' is the first character in a command line argument then the rest of the line is considered to be a shell command, and the output of the command preceeding the `|' is sent to that command. The available remote commands are:

cat [-r] file [files...]

Same as get but the files are written to the screen rather than to files. If the -r flag is specified, then directories that are found are entered and searched recursively for files to view. See the environment variable PAGER and the command pager for how to make this command automatically pass output into another program (for example, more ).

close

Closes session to remote system.

cd [directory]

Change directory on the remote system. The permissions on the remote directory are printed if the command was successful.

du [-rcas] [files...]

Calculate the disk usage of the files specified; if no files given, default to the current directory (`.'). If the -r flag is given, descend into subdirectories. If -c is given, give a grand total of filesizes at the end (assuming there is more than one file given on the command line). If -a is given, show all files rather than just directory totals. If -s is given, then summarise the totals for each of the arguments given on the command line rather than showing subdirectories individually. -s and -a are incompatible.

get [-r] file [files...]

Download a copy of the list of files specified; globbing is performed on the filenames given in the style of the Bourne shell. If the -r flag is given, then the remote directory structure is copied locally; directories are entered, and files within them copied. Without the -r flag all files are copied into to the local directory, and directories in the arguments are ignored.

grab file [files...]

An atomic action which performs a get followed by a delete. Two attempts to grab the same file will result in only one of them actually suceeding. There is no -r version.

ls [flags] [files]

Get a directory listing of remote files. This behaves practically identically to BSD4.2 ls; see the manual page for ls(1) for options if you are using a BSD system, or guess if you aren't. The fsp ls command behaves differently to standard FTP ls. Notably, once it has fetched a directory listing it does not query the remote server for that listing again: the listing is held on the local end. This has 2 effects; the second directory listing you request is (practically) instantaneous since it is not necessary to ask for it again; and, secondly, if there are any modifications to the remote directory whilst you are connected, you will not see them. Use the rehash command if you want to scratch the clients copy of the remote systems directory listings and protections.

dir

Remote directory listing in long format. Dir is built-in alias for ls -l.

mkdir directory [directories...]

Make the specified directories on the remote system. The site that created the directories is labelled their owner.

mv oldfile newfile

Renames specified file on the remote system. You must have permission rename in target and source directory.

pro [[-|+][permission]] [files...]

Return or set the protection for the remote directory. If the server is an advanced server then this command also gives the local client knowledge about what operations can and can't be done in the remote directory; these will be rejected by the client rather than the server in order to save bandwidth. No facilities that the server allows will be restricted; only commands which are guaranteed to fail will be prevented. permission can be either `c' or `d' in the standard server; these refer to `create' and `delete' permissions. Prefixing by `+' sets the permission, `-' removes it. Only the owner of a directory can set the permissions. If no permissions are given, the current settings are printed.

put file [files...]

Upload a copy of the list of files specified; as for get, globbing is performed on the filenames. In order to upload a file, you must have `create' permission on the remote directory.

rm file [files...]

Remove the specified files. Globbing is performed as for get. In order for this command to succeed you must have `delete' permission on the remote directory.

rmdir directory [directories...]

Remove the specified directories on the remote system. Only the owner can do this, and the remote directories must be empty for it to work.

tar [-r] tarfile file [files...]

Create a tarfile locally called tarfile which is made up of the listed files. If the -r flag is given, then behave in a similar recursive manner to get. The names of the files within the archive are precisely those that would be created if the command was get.

touch file [files...]

If the specified files do not exist on the remote server, then the files are created zero-length. If they do exist, then nothing is done. This is a much better method than using mkdir to send messages!

ver

Return the version string of the remote system. This information is cached locally. If the server is an advanced server, then this command also gives the local client knowledge about what can and cannot be done; for example, the client will prevent attempts to upload to a read-only server since attempts to perform that operation are guaranteed to be rejected.

In addition to these commands, there is a set of commands which are purely local in their action. Note that some of the commands you would have expected to be remote are in fact local. Primarily, open does not contact the remote site. Contact is only ever made with the server when you want to ask it something. Further, ls is remote for only as long as it needs to be; as soon as the directory information is transferred, further ls purely locally.

buffer [size|?]

Set the size of the data packets to be transferred. This can be at most 1024 bytes, but some systems may need the number to be lowered in order to get the packets through gateways.

builtin command [args]

Guarantee that the builtin version of command is executed. This can be abbreviated to @. i.e., @ls is identical to builtin ls and both run the `proper' version of ls.

burst [count|?]

When a request is made from the server for another piece of information, either the request or reply can get lost. In this case, the client needs to try again; and again, and again... The current method of doing this is to try once, wait a bit, try again, wait for a bit longer, etc, with the retry period increasing at each failure. The burst command sets the number of `quick' retries that are made at each of these increasing time steps; the long retry period can stretch to about 10 minutes -- this command allows the number of attempts made after each 10 minute period to be set. (The default is 1; you don't gain much by setting it at more than about 4.)

datestamp [on|off|?]

When a file is downloaded, this controls whether the access dates on the file are set to the same as those on the remote end. This may or may not be useful...

debug [level]

Set the debug level to the value specified, or print the current level if no argument is given. Most people won't want to see the output that this generates... (specifying `debug n' is the same as giving `n' -d flags on the command line).

delay [period|?]

Set the minimum retry period (in milliseconds); the default is 1340, the minimum allowed is 1000. This value is used as a baseline and each retry has progressively longer gaps. Note that this value is modified by performance of the connection -- if the connection generally allows faster communication, the retry period will be automatically changed to take account of it.

echo [text]

echon [text]

Echo the supplied text to the user; these commands differ in whether they also print a newline character at the end of the text; echon does not. These commands are only of any real use in files that are to be sourced, or in macros.

iferror command

If the last command caused an error, execute command.

ifok command

If the last command completed successfully, execute command.

onerror command

Whenever an error occurs, execute command.

skipto label

Ignore all input lines until a line which begins with label: Execute the command on that line (possibly a null command). This is useful in scripts for ignoring a block of commands depending on the error code of a command.

exit [n]

This command terminates the client with the error code of the previous command. If the optional argument is supplied, then the program exits with that value as the return code.

flush

Stronger version of rehash All cached information about remote system are cleared.

help [ all | name ... ]

With no parameters, this prints out a list of the commands and macros that are defined. With the argument all a long description of each command is given, as well as a long description of each macro for which a help string was provided. Otherwise, the argument list is assumed to be a list of commands, and the long help string for each command is printed. ? is an alias for this command.

host

Same as open.

lcd directory

Change directory on the local machine.

macro [-[rl]] name [help]

Without either the -r or -l flags, this defines a macro called name and, if the help string is supplied (which must be a quoted single argument to the command), then this will be printed when help is invoked on the macro name. If a macro is defined, then it will be executed whenever its name is typed as a command. Macros take precedence over builtin commands; this means that you can alias commands out of existence. If you want to guarantee that you execute the builtin version of a command precede it by the command builtin. Enter the macro line-by-line, and terminate it with a single `.' on a line of its own (no leading whitespace). Macros can not (currently) be either self-recursive or mutually recursive; if a recursion loop is detected then the attempt to recurse is ignored and the macro continues regardless.

If the -r flag is given then the specified macro is removed. If -l is given, then the macro is listed.

maxdelay [period|?]

Set the maximum retry period (in milliseconds); the default is 60000, the minimum allowed is 1000, but setting this bellow 3000 is useless most time.

open name [port [directory]]

Set the host of the remote system; also, possibly set the port number and directory. Note that if either the port or the directory are omitted, they default to the values 21 and / respectively.

pager [command]

Set the `pager' to the command specified. The pager is invoked by the cat command, which filters its output though it. The value will tend to be something like more or less. Supplying no parameter turns off the pager. The initial pager command is given by the environment variable PAGER. When the pager command is invoked, the environment variable FSPFILE is set to the name of the file that is being cat

port number

Set the port number of the connection.

prompt [on|off|?]

When a download operation is performed, a check is made to see if the file that you are trying to download already exists; if it does, you are prompted for whether you want to continue the download, or whether you want to restart it. This turns on/off those questions. If it is set to `off' then the a continue operation is always performed.

pwd

Print the current host, port, and directory on the remote system. The client holds all this information.

quit

Finish your interaction with fsp. The program exits with a return value of 0. This is the same as exit 0 .

readme [never|once|always]

Determine how often (if ever) README files should be read. The options are (hopefully) self explanatory. A README can be force-read for the current directory by typing the command without any arguments.

rehash

Drop all information about the remote site. The local copies of the remote directory structure, permissions and server flags will be lost.

shell command [args]

Run a `shell' command on the specified command and arguments. In fact, this is currently a lie. The command is executed by a direct fork; in a future version this will be implemented properly. shell can be replaced by `!' (no space needed after the `!').

since [time|local-file]

When a `ls' is performed the date stamps on files are compared against the time specified to determine whether they are printed. The interface to this command leaves a lot to be desired; the time must be specified as the number of seconds since 1st January 1970, or it can be specified as the date stamp on a local file. (Only the latter form is really any use.)

source file [files...]

Treat the contents of the specified as if they were typed at the keyboard.

timeout n

If a single communication attempt (i.e., one packet of any transfer) takes longer than n seconds, then cause the command to return an error. If n is set to 0, then assume an infinite timeout period. This is useful when combined with the iferror command -- it allows a script to terminate a session if the remote server is not detected.

touch file [files...]

Create the specified files in the remote directory. If the file already exists, nothing is done, otherwise a zero length file is `uploaded'. You must have `create' permission in the remote directory.

trace [off|on|all|hash|?]

Sets the type of tracing used on file transfers. `off' ensures that FSP keeps quiet during file transfers; no information is printed about the transaction. `on' causes the number of Kbytes transferred to be printed, as well as retry information (the character `R', which turns into a spinning bar for each retry of a get/put of a Kbyte of data). `hash' behaves rather more like ftp; each Kbyte transferred causes a hash to be printed, and information about file size and speed are printed. `all' causes statistics about the packet transfers to be printed after each file copy operation. If `?' is given, the current mode is printed. If no parameter is supplied then the current value is advanced (with wrap-around) through the list given above.

FILES

~/.fsprc

If this file exists it is used as a start-up script. It is useful for executing personalisation commands and macro definitions.

ENVIRONMENT

FSPRC

If this variable is set, then it overrides the default file from which start-up instructions are read.

PAGER

Determine the initial setting of the pager used by the cat command.

FSPFILE

This environment variable is set by the cat command to allow the pager command to know the name of the file it is being fed.

SEE ALSO

AUTHORS

BUGS

All bug reports on this code should be directed to http://fspclient.sourceforge.net