ftp(1N) ftp(1N)NAME ftp - transfers files by using the DARPA Internet File Transfer Protocol (FTP) SYNOPSIS ftp [-d] [-g] [-i] [-n] [-v] [remote-system] ARGUMENTS -d Enables debugging. By default, debugging is disabled. You can also enable and disable debugging by running the debug command from the ftp command interpreter. -g Disables filename expansion. You can also enable and disable filename expansion by running the glob command from the ftp command interpreter. -i Enables or disables interactive prompting during multiple file transfers. You can also enable and disable prompting by running the prompt command from the ftp command interpreter. -n Disables the automatic login process, called ``auto login,'' that ftp normally performs upon initial connection. By default, auto login is enabled. See ``The Autologin Process'' later in the ``Description'' section for details. If you use this option, you can log in after connecting to the remote system by running the user command from the ftp command interpreter. remote-system Specifies the name of the remote system with which ftp is to connect. The value of remote-system can be the host name or the Internet address of a system that is reachable through an Ethernet connection. If you provide this argument, ftp immediately attempts to establish a connection to an FTP server on the specified system. If you do not provide this argument, ftp enters its command interpreter and waits for your commands. -v Causes ftp to display all responses from the remote system and report data-transfer statistics. You can also enable and disable this display by running the verbose command from the ftp command interpreter. DESCRIPTION ftp allows you to transfer files to and from a remote system by using the DARPA Internet File Transfer Protocol. To use ftp, your system must be running a kernel that includes the Berkeley networking software. Your interface to ftp is through its command interpreter. January 1992 1
ftp(1N) ftp(1N)The ftp Command Interpreter To indicate that it is waiting for you to enter a command, ftp displays this prompt: ftp> This section describes the commands that ftp recognizes. To preserve embedded spaces in command arguments, you can enclose the command in double quotation marks ("). Many of the ftp commands, such as bell and prompt, are ``toggle switches'' in the sense that running the command enables or disables the command, depending on the command's previous state. When you run one of these commands, ftp reports the new command state. ! [ command [ arg ... ] ] Runs an interactive shell on the local system. If you specify a command argument, it is taken to be a command to execute, and any arg arguments are passed as arguments to command. $ macro-name [ arg ... ] Runs the macro macro-name, as defined by the macdef command, described later in this list, or as defined in your .netrc file, described in ``The .netrc File'' later in the ``Description'' section. Arguments specified by arg arguments are not expanded before being passed to the macro. The macro processor interprets the dollar sign ($) and backslash (\) as special characters. A $ followed by one or more numbers is replaced by the corresponding argument on the macro invocation command line. A $ followed by an i tells the 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 \ to prevent special treatment of the $. ? [ command ] Acts as a synonym for the help command. account [ passwd ] Specifies a supplemental password, which may be required by a remote system for access to resources once you are successfully logged in. If you do not provide a passwd argument, ftp prompts for the account password and disables echoing as you enter the password. 2 January 1992
ftp(1N) ftp(1N)append local-file [ remote-file ] Appends a local file to a file on the remote system. If remote-file is not specified, the local filename is used in naming the remote file, after being altered by any ntrans or nmap setting. The file transfer is subject to the current settings for type, form, mode, and struct. ascii Sets the file-transfer type to network ASCII, which is the default. bell Enables or disables the sounding of a bell when each file transfer command completes. binary Sets the file transfer type to support binary image transfer. bye Disconnects from the remote server and exits ftp. Entering the end-of-file character (usually CONTROL-D) has the same effect. case Enables or disables case mapping during mget commands. When case is enabled, those filenames on the remote system whose letters are all uppercase are written on the local system with the letters mapped to lowercase. By default, case is disabled. cd remote-directory Changes the working directory on the remote system to the directory specified by remote-directory. cdup Changes the working directory on the remote system to the parent of the current working directory on the remote system. close Disconnects from the remote server and returns to the command interpreter. Any defined macros are erased. cr Enables or disables the stripping of carriage return characters during the retrieval of ASCII files. By default, cr is disabled. When the value of type is ascii, ftp interprets carriage return-newline sequences as record delimiters. When cr is enabled, ftp strips carriage returns from this sequence to conform with the UNIX single-newline record delimiter. Records on non-UNIX remote systems may contain single January 1992 3
ftp(1N) ftp(1N)newlines. When the value of type is ascii, ftp can distinguish these newlines from a record delimiter only when cr is disabled. debug [ debug-value ] Enables or disables debugging mode. By default, debug is disabled. The optional argument debug-value is an integer value that specifies a debugging level. The default value is 1; higher values cause ftp to display more detailed debugging information. When debugging is on, ftp displays each command sent to the remote system, preceded by this string: --> delete remote-file Deletes the file specified by remote-file on the remote system. dir [ remote-directory ] [ local-file ] Displays a list of the contents of the directory specified by remote-directory. If a local-file argument is specified, the output is placed in the file specified by local-file. If you do not specify a remote-directory argument, the contents of the current working directory on the remote system are displayed. If you do not specify a local-file argument, or if the value of local-file is a hyphen (-), the output is displayed on the terminal. disconnect Acts as a synonym for the close command. form format Sets the file-transfer form to format. The default format is file. get remote-file [ local-file ] Retrieves the remote file specified by remote-file and stores it on the local system. If you do not specify a local-file argument, the transferred file is given the same name that it has on the remote system, subject to alteration by the current case, ntrans, and nmap settings. The current settings for type, form, mode, and struct affect the file transfer. glob Enables or disables filename expansion for the mdelete, mget, and mput commands. When glob is disabled, the filename arguments are taken literally and not expanded. When glob is enabled, filename expansion for 4 January 1992
ftp(1N) ftp(1N)mput is done as in the C shell. For mdelete and mget, each remote filename is expanded separately on the remote system and the lists are not merged. Expansion of a directory name is likely to be different from expansion of the name of an ordinary file because the exact result depends on the foreign operating system and the FTP server. You can preview the filename expansion that will result by running this command: mls filename-argument ... - hash Enables or disables the display of a number sign (#) for each data block transferred. The size of a data block is 1024 bytes. By default, hash is disabled. help [ command ] Prints an informative message about the meaning of the command specified by command. If you do not specify a command argument, ftp displays a list of the ftp commands. lcd [ directory ] Changes the working directory on the local system. If you do not specify a directory argument, the working directory is changed to your home directory. ls [ remote-directory ] [ local-file ] Displays an abbreviated list of the contents of a directory on the remote system. If you do not specify a remote-directory argument, ftp displays the contents of the current working directory. If you do not specify a local-file argument, or if local-file is a hyphen (-), the output is displayed on the terminal. macdef macro-name Defines a macro and causes ftp to enter macro input mode. Lines that you subsequently enter are stored as the macro named by macro-name until you enter a null line to terminate macro input mode. You can use a total of at most 4096 characters to define at most 16 macros. Macros remain defined until you issue the close command. mdelete [ remote-file ... ] Deletes the files on the remote system specified by one or more remote-file arguments. mdir remote-file ... local-file Displays a list of the contents of the directories specified by one or more remote-file arguments. This command is similar to the dir command except that you can specify multiple remote-file arguments. If the January 1992 5
ftp(1N) ftp(1N)local-file argument is specified, the output is placed in the file specified by local-file. If prompt is enabled, ftp prompts you to verify that the last argument is indeed the target local file for receiving mdir output. If the value of local-file is a hyphen (-), the output is displayed on the terminal. mget remote-file ... Expands the files on the remote system specified by one or more remote-file arguments and does a get for each filename thus produced. See glob for details on filename expansion. Resulting filenames are then processed according to case, ntrans, and nmap settings. Files are transferred into the local working directory. The mget command is not meant to transfer entire directory subtrees of files. You can transfer a subtree by transferring a tar archive of the subtree in binary mode. mkdir directory-name Makes the directory specified by directory-name on the remote system. mls remote-file ... local-file Lists information about the files specified by one or more remote-file arguments and places the output in the file specified by local-file. If local-file is a hyphen (-), the output is displayed on the terminal. If prompt is enabled and local-file is not a hyphen, ftp prompts you to verify that the last argument is indeed the target local file for receiving mls output. mode [ mode-name ] Sets the file-transfer mode to the value specified by mode-name. The only supported mode is stream mode. mput local-file ... Expands the list of local files specified as local-file arguments and does a put operation for each file in the resulting list. See the description of glob earlier in this list, for details of filename expansion. Resulting filenames are then processed according to ntrans and nmap settings. The mput command is not meant to transfer entire directory subtrees of files. You can transfer a subtree by transferring a tar archive of the subtree in binary mode. nmap [ inpattern outpattern ] Sets or unsets the filename-mapping mechanism. If you 6 January 1992
ftp(1N) ftp(1N)do not specify any arguments, the filename-mapping mechanism is unset. If you specify arguments, remote filenames are mapped during execution of mput and put commands issued without a specified remote target filename, and local filenames are mapped during execution of mget commands and get commands issued without a specified local target filename. This command is useful when connecting to a non-UNIX remote system that has different file-naming conventions or practices. The mapping follows the pattern set by inpattern and outpattern. The value of inpattern is a template for incoming filenames, which may have already been processed according to the ntrans and case settings. 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. The outpattern argument 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, given an inpattern argument whose value is $1.$2 and the transfer of a remote file named mydata.data, $1 has the value mydata, and $2 has the value data. Given an outpattern argument whose value is [$1,$2].[$2,file] the output filename is myfile.data for input filenames myfile.data and myfile.data.old; myfile.file for the input filename myfile; and myfile.myfile for the input filename .myfile. You can include space characters in outpattern, as in this example: nmap $1 | sed "s/ *$//" > $1 Use the \ character to prevent special treatment of the $, [, ], and , characters. ntrans [ inchars [ outchars ] ] Sets or unsets the filename-character-translation January 1992 7
ftp(1N) ftp(1N)mechanism. If you do not specify any arguments, the filename-character-translation mechanism is unset. If you specify inchars and outchars arguments, characters in remote filenames are translated during execution of mput and put commands issued without a specified remote target filename, and characters in local filenames are translated during execution of mget and get commands issued without a specified local target filename. This command is useful when you are connecting to a non-UNIX remote system that has 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 filename. open remote-system [ port ] Establishes a connection to the FTP server running on the system specified by remote-system. If you supply an optional port number, ftp attempts to contact an FTP server at that port. If you do not disable auto login by invoking ftp with the -n option, ftp automatically attempts to log the user in to the FTP server. See ``The Autologin Process'' later in the ``Description'' section for details. prompt Enables or disables interactive prompting. By default, prompt is enabled. Interactive prompting occurs during multiple file-transfer operations operations to allow you to send or receive files selectively. If prompting is disabled, any mget or mput transfers all files, and any mdelete deletes all files. proxy ftp-command Executes 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 command to establish the secondary control connection. Enter the command proxy ? to see other ftp commands available on the secondary connection. The following commands behave differently when prefaced by proxy: open Does not define new macros during the auto-login process. close Does not erase existing macro definitions. 8 January 1992
ftp(1N) ftp(1N)get mget Transfer files from the host on the primary control connection to the host on the secondary control connection. put mput append Transfer files from the host on the secondary control connection to the host on the primary control connection. Third-party file transfers depend upon support of the File Transfer Protocol PASV command by the server on the secondary control connection. put local-file [ remote-file ] Sends a local file to the remote system. If you do not specify a remote-file argument, the local filename is used to name the remote file, after processing according to any ntrans or nmap settings. The file transfer is subject to the current settings for type, form, mode, and struct. pwd Displays the name of the current working directory on the remote system. quit Acts as a synonym for the bye command. quote arg ... Sends the arguments, specified by one or more arg arguments, to the remote FTP server. recv remote-file [ local-file ] Acts as a synonym for the get command. remotehelp [ command-name ] Displays a list of commands for which the remote FTP server can provide help. If you specify a command-name argument, the server responds with the help information for the specified command. rename [ current-name ] [ new-name ] Renames the file specified by current-name on the remote system to the name specified by new-name. reset Clears the reply queue. This command resynchronizes command and reply sequencing with the remote FTP server. Resynchronization may be necessary following a violation of the File Transfer Protocol by the remote server. January 1992 9
ftp(1N) ftp(1N)rmdir directory-name Deletes a directory on the remote system. runique Enables or disables the use of unique names to store files on the local system. By default, runique is disabled. When runique is enabled and a file already exists with a name equal to the target local filename for a get or mget command, the characters .1 are appended to the name. If that name matches another existing file, the characters .2 are appended to the original name, and so on, until ftp generates a unique name, in which case it displays the name on the terminal. If this process continues through .99, ftp displays an error message and the transfer does not take place. Note that runique does not affect local files generated from a shell command. send local-file [ remote-file ] Acts as a synonym for the put command. sendport Enables or disables the use of PORT commands. By default, ftp attempts to use a PORT command when establishing a connection for each data transfer. The use of PORT commands can prevent delays when you are performing multiple file-transfer operations. If the PORT command fails, ftp uses the default data port. When PORT commands are disabled, ftp makes no attempt to use PORT commands for each data transfer. This function is useful for certain FTP implementations that ignore PORT commands but indicate, incorrectly, that they have been accepted. status Shows the current status of the connection, including command settings. struct [ struct-name ] Sets the file-transfer structure to the value specified by struct-name. The only supported structure is the ``file'' structure. sunique Enables or disables the use of unique filenames when sending files to a remote system. By default, sunique is disabled. The remote FTP server must support the File Transfer Protocol STOU command to enable this command successfully. See runique for details. 10 January 1992
ftp(1N) ftp(1N)tenex Sets the file-transfer type to that needed for TENEX systems. trace Enables or disables packet tracing. By default, trace is disabled. type [ type-name ] Sets the file-transfer type to the value specified by type-name. The value of type-name can be ascii, binary, ebcdic, image, or tenex. The values binary and image are equivalent. If you do not specify a type-name argument, ftp displays the current type. By default, type is ASCII. user user-name [ password ] [ account ] Logs you in to the remote FTP server. If you do not specify a password argument and the server requires a password, ftp prompts for a password after disabling local echo. If you do not specify account and the FTP server requires an account name, ftp prompts for it. If you specify an account argument and the remote server does not require an account argument, ftp relays an ACCT command to the remote server after the login sequence is completed. Unless you disable auto login by using the -n option, this process occurs automatically when the connection to the FTP server is first established. verbose Enables or disables verbose mode. By default, verbose is enabled. In verbose mode, ftp displays all responses from the FTP server and displays file-transfer statistics. Note that when verbose is disabled, ftp does not display any responses from the FTP server, including the output for such commands as pwd. Stopping a File Transfer To stop sending a file transfer, send an interrupt, which is usually done by pressing CONTROL-C. Sending transfers are halted immediately. You can halt receiving transfers by sending a File Transfer Protocol ABOR command to the remote server and discarding any further data received. The speed at which this function 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 does not appear until the remote server has finished sending the requested file. January 1992 11
ftp(1N) ftp(1N)Interrupts are ignored when ftp has completed any local processing and is waiting for a reply from the remote server. A long delay while waiting may result from the ABOR processing just described or from unexpected behavior by the remote server, including violations of the File Transfer Protocol. If the delay results from unexpected remote server behavior, you can stop the local instance of ftp only by running the kill command. File-Naming Conventions Files specified as arguments to ftp commands are processed according to the following rules: 1. If the filename is a hyphen (-), the standard input and standard output are used for reading and writing, respectively. 2. If the first character of the filename is an exclamation mark (!), ftp interprets the remainder of the argument as a shell command. To run the command, ftp forks a shell, passes any specified arguments, and reads or writes from the standard output or standard input as necessary. If the shell command includes spaces, the argument must be quoted. Here is an example: "!ls -lt" 3. If the filename is not a hyphen and does not begin with an exclamation mark, and if filename expansion is enabled, local filenames are expanded according to the rules used in the C shell. See the glob command for details. If you use an ftp command that expects a single local file, such as put, only the first filename generated by filename expansion is used. 4. For mget and get commands with unspecified local filenames, the local filename is the remote filename, which may be altered by a case, ntrans, or nmap setting. The resulting filename may then be altered if runique is enabled. 5. For mput and put commands with unspecified remote filenames, 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 enabled. File-Transfer Parameters These parameters affect file transfer: type, mode, form, and struct. See the description of type in the ``Description'' section for its possible settings. This 12 January 1992
ftp(1N) ftp(1N)version of ftp supports only the default values for mode, form, and struct. The Autologin Process By default, when you use the remote-system argument on the ftp command line to specify the name of a remote system to connect to, ftp automatically prompts you for the login name that you want to use on the remote system. If, when prompted, you press RETURN, ftp uses your login name on the local system. Next, ftp prompts for a password. Some FTP servers also prompt for a second password. This sequence of prompts and responses is known as the auto-login process. If you have a .netrc file in your home directory and it contains an entry for the system specified by remote-system, ftp extends the auto-login process by using the entry to log you in automatically. See ``The .netrc File'' later in the ``Description'' section for details. Whether you have a netrc file or not, you can disable the auto-login process by running ftp with the -n option. In this case, use the open command to log in to the FTP server. The .netrc File The .netrc file contains login and initialization information used by the auto-login process. The file resides in your home directory and must be readable only by you. An entry in this file consists of these tokens, separated by a space, a tab, or a newline character: account string Specifies an additional account password. If this token is present, the auto-login process supplies the specified string if the remote server requires an additional account password, or the auto-login process initiates an account command if it does not. Not all FTP servers support this command. login login-name Specifies a login name on the remote system. If this token is present, the auto-login process initiates a login session using the specified name. macdef name Defines a macro. This token provides the same functionality as the ftp macdef command and causes the creation of a macro whose name is name. The macro definition begins with the next line in .netrc and continues until the auto-login process reads a null line. If you define a macro named init, it is automatically executed as the last step in the auto- login process. January 1992 13
ftp(1N) ftp(1N)machine remote-system Specifies the name of a remote system. The auto-login process searches the .netrc file for a machine token that matches the remote-system argument specified on the ftp command line or as an argument to the open command. Once a match is made, the system processes the subsequent .netrc tokens, stopping when another machine token is encountered or the end of the file is reached. password string Specifies a password. If this token is present, the auto-login process supplies the specified string if the remote server requires a password as part of the login process. Note that if this token is present in the .netrc file, ftp stops the auto-login process if the .netrc file is readable by anyone other than you. Anonymous FTP The FTP server prohibits logging in to an account that does not have a password. To make files available to anyone who can connect to the system, some system administrators set up the FTP server to allow logging in as anonymous or ftp, which are special login names for which any password is acceptable. If you log in anonymously, you are restricted to the home directory of the user ftp. See ftpd(1M) for details. EXAMPLES The first example illustrates a simple ftp connection and file transfer from the remote system to the local system. Long output lines have been folded for the sake of readability. ftp printms Connected to printms. 220 printms FTP server (Version 4.109 Fri Nov 20 07:43:57 PST 1987) ready. Name (printms:tim): 331 Password required for tim. Password: 230 User tim logged in. ftp> get tmac.an 200 PORT command successful. 150 Opening data connection for tmac.an (89.0.0.33,1205) (13366 bytes). 226 Transfer complete. local: tmac.an remote: tmac.an 13922 bytes received in 0.69 seconds (20 Kbytes/s) ftp> quit 221 Goodbye. 14 January 1992
ftp(1N) ftp(1N)The second example illustrates an ftp connection and a file transfer from the local system to the remote system. ftp printms Connected to printms. 220 printms FTP server (Version 4.109 Fri Nov 20 07:43:57 PST 1987) ready. Name (printms:tim): 331 Password required for tim. Password: 230 User tim logged in. ftp> put tmac.an 200 PORT command successful. 150 Opening data connection for tmac.an (89.0.0.33,1209). 226 Transfer complete. local: tmac.an remote: tmac.an 13922 bytes sent in 0.83 seconds (16 Kbytes/s) ftp> quit 221 Goodbye. The third example illustrates changing to a directory in the remote file system and listing the contents of several directories. ftp printms Connected to printms. 220 printms FTP server (Version 4.109 Fri Nov 20 07:43:57 PST 1987) ready. Name (printms:tim): 331 Password required for tim. Password: 230 User tim logged in. ftp> ls 200 PORT command successful. 150 Opening data connection for /bin/ls (89.0.0.33,1212) (0 bytes). OUT cutmks tmac.ap tmac.ptx tmac.syn tmac.toc 226 Transfer complete. 76 bytes received in 1.2 seconds (0.13 Kbytes/s) ftp> cd OUT 250 CWD command successful. ftp> ls 200 PORT command successful. 150 Opening data connection for /bin/ls (89.0.0.33,1213) (0 bytes). junk January 1992 15
ftp(1N) ftp(1N)226 Transfer complete. 4 bytes received in 0.058 seconds (3.9 Kbytes/s) ftp> close 221 Goodbye. ftp> quit LIMITATIONS Correct execution of many commands depends upon proper behavior by the remote server. An error in the treatment of returns in the 4.2 BSD UNIX ASCII-mode transfer code has been corrected. This correction may result in incorrect transfers of binary files to and from 4.2 BSD servers using the ascii type. You can avoid this problem by using the image or binary type. When verbose mode is disabled, ftp does not echo responses from the remote server or any responses to the pwd command. The FTP server disconnects any login sessions that have had no activity for a certain amount of time. The default period is 15 minutes. FILES /usr/bin/ftp Executable file /usr/spool/ftp/* File hierarchy to which, by convention, anonymous FTP users are restricted SEE ALSO csh(1), tar(1) ftpd(1M) in A/UX System Administrator's Reference A/UX Networking Essentials 16 January 1992