Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
FSP(1)			    General Commands Manual			FSP(1)

       fsp - an	all-in-one FSP client

       fsp [-dvV] [[macro [parameters]]	| [host	[port [directory]]]]

       fsp  is	an  ftp	 like client for an anonymous-ftp style	archive	system
       called FSP.  See	fspd(1)	for further details on FSP.  When given	the -d
       flag,  the  client  enters debugging mode; this is generally not	a good
       idea, and only exists for development purposes.	The -v	and  -V	 flags
       print out a copyright banner; they differ in that -V causes the program
       to immediately exit rather than continuing into interactive mode.

       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 com-
       mand.  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  success-

       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 argu-
		 ments given on	the command line rather	than showing subdirec-
		 tories	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 prac-
		 tically 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	 stan-
		 dard  FTP ls.	Notably, once it has fetched a directory list-
		 ing it	does not query the  remote  server  for	 that  listing
		 again:	 the listing is	held on	the local end.	This has 2 ef-
		 fects;	the second directory listing you request  is  (practi-
		 cally)	 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

       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 band-
		 width.	 No facilities that the	 server	 allows	 will  be  re-
		 stricted;  only commands which	are guaranteed to fail will be
		 prevented.  permission	can be either `c' or `d' in the	 stan-
		 dard  server;	these  refer  to `create' and `delete' permis-
		 sions.	 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	direc-

       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 us-
		 ing mkdir to send messages!

       ver	 Return	the version string of the remote system.  This	infor-
		 mation	 is  cached  locally.	If  the	 server	is an advanced
		 server, then this command also	gives the local	client	knowl-
		 edge  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

       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	trans-
       ferred, 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 cur-
		 rent 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 con-
		 nection -- if the connection generally	allows faster communi-
		 cation,  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  re-
		 mote 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 de-
		 scription of each macro for which a help string was provided.
		 Otherwise,  the argument list is assumed to be	a list of com-
		 mands,	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 exis-
		 tence.	 If you	want to	guarantee that you execute the builtin
		 version  of a command precede it by the command builtin.  En-
		 ter 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	recur-
		 sive; if a recursion loop is detected then the	attempt	to re-
		 curse 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  bel-
		 low  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  in-
		 voked by the cat command, which filters its output though it.
		 The value will	tend to	be something like more or less.	  Sup-
		 plying	 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 ex-
		 ists; 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 af-
		 ter the `!').

       since [time|local-file]
		 When a	`ls' is	performed the date stamps on  files  are  com-
		 pared	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 sec-
		 onds 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 infi-
		 nite 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' en-
		 sures that FSP	keeps quiet during file	transfers; no informa-
		 tion  is printed about	the transaction.  `on' causes the num-
		 ber of	Kbytes transferred to be printed, as well as retry in-
		 formation (the	character `R', which turns into	a spinning bar
		 for each retry	of a get/put of	a Kbyte	of data).  `hash'  be-
		 haves	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	trans-
		 fers to be printed after each file copy operation.  If	`?' is
		 given,	 the current mode is printed.  If no parameter is sup-
		 plied then the	current	value is advanced  (with  wrap-around)
		 through the list given	above.

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

       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  com-

	      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.


       The original (individual) clients were written  by  Wen-King  Su	 <wen->.  They, and some library code,	was then modi-
       fied, and the front-end parser, macro's,	 local	commands  and  general
       glue  were  written by Phil Richards <> in order to
       form this client.  The initial globbing code was	written	by Rene	 Sein-
       dal for an ftpd,	and modified minutely to fit with the scheme of	things
       by Phil Richards. After 10 years	or so, this code is now	maintained  by
       Radim Kolar.

       Quite  a	 lot, thank you	very much.  As they are	found, they are	listed
       and slowly fixed.  Pipes	inside macros can cause	 unexpected  behaviour
       if  the	macro is then fed into another pipe (unexpected	= I don't know
       what will happen).  Other major ones that have to fixed at  the	moment
       are:  brace expansion needs adding to the globbing code;	positional pa-
       rameters, environment variables,	and local variables  should  be	 added
       (this would allow a number of parameter setting commands	to be removed,
       or turned into macro's);	the shell  command  should  be	one  --	 there
       should also be a	non-shell command for fast exec'ing of commands.

       All  bug	 reports  on  this  code  should  be  directed	to http://fsp-

LOCAL				  24 Jul 2005				FSP(1)


Want to link to this manual page? Use this URL:

home | help