unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

FTP(1C)                                                                FTP(1C)



NAME
       ftp - file transfer program

SYNOPSIS
       ftp [ -dgintv ] [ hostname ]

AVAILABILITY
       This  command  is  available  with the Networking software installation
       option.  Refer to for information on how to install optional software.

DESCRIPTION
       ftp is the user interface to the ARPANET standard File Transfer  Proto-
       col (FTP).  ftp transfers files to and from a remote network site.

       The  client  host  with which ftp is to communicate may be specified on
       the command line.  If this is done, ftp immediately attempts to  estab-
       lish  a connection to an FTP server on that host; otherwise, ftp enters
       its command interpreter and awaits instructions from  the  user.   When
       ftp is awaiting commands from the user, it displays the prompt `ftp>>'.

OPTIONS
       Options  may be specified at the command line, or to the command inter-
       preter.

       -d     Enable debugging.

       -g     Disable filename "globbing."

       -i     Turn off interactive prompting during multiple file transfers.

       -n     Do not attempt "auto-login" upon initial connection.   If  auto-
              login  is enabled, ftp checks the .netrc file in the user's home
              directory for an entry  describing  an  account  on  the  remote
              machine.  If no entry exists, ftp will prompt for the login name
              of the account on the remote machine (the default is  the  login
              name  on  the  local  machine), and, if necessary, prompts for a
              password and an account with which to login.

       -t     Enable packet tracing (unimplemented).

       -v     Show all responses from the remote server, as well as report  on
              data  transfer  statistics.  This is turned on by default if ftp
              is running interactively with its input coming from  the  user's
              terminal.

COMMANDS
       !  [ command ]
              Run command as a shell command on the local machine.  If no com-
              mand is given, invoke an interactive shell.

       $ macro-name [ args ]
              Execute the macro macro-name that was defined  with  the  macdef
              command.  Arguments are passed to the macro unglobbed.

       account [ passwd ]
              Supply  a  supplemental password required by a remote system for
              access to resources once a  login  has  been  successfully  com-
              pleted.   If  no argument is included, the user will be prompted
              for an account password in a non-echoing input mode.

       append local-file [ remote-file ]
              Append a local file to a file on the remote machine.  If remote-
              file  is left unspecified, the local file name is used in naming
              the remote file after being altered by any ntrans or  nmap  set-
              ting.   File transfer uses the current settings for "representa-
              tion type", "file structure", and "transfer mode".

       ascii  Set the "representation type" to "network ASCII".  This  is  the
              default type.

       bell   Sound a bell after each file transfer command is completed.

       binary Set the "representation type" to "image".

       bye    Terminate  the  FTP session with the remote server and exit ftp.
              An EOF will also terminate the session and exit.

       case   Toggle remote computer file name case mapping during  mget  com-
              mands.   When  case is on (default is off), remote computer file
              names with all letters in upper case are written  in  the  local
              directory with the letters mapped to lower case.

       cd remote-directory
              Change  the  working  directory on the remote machine to remote-
              directory.

       cdup   Change the remote machine working directory to the parent of the
              current remote machine working directory.

       close  Terminate  the FTP session with the remote server, and return to
              the command interpreter.  Any defined macros are erased.

       cr     Toggle  RETURN  stripping  during  "network  ASCII"  type   file
              retrieval.   Records  are  denoted by a RETURN/LINEFEED sequence
              during "network ASCII" type file transfer.  When cr is  on  (the
              default),  RETURN  characters are stripped from this sequence to
              conform with the UNIX system single LINEFEED  record  delimiter.
              Records on non-UNIX-system remote hosts may contain single LINE-
              FEED characters; when an "network ASCII" type transfer is  made,
              these  LINEFEED  characters  may  be distinguished from a record
              delimiter only when cr is off.

       delete remote-file
              Delete the file remote-file on the remote machine.

       debug [ debug-value ]
              Toggle debugging mode.  If an optional debug-value is  specified
              it  is  used  to set the debugging level.  When debugging is on,
              ftp prints each command sent to the remote machine, preceded  by
              the string `-->>'.

       dir [ remote-directory ] [ local-file ]
              Print  a  listing  of  the  directory contents in the directory,
              remote-directory, and, optionally, placing the output in  local-
              file.   If no directory is specified, the current working direc-
              tory on the remote machine is used.  If no local file is  speci-
              fied, or local-file is `-', output is sent to the terminal.

       disconnect
              A synonym for close.

       form [ format-name ]
              Set  the  carriage control format subtype of the "representation
              type" to format-name.  The only valid format-name is  non-print,
              which corresponds to the default "non-print" subtype.

       get remote-file [ local-file ]
              Retrieve  the remote-file and store it on the local machine.  If
              the local file name is not specified, it is given the same  name
              it  has on the remote machine, subject to alteration by the cur-
              rent case, ntrans, and nmap settings.  The current settings  for
              "representation type", "file structure", and "transfer mode" are
              used while transferring the file.

       glob   Toggle filename expansion, or "globbing", for mdelete, mget  and
              mput.  If globbing is turned off, filenames are taken literally.

              Globbing  for  mput is done as in csh(1).  For mdelete and mget,
              each remote file name  is  expanded  separately  on  the  remote
              machine, and the lists are not merged.

              Expansion  of a directory name is likely to be radically differ-
              ent from expansion of the name of an ordinary  file:  the  exact
              result  depends  on  the remote operating system and FTP server,
              and can be previewed by doing `mls remote-files -'.

              mget and mput are not meant to transfer  entire  directory  sub-
              trees  of  files.   You can do this by transferring a tar(1) ar-
              chive of the subtree (using a "representation type"  of  "image"
              as set by the binary command).

       hash   Toggle hash-sign (#) printing for each data block transferred.

       help [ command ]
              Print  an  informative message about the meaning of command.  If
              no argument is given, ftp prints a list of the known commands.

       lcd [ directory ]
              Change the working directory on the local machine.  If no direc-
              tory is specified, the user's home directory is used.

       ls [ remote-directory ] [ local-file ]
              Print  an  abbreviated listing of the contents of a directory on
              the remote machine.  If remote-directory  is  left  unspecified,
              the  current  working  directory  is  used.  If no local file is
              specified, or if local-file is `-', the output is  sent  to  the
              terminal.

       macdef macro-name
              Define a macro.  Subsequent lines are stored as the macro macro-
              name; a null line (consecutive NEWLINE characters in a  file  or
              RETURN  characters  from  the  terminal)  terminates macro input
              mode.  There is a limit of 16 macros and 4096  total  characters
              in all defined macros.  Macros remain defined until a close com-
              mand is executed.

              The macro processor interprets `$' and `\'  as  special  charac-
              ters.   A  `$'  followed by a number (or numbers) is replaced by
              the corresponding argument on the macro invocation command line.
              A  `$'  followed by an `i' signals that macro processor that the
              executing macro is to be looped.  On  the  first  pass  `$i'  is
              replaced  by  the first argument on the macro invocation command
              line, on the second pass it is replaced by the second  argument,
              and  so on.  A `\' followed by any character is replaced by that
              character.  Use the `\' to prevent special treatment of the `$'.

       mdelete [ remote-files ]
              Delete the remote-files on the remote machine.

       mdir remote-files local-file
              Like dir, except multiple remote files  may  be  specified.   If
              interactive  prompting is on, ftp will prompt the user to verify
              that the last argument is  indeed  the  target  local  file  for
              receiving mdir output.

       mget remote-files
              Expand  the  remote-files on the remote machine and do a get for
              each file name thus produced.  See glob for details on the file-
              name  expansion.   Resulting  file  names will then be processed
              according to case, ntrans, and nmap settings.  Files are  trans-
              ferred  into  the  local working directory, which can be changed
              with `lcd directory'; new local directories can be created  with
              `! mkdir directory'.

       mkdir directory-name
              Make a directory on the remote machine.

       mls remote-files local-file
              Like  ls(1V), except multiple remote files may be specified.  If
              interactive prompting is on, ftp will prompt the user to  verify
              that  the  last  argument  is  indeed  the target local file for
              receiving mls output.

       mode [ mode-name ]
              Set the "transfer mode" to mode-name.  The only valid  mode-name
              is stream, which corresponds to the default "stream" mode.

       mput local-files
              Expand  wild cards in the list of local files given as arguments
              and do a put for each file in the resulting list.  See glob  for
              details  of  filename expansion.  Resulting file names will then
              be processed according to ntrans and nmap settings.

       nmap [ inpattern outpattern ]
              Set or unset the filename mapping mechanism.   If  no  arguments
              are  specified,  the  filename  mapping  mechanism is unset.  If
              arguments are specified, remote filenames are mapped during mput
              commands and put commands issued without a specified remote tar-
              get filename.  If arguments are specified, local  filenames  are
              mapped  during  mget  commands and get commands issued without a
              specified local target filename.

              This command is useful  when  connecting  to  a  non-UNIX-system
              remote host with different file naming conventions or practices.
              The mapping follows the pattern set by inpattern and outpattern.
              inpattern  is  a template for incoming filenames (which may have
              already been processed according to the  ntrans  and  case  set-
              tings).   Variable  templating  is accomplished by including the
              sequences $1, $2, ..., $9 in inpattern.  Use \ to  prevent  this
              special  treatment of the $ character.  All other characters are
              treated literally, and are used to determine the nmap  inpattern
              variable values.

              For  example,  given  inpattern  $1.$2  and the remote file name
              mydata.data, $1 would have the value "mydata", and $2 would have
              the value "data".

              The  outpattern  determines  the resulting mapped filename.  The
              sequences $1, $2, ..., $9 are replaced by  any  value  resulting
              from the inpattern template.  The sequence $0 is replaced by the
              original filename.  Additionally, the sequence `[seq1,seq2]'  is
              replaced  by  seq1 if seq1 is not a null string; otherwise it is
              replaced by seq2.

              For example, the command `nmap $1.$2.$3 [$1,$2].[$2,file]' would
              yield  the  output  filename  myfile.data  for  input  filenames
              myfile.data and myfile.data.old, myfile.file for the input file-
              name  myfile,  and myfile.myfile for the input filename .myfile.
              SPACE characters may be included in outpattern, as in the  exam-
              ple  `nmap  $1  |  sed "s/  *$//" >> $1'.  Use the \ character to
              prevent special treatment of the `$', `[', `]' and  `,'  charac-
              ters.

       ntrans [ inchars [ outchars ] ]
              Set  or  unset the filename character translation mechanism.  If
              no arguments are specified, the filename  character  translation
              mechanism  is  unset.  If arguments are specified, characters in
              remote filenames are translated during  mput  commands  and  put
              commands  issued without a specified remote target filename, and
              characters in local filenames are translated  during  mget  com-
              mands  and  get commands issued without a specified local target
              filename.

              This command is useful  when  connecting  to  a  non-UNIX-system
              remote host with different file naming conventions or practices.
              Characters in a filename matching a  character  in  inchars  are
              replaced  with  the corresponding character in outchars.  If the
              character's position in inchars is longer  than  the  length  of
              outchars, the character is deleted from the file name.

       open host [ port ]
              Establish  a  connection  to  the specified host FTP server.  An
              optional port number may be supplied, in which  case,  ftp  will
              attempt  to  contact  an  FTP server at that port.  If the auto-
              login option is on (default), ftp will also attempt to automati-
              cally log the user in to the FTP server (see below).

       prompt Toggle interactive prompting.  Interactive prompting occurs dur-
              ing multiple file transfers to allow  the  user  to  selectively
              retrieve  or  store  files.  By default, prompting is turned on.
              If prompting is turned off, any mget or mput will  transfer  all
              files, and any mdelete will delete all files.

       proxy ftp-command
              Execute  an FTP command on a secondary control connection.  This
              command allows simultaneous connection to two remote FTP servers
              for transferring files between the two servers.  The first proxy
              command should be an open, to establish  the  secondary  control
              connection.   Enter the command `proxy ?'  to see other FTP com-
              mands executable on the secondary connection.

              The following  commands  behave  differently  when  prefaced  by
              proxy:  open  will  not  define new macros during the auto-login
              process, close will not erase existing  macro  definitions,  get
              and  mget  transfer  files  from the host on the primary control
              connection to the host on the secondary control connection,  and
              put,  mput,  and append transfer files from the host on the sec-
              ondary control connection to the host  on  the  primary  control
              connection.

              Third  party file transfers depend upon support of the PASV com-
              mand by the server on the secondary control connection.

       put local-file [ remote-file]
              Store a local file on the remote  machine.   If  remote-file  is
              left  unspecified,  the local file name is used after processing
              according to any ntrans or nmap settings in  naming  the  remote
              file.   File transfer uses the current settings for "representa-
              tion type", "file structure", and "transfer mode".

       pwd    Print the name of the current working directory  on  the  remote
              machine.

       quit   A synonym for bye.

       quote arg1 arg2 ...
              Send  the  arguments  specified,  verbatim,  to  the  remote FTP
              server.  A single FTP reply code is expected in return.

       recv remote-file [ local-file]
              A synonym for get.

       remotehelp [ command-name ]
              Request help from the remote FTP server.  If a  command-name  is
              specified it is supplied to the server as well.

       rename from to
              Rename the file from on the remote machine to have the name to.

       reset  Clear  reply  queue.  This command re-synchronizes command/reply
              sequencing with the remote FTP server.  Resynchronization may be
              necessary  following  a  violation  of  the  FTP protocol by the
              remote server.

       rmdir directory-name
              Delete a directory on the remote machine.

       runique
              Toggle storing of files on the local system  with  unique  file-
              names.  If a file already exists with a name equal to the target
              local filename for a get or mget command, a `.1' is appended  to
              the  name.  If the resulting name matches another existing file,
              a `.2' is appended to the original name.  If this  process  con-
              tinues  up to `.99', an error message is printed, and the trans-
              fer does not take place.  The generated unique filename will  be
              reported.   Note:  runique will not affect local files generated
              from a shell command (see below).  The default value is off.

       send local-file [ remote-file ]
              A synonym for put.

       sendport
              Toggle the use of PORT commands.  By default, ftp  will  attempt
              to  use  a  PORT command when establishing a connection for each
              data transfer.  The use of PORT commands can prevent delays when
              performing  multiple  file transfers. If the PORT command fails,
              ftp will use the default data port.  When the use of  PORT  com-
              mands  is disabled, no attempt will be made to use PORT commands
              for each data transfer.  This is useful when connected  to  cer-
              tain  FTP  implementations  that ignore PORT commands but incor-
              rectly indicate they have been accepted.

       status Show the current status of ftp.

       struct [ struct-name ]
              Set the "file structure" to struct-name.  The only valid struct-
              name is file, which corresponds to the default "file" structure.

       sunique
              Toggle  storing  of  files  on  remote machine under unique file
              names.  The remote FTP server must support the STOU command  for
              successful completion.  The remote server will report the unique
              name.  Default value is off.

       tenex  Set the "representation type" to that needed to  talk  to  TENEX
              machines.

       trace  Toggle packet tracing (unimplemented).

       type   [ type-name ]
              Set  the  "representation  type"  to type-name.  The valid type-
              names are  ascii  for  "network  ASCII",  binary  or  image  for
              "image",  and  tenex for "local byte size" with a byte size of 8
              (used to talk to TENEX machines).  If no type is specified,  the
              current type is printed.  The default type is "network ASCII".

       user user-name [ password ] [ account ]
              Identify  yourself to the remote FTP server.  If the password is
              not specified and the server requires it, ftp  will  prompt  the
              user  for  it (after disabling local echo).  If an account field
              is not specified, and the FTP server requires it, the user  will
              be  prompted  for  it.   If  an  account  field is specified, an
              account command will be relayed to the remote server  after  the
              login sequence is completed if the remote server did not require
              it for logging in.  Unless ftp is invoked with "auto-login" dis-
              abled,  this process is done automatically on initial connection
              to the FTP server.

       verbose
              Toggle verbose mode.  In verbose mode, all  responses  from  the
              FTP  server  are displayed to the user.  In addition, if verbose
              mode is on, when a file transfer completes, statistics regarding
              the  efficiency  of the transfer are reported.  By default, ver-
              bose mode is on if ftp's commands are coming  from  a  terminal,
              and off otherwise.

       ?  [ command ]
              A synonym for help.

       Command  arguments  which have embedded spaces may be quoted with quote
       (") marks.

       If any command argument which is not indicated as being optional is not
       specified, ftp will prompt for that argument.

ABORTING A FILE TRANSFER
       To abort a file transfer, use the terminal interrupt key (usually CTRL-
       C).  Sending transfers will be immediately halted.  Receiving transfers
       will  be  halted  by  sending a ftp protocol ABOR command to the remote
       server, and discarding any further data received.  The speed  at  which
       this  is accomplished depends upon the remote server's support for ABOR
       processing.  If the remote server does not support the ABOR command, an
       "ftp>"  prompt  will  not  appear until the remote server has completed
       sending the requested file.

       The terminal interrupt key sequence will be ignored when ftp  has  com-
       pleted  any  local  processing  and is awaiting a reply from the remote
       server.  A long delay in this mode may result from the ABOR  processing
       described  above,  or  from  unexpected  behavior by the remote server,
       including violations of the ftp protocol.  If the  delay  results  from
       unexpected remote server behavior, the local ftp program must be killed
       by hand.

FILE NAMING CONVENTIONS
       Local files specified  as  arguments  to  ftp  commands  are  processed
       according to the following rules.

       1)     If the file name `-' is specified, the standard input (for read-
              ing) or standard output (for writing) is used.

       2)     If the first character of the file name is `|', the remainder of
              the  argument is interpreted as a shell command.  ftp then forks
              a shell, using popen(3S) with the argument supplied,  and  reads
              (writes)  from  the  standard  output  (standard  input) of that
              shell.  If the shell  command  includes  SPACE  characters,  the
              argument  must  be quoted; for example `"| ls -lt"'.  A particu-
              larly useful example of this mechanism is: `dir | more'.

       3)     Failing the above checks, if "globbing" is enabled,  local  file
              names  are  expanded  according to the rules used in the csh(1);
              see the glob command.  If the ftp command expects a single local
              file  (for  example,  put), only the first filename generated by
              the "globbing" operation is used.

       4)     For mget commands and get commands with unspecified  local  file
              names,  the  local filename is the remote filename, which may be
              altered by a case, ntrans, or nmap setting.  The resulting file-
              name may then be altered if runique is on.

       5)     For  mput commands and put commands with unspecified remote file
              names, the remote filename is the local filename, which  may  be
              altered by a ntrans or nmap setting.  The resulting filename may
              then be altered by the remote server if sunique is on.

FILE TRANSFER PARAMETERS
       The FTP specification specifies many parameters which may affect a file
       transfer.

       The  "representation  type"  may  be  one of "network ASCII", "EBCDIC",
       "image", or "local byte size" with a specified byte size (for  PDP-10's
       and  PDP-20's  mostly).   The "network ASCII" and "EBCDIC" types have a
       further subtype which specifies whether vertical format  control  (NEW-
       LINE  characters,  form  feeds,  etc.)  are to be passed through ("non-
       print"), provided in TELNET format ("TELNET format controls"), or  pro-
       vided in ASA (FORTRAN) ("carriage control (ASA)") format.  ftp supports
       the "network ASCII" (subtype "non-print" only) and "image" types,  plus
       "local  byte  size"  with a byte size of 8 for communicating with TENEX
       machines.

       The "file structure" may  be  one  of  "file"  (no  record  structure),
       "record",  or  "page".   ftp  supports only the default value, which is
       "file".

       The "transfer mode" may be one of "stream", "block",  or  "compressed".
       ftp supports only the default value, which is "stream".

SEE ALSO
       csh(1), ls(1V), rcp(1C), tar(1), popen(3S), netrc(5), ftpd(8C)

BUGS
       Correct  execution of many commands depends upon proper behavior by the
       remote server.

       An error in the treatment of carriage returns in the 4.2 BSD code  han-
       dling  transfers  with  a  "representation type" of "network ASCII" has
       been corrected.  This correction may result in incorrect  transfers  of
       binary  files to and from 4.2 BSD servers using a "representation type"
       of "network ASCII".  Avoid this problem by using the "image" type.



                                15 January 1988                        FTP(1C)