*** UNIX MANUAL PAGE BROWSER ***

ftp(1) General Commands Manual ftp(1) NAME ftp - Transfers files between a local and a remote host SYNOPSIS ftp [-dginptv] [host] The ftp command is the interface to the File Transfer Protocol (FTP). This command uses FTP to transfer files between the local host and a remote host or between two remote hosts. OPTIONS The following options can be entered on the shell command line. (The ftp command equivalents can also be entered at the ftp> prompt.) En- ables debugging by turning on the logging feature. See the debug sub- command. Disables the expansion of metacharacters in filenames. Inter- preting metacharacters may be referred to as expanding (sometimes called globbing) a filename. See the glob subcommand. Disables inter- active prompting during multiple file transfers. See the prompt, mget, mput, and mdelete subcommands for descriptions of prompting during mul- tiple file transfers. Prevents an automatic login on the initial con- nection. Otherwise, ftp searches for a $HOME/.netrc entry that de- scribes the login and initialization process for the remote host. See the user subcommand. Enables the interpretation of the vertical bar (|) as a pipe symbol when it is the first character in a file name. See the pipe subcommand. Toggles packet tracing (see trace subcom- mand). Displays all the responses from the remote server and provides data transfer statistics. This is the default display mode when the output of the ftp command is to a device, such as the console or a dis- play. However, if output is redirected, such as through a pipe or to a file, or if the ftp command is started by a daemon, such as the cron daemon, verbose mode is not in effect unless the -v option or the ver- bose subcommand is used. See the verbose subcommand. DESCRIPTION The FTP protocol is designed to allow transferring data between hosts that use dissimilar file systems. Therefore, although the protocol provides a lot of flexibility for transferring data, it does not at- tempt to preserve file attributes that are specific to a particular file system (for example, the protection mode or modification times of a file). Additionally, the FTP protocol makes few assumptions about the overall structure of a file system and does not provide or allow such things as recursively copying subdirectories. Note that if you are transferring files between DIGITAL UNIX systems (or other systems compatible with the UNIX operating system) and need to preserve file attributes or need to recursively copy subdirectories, you can use the rcp command. The ftp command provides subcommands for tasks such as listing remote directories, changing the current local and remote directory, transfer- ring multiple files in a single request, creating and removing directo- ries, and escaping to the local shell to perform shell commands. The ftp command also provides for security by sending passwords to the re- mote host and permits automatic login, file transfer, and logoff. If you execute ftp and do not specify a hostname, ftp immediately dis- plays the ftp> prompt and waits for an ftp subcommand. To connect to a remote host, you then execute the open subcommand. When the ftp com- mand connects to the remote host, ftp then prompts for the username and password before displaying the ftp> prompt again. The ftp command fails if no password is defined at the remote host for the specified user- name. If you do specify the name of a remote host, ftp immediately tries to establish a connection to the specified host. If ftp connects success- fully, ftp searches for a local $HOME/.netrc file in your current di- rectory or home directory. If the file exists, ftp searches the file for an entry that initiates the login process and command macro defini- tions for the remote host. If the $HOME/.netrc file or autologin entry does not exist, ftp prompts you for a username and password. This oc- curs whether or not the hostname is entered on the command line. If ftp finds a $HOME/.netrc autologin entry for the specified host, ftp attempts to use the information in that entry to automatically log in to the remote host. The ftp command also loads any command macros de- fined in the entry. In some cases (for example, when the required password is not listed in an autologin entry), ftp prompts for the password before displaying the ftp> prompt. Once ftp completes the au- tologin process, ftp executes the init macro if the macro is defined in the autologin entry. If the init macro does not exist or does not con- tain a quit or bye command, ftp then displays the ftp> prompt and waits for a subcommand. The remote username that you specify either at the prompt or in a $HOME/.netrc file must exist and have a password defined at the remote host or ftp fails. In addition, the remote user's shell must be listed in the /etc/shells file. Users are authenticated as described in ftpd(8). The ftpd(8) reference page also describes anonymous FTP configuration. The ftp command interpreter, which handles all commands entered at the ftp> prompt, provides facilities that are not available with most file transfer programs, such as: the handling of filename arguments to ftp commands, the ability to collect a group of commands into a single com- mand macro, and the ability to load macros from a $HOME/.netrc file. These facilities are designed to allow simplifying repeated tasks and to allow using ftp in unattended mode. The command interpreter handles filename arguments according to the following rules: If a - (dash) is specified for the argument, standard input is used for read operations and standard output is used for write operations. If the first character of the filename is a vertical bar (|), the remainder of the argument is interpreted as a shell command. The ftp command then forks a shell, using popen() with the argument supplied, and reads (writes) from stdout (stdin). By default, this feature is disabled. See the pipe subcommand. If the shell command in- cludes spaces, the argument must be quoted; for example, | ls -lt. A particularly useful example of this mechanism is dir |more. Failing the above checks, if globbing is enabled, local filenames are expanded according to the rules used in csh; see the glob subcommand. If the ftp command expects a single local file (for example, put), only the first filename generated by the globbing operation is used. For get and mget subcommands with unspecified local filenames, the local file- name is the same as the remote filename, which may be altered by a case, ntrans, or nmap setting. The resulting filename can then be al- tered if runique is on. For mput commands and put commands with un- specified remote filenames, the remote filename is the same as the lo- cal filename, which can be altered by a ntrans or nmap setting. The resulting filename can then be altered by the remote server if sunique is on. Note that the ftp command interpreter does not support pipes. To end an ftp session when you are running interactively, use the bye or quit subcommand or the End-of-File key sequence at the ftp> prompt. To end a file transfer before it has been completed, use the Interrupt key sequence. The default Interrupt key sequence is <Ctrl-c>. The stty command can be used to redefine this key sequence. Sending transfers (those from the local host to the remote host) are normally halted immediately. Receiving transfers are halted by sending an FTP ABOR instruction to the remote FTP server and discarding all incoming file transfer packets until the remote server stops sending them. If the remote server does not support the ABOR instruction, the ftp> prompt will not appear until the remote server has sent all of the re- quested file. Additionally, if the remote server does something unex- pected, the local ftp process may need to be ended manually. The ftp command uses the default Type-of-Service values recommended by RFC1060, which are as follows: Low delay High throughput You can configure these values by specifying them in the /etc/iptos file. For more information, see iptos(4). SUBCOMMANDS The following ftp subcommands can be entered at the ftp> prompt. If an argument for a subcommand includes spaces, enclose the argument within (double quotes). Invokes an interactive shell on the local host. An optional command, with one or more optional arguments, can be speci- fied. Executes the specified macro, previously defined with the macdef subcommand. Arguments are not expanded. See the macdef subcommand for further information. Displays a help message describing the subcom- mand. If you do not specify subcommand, ftp displays a list of known subcommands. Sends a supplemental password that a remote host may re- quire before granting access to its resources. If the password is not supplied with the command, you are prompted for the password. The pass- word does not appear on the screen. Appends a local file to a file on the remote host. If the remote filename is not specified, the local filename is used, altered by any setting made with the ntrans or nmap subcommand. The append subcommand uses the current values for form, mode, struct, and type while appending the file. For more information on these subcommands, see their individual descriptions. Sets the file transfer type to network ASCII. This ft command is the default when ftp cannot determine that the remote system is a UNIX system. File transfer may be more efficient with binary-image transfer. Sounds a bell after the completion of each file transfer. Sets the file transfer type to binary image, by default, if ftp can determine that the remote system is a UNIX system. This can be more efficient than an ASCII transfer. Ends the File Transfer session and exits ftp. Same as quit. Sets a toggle for the case of filenames. When case is on, remote filenames that appear in all capital letters are changed from uppercase to lower- case when written in the local directory. The default is off (uppercase remote filenames are written in uppercase in the local directory). Changes the remote working directory to the specified directory. Changes the working directory on the remote host to the parent of the current directory. Ends the File Transfer session, but does not exit ftp. Defined macros are erased. Same as disconnect. Strips the car- riage-return character from a carriage-return/linefeed sequence when receiving records during ASCII-type file transfers. (The ftp command terminates each ASCII-type record with a carriage-return/linefeed se- quence during file transfers.) This conforms with the DIGITAL UNIX and UNIX system convention for terminating records with a single linefeed. Records on remote hosts that have different record termination conven- tions may have single linefeeds imbedded in records. To distinguish these imbedded linefeeds from record delimiters, set cr to off. The cr subcommand toggles between on and off. Deletes the specified remote file. Prints each command sent to the remote host preceded by the string --> when debug on is specified. Writes a listing of the con- tents of remote_directory to the file local_file. If remote_directory is not specified, dir lists the contents of the current remote direc- tory. If local_file is not specified or is a - (dash), dir displays the listing on the local terminal. See close. Specifies the form of the file transfer. The only format available is non-print. Copies the remote file to the local host. If local_file is not specified, the re- mote filename is used locally and is altered by any settings made by the case, ntrans, and nmap subcommands. The ftp command uses the cur- rent settings for type, form, mode, and struct while transferring the file. For additional information, refer to the description of each of these subcommands. Toggles filename expansion (globbing) for mdelete, mget, and mput. If globbing is off, filename arguments for these sub- commands are not expanded. When globbing is enabled and a pattern- matching character is used in a subcommand that expects a single file- name, results may be different than expected. For example, the append and put subcommands perform filename expansion and then use only the first filename generated. Other ftp subcommands, such as cd, delete, get, mkdir, rename, and rmdir, do not perform filename expansion and take the pattern-matching characters literally. Globbing for the mput subcommand is done locally in the same way as for the csh command. For mdelete and mget, each filename is expanded separately at the remote machine and the lists are not merged. The expansion of a directory name may be different than the expansion of a filename, depending on the remote host and the ftp server. To preview the expansion of a di- rectory name, use the mls subcommand: mls remote_file - To transfer an entire directory subtree of files, transfer a tar archive of the subtree in binary form, rather than using mget or mput. Toggles # (hash sign) printing. When hash is on, ftp displays one hash sign for each data block (1024 bytes) trans- ferred. Displays help information. Refer to the ? subcommand. Changes the working directory on the local host. If you do not specify a directory, ftp uses your home directory. Writes an abbreviated file listing of a remote directory to a local file. If remote_directory is not specified, ftp lists the current re- mote directory. If local_file is not specified or is a - (dash), ftp displays the listing on the local terminal. Defines a subcommand macro. Subsequent lines up to a null line (two consecutive linefeeds) are saved as the text of the macro. Up to 16 macros containing at most 4096 bytes for all macros can be defined. Macros remain defined until redefined or a close is ex- ecuted. The special characters $ (dollar sign) and \ (backslash) have special uses in ftp macros. A $ followed by one or more numbers is replaced by the corresponding macro parameter on the invoca- tion line (refer to the $ subcommand). A $ followed by an i in- dicates that the macro is to loop, with $i being replaced by consecutive parameters on each pass. The first macro parameter is used on the first pass, the second parameter is used on the second pass, and so on. A \ prevents special treatment of the next character. Use the \ to turn off the special meanings of $ and \. Expands remote_files and deletes the indicated remote files. Expands remote_directory at the remote host and writes a listing of the contents of the remote_directory to the lo- cal_file. If the remote_directory argument contains a pattern- matching character, mdir prompts for a local_file if none is specified. If the remote_directory argument is a list of remote directories, separated by spaces, the last argument in the list must be either a local filename or a - (dash). If local_file is -, mdir displays the listing on the local terminal. If interac- tive prompting is on (refer to the prompt subcommand), ftp prompts you to verify that the last argument is a local file and not a remote directory. Expands remote_files at the remote host and copies the indicated remote files to the current directory on the local host. Refer to the glob subcommand for more infor- mation on filename expansion. The remote filenames are used lo- cally and are altered by any settings made by the case, ntrans, and nmap subcommands. The ftp command uses the current settings for type, form, mode, and structure while transferring the files. Refer to the description of each of these subcommands for additional information. Creates the directory remote_direc- tory on the remote host. Expands remote_directory at the remote host and writes an abbreviated file listing of the indicated re- mote directories to a local file. If the remote_directory argu- ment contains a pattern-matching character, mls prompts for a local_file if none is specified. If the remote_directory argu- ment is a list of remote directories, separated by spaces, the last argument in the list must be either a local filename or a - (dash). If local_file is -, mls displays the listing on the lo- cal terminal. If interactive prompting is on (refer to the prompt subcommand), ftp prompts you to verify that the last ar- gument is a local file and not a remote directory. Sets file transfer mode. The only mode available is stream. Shows the last modification time of file on the remote machine. Expands local_file at the local host and copies the indicated local files to the remote host. Refer to the glob subcommand for more information on filename expansion. The local filenames are used at the remote host and are altered by any settings made by the ntrans and nmap subcommands. The ftp command uses the current settings for type, form, mode, and structure while transferring the files. Refer to the description of each subcommand for addi- tional information. Prints a list of the files of a directory on the remote machine. If remote_directory is left unspecified, the current working directory is used. If interactive prompting is on, ftp prompts the user to verify that the last argument is indeed the target local file for receiving nlist output. If no local file is specified, the output is sent to the terminal. Sets or unsets the filename mapping mechanism. If no arguments are specified, filename mapping is turned off. If arguments are specified, source filenames are mapped for mget and mput opera- tions and for get and put operations when the destination file- name is not specified. This subcommand is useful when the local and remote hosts use different filenaming conventions or prac- tices. Mapping follows the pattern set by inpattern and outpat- tern. The inpattern variable specifies the template for incoming file- names, which may have already been processed according to the case and ntrans settings. The template variables $1 through $9 can be included in inpattern. All characters in inpattern other than $ and protected $s (that is, \$) define the values of the template variables. For example, if the inpattern is $1.$2 and the remote filename is mydata.dat, the value of $1 is mydata and the value of $2 is dat. The outpattern variable determines the resulting filename. The variables $1 through $9 are replaced by their values as derived from inpattern and the variable $0 is replaced by the original filename. Additionally, the sequence [sequence1,sequence2] is replaced by the value of sequence1 if sequence1 is not null; otherwise, it is replaced by the value of sequence2. For exam- ple, the following subcommand would yield myfile.data from my- file.data or myfile.data.old, myfile.file from myfile, and my- file.myfile from nmap $1.$2.$3 [$1,$2].[$2,file] Spaces can be included in outpattern. Use the \ (backslash) character to prevent the special meanings of $, [, ], and , (comma) in outpattern. Sets or unsets the filename character translation mechanism. If no arguments are specified, character translation is turned off. If arguments are specified, charac- ters in source filenames are translated for mget and mput opera- tions and for get and put operations when the destination file- name is not specified. This subcommand is useful when the local and remote hosts use different file naming conventions or prac- tices. Character translation follows the pattern set by in_char- acters and out_characters. Characters in a source filename matching characters in in_characters are replaced by the corre- sponding characters in out_characters. If the string in_charac- ters is longer than the string out_characters, characters in in_characters are deleted if they have no corresponding charac- ter in out_characters. Establishes a connection to the FTP server at the specified host. If the optional port number is specified, ftp will attempt to connect to a server at that port. If the autologin feature is set (that is, -n was not specified on the command line), ftp will attempt to automatically log you in to the FTP server. You must also have a $HOME/.netrc file with the correct information in it and the correct permissions set. Toggles the interpretation of the vertical bar (|) as the pipe symbol when it is the first character in a file name. If the interpretation is off (the default), the vertical bar is in- terpreted as a regular character and has no special meaning. Otherwise, the vertical bar (|) indicates that the remainder of the argument is interpreted as a shell command. Toggles inter- active prompting. If interactive prompting is on (the default), ftp prompts for verification before retrieving, sending, or deleting multiple files during mget, mput, and mdelete opera- tions. Otherwise, ftp will perform the operation on all files specified. Executes an ftp command on a secondary control con- nection. This subcommand allows ftp to simultaneously connect to two remote FTP servers for transferring files between the two servers. To establish the secondary control connection, specify open as the first proxy subcommand. Enter the subcommand proxy ? to see the other ftp subcommands that are executable on the secondary connection. The following subcommands behave differ- ently when prefaced by proxy: The open subcommand does not de- fine new macros during the autologin process. The close subcom- mand does not erase existing macro definitions. The get and mget subcommands transfer files from the host on the primary connection to the host on the secondary connection. The put, mput, and append subcommands transfer files from the host on the secondary connection to the host on the primary connection. File transfers require that the FTP server on the secondary connec- tion support the PASV (passive) instruction. Stores a local file on the remote host. If you do not specify remote_file, ftp uses the local filename to name the remote file, and the remote filename is altered by any settings made by the ntrans and nmap subcommands. The ftp command uses the current settings for type, form, mode, and structure while transferring the files. Refer to the description of each subcommand for additional in- formation. Displays the name of the current directory on the remote host. Ends the file transfer session and exits ftp. A synonym for bye. Sends the specified string verbatim to the re- mote host. Unpredictable results can occur when you quote com- mands that involve data transfers. Copies the remote file to the local host. A synonym for get. Acts like get, except that if local_file exists and is smaller than remote_file, local_file is presumed to be a partially transferred copy of remote_file and the transfer is continued from the apparent point of fail- ure. This subcommand is useful when transferring very large files over networks that are prone to dropping connections. Re- quests help from the remote FTP server. Renames a file on the remote host. Clears the reply queue. This command resynchro- nizes the command parsing. Restarts the immediately following get or put at the indicated marker. On systems that treat files as unstructured byte arrays (such as DIGITAL UNIX and UNIX sys- tems), marker is simply a byte offset into the file. Removes the directory remote_directory at the remote host. Toggles whether unique filenames are created for local destination files during get and mget operations. If creating unique local file- names is not enabled (the default), ftp overwrites local files. Otherwise, if a local file has the same name as specified for a local destination file, ftp modifies the specified name of the local destination file with If a local file is already using the new name, ftp appends the postfix to the specified name. If a local file is already using this second name, ftp continues in- crementing the postfix until it either finds a unique filename or reaches without finding a unique name. If ftp cannot find a unique name, ftp reports an error and the transfer does not take place. Note that runique does not affect local filenames gener- ated from a shell command. Stores a local file on the remote host. A synonym for put. Toggles the use of FTP PORT instruc- tions. By default, ftp uses a PORT instruction when establish- ing a connection for each data transfer. When the use of PORT instructions is disabled, ftp does not use PORT instructions for data transfers. The PORT instruction is useful when dealing with FTP servers that ignore PORT instructions while incorrectly indicating they were accepted. Returns the size of file on the remote machine in bytes. Displays current status of ftp. Sets data transfer structure type. The only structure supported is file. Toggles whether unique filenames are created for remote destination files during put and mput operations. If creating unique remote filenames is not enabled (the default), ftp over- writes remote files. Otherwise, if a remote file has the same name as specified for a remote destination file, the remote FTP server modifies the name of the remote destination file. Note that the remote server must support the STOU instruction. Shows the type of operating system running on the remote machine. Sets the file transfer type to that needed for TENEX machines. Toggles packet tracing. Sets the file transfer type to type. If type is not specified, the current type is printed. The de- fault type is ASCII. Identifies the local user as user to the remote FTP server. If password or account is not specified and the remote server requires it, ftp prompts for it locally. If account is required, ftp sends it to the remote server after the remote login process completes. Note that, unless autologin is disabled by specifying -n on the command line, this process is done automatically for the initial connection to the remote server. You also need a $HOME/.netrc file in your home directory to issue an autologin. Toggles ver- bose mode. When verbose mode is on (the default), ftp displays all responses from the remote FTP server. Additionally, ftp displays statistics on all file transfers when the transfers are completed. Aborting a File Transfer To abort a file transfer, use the Interrupt key sequence (often <Ctrl- c>). Sending transfers are immediately halted. Receiving transfers are halted by sending an 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, the prompt ftp> does not appear until the remote server has completed sending the requested file. The Interrupt key sequence is ignored when ftp has completed any local processing and is awaiting a reply from the remote server. A long de- lay 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. EXAMPLES This example shows how user smith, who is logged in on host1, can log in on the remote host host2, check the current working directory on host2 and list its contents, transfer a file, and then end the session. $ ftp host2 If the connection to host2 is successful, a verification message is displayed on the local system: Connected to host2.abc.org 220 host2 FTP server (Version ...) ready. Name (host2:smith): smith Password: Enter your name and password when prompted by the system. A mes- sage similar to the following is then displayed on your local system: 230 User smith logged in ftp> _ To set the file transfer type to binary, enter the binary sub- command after the ftp> prompt: ftp> binary A message similar to the following is displayed on your local system: 200 Type set to I To check the current working directory, enter the pwd command after the ftp> prompt: ftp> pwd A message similar to the following is displayed on your local system: 257 "u/smith" is current directory To list the contents of the current working directory, enter the ls command after the ftp> prompt: ftp> ls A message similar to the following is displayed on your local system: 200 PORT command successful. 150 Opening data connec- tion for /usr/bin/ls (555.5.55.555) (0 bytes) printfile testfile 226 Transfer complete. (The Opening data connection message appears on one line, not on two lines as shown above.) To transfer a file from the remote host to the local host, enter the get or mget subcommand follow- ing the ftp> prompt: ftp> get testfile tmp.testfile A message similar to the following is displayed on your local system: 200 PORT command successful. 150 Opening data connec- tion for testfile (555.5.55.555) (1201 bytes) 226 Transfer complete. lo- cal:tmp.testfile remote:testfile (The Opening data connection message appears on one line, not on two lines as shown above.) To end the ftp session, enter the quit subcommand after the ftp> prompt: ftp> quit 221 Goodbye. $ _ This example shows how user smith, who is logged in on host1, can log in as the user smith on the remote host host2: $ ftp host2 Connected to host2.abc.org 220 host2 FTP server (Version ...) ready. Name (host2:smith): 331 Passwd required for smith Pass- word: 230 User smith logged in ftp> In this example, user smith makes a typing error: $ ftp test Connected to test.abc.org 220 test FTP server (Version ...) ready. Name (test:fred): msith 530 User msith unknown ftp> user smith 331 Passwd required for smith Password: 230 User smith logged in ftp> In this example, user fred issues the ftp command without specifying a hostname, then connects to host1 using the open subcommand: $ ftp ftp> open host1 Connected to host1.abc.org 220 host1 FTP server (Version ...) ready. Name (host1:fred): 331 Passwd required for fred Pass- word: 230 User fred logged in ftp> FILES Contains automatic login information. SEE ALSO Commands: csh(1), rcp(1), stty(1), tftp(1), ftpd(8) Functions: popen(3) Files: iptos(4), netrc(4) ftp(1)