Please contact or Mt Xia for assistance with all your shell programming needs.
ftp(1) ftp(1) NAME ftp - Transfers files between a local and a remote host SYNOPSIS ftp [-dgintv] [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. FLAGS The following flags can be entered on the shell command line. (The the ftp command equivalents can also be entered at the ftp> prompt.) -d Enables debugging by turning on the logging feature. See the debug subcommand. -g Disables the expansion of metacharacters in filenames. Interpreting metacharacters may be referred to as expanding (sometimes called glob- bing) a filename. See the glob subcommand. -i Disables interactive prompting during multiple file transfers. See the prompt, mget, mput, and mdelete subcommands for descriptions of prompt- ing during multiple file transfers. -n Prevents an automatic login on the initial connection. Otherwise, ftp searches for a $HOME/.netrc entry that describes the login and initial- ization process for the remote host. See the user subcommand. -t Toggles packet tracing (see trace subcommand). -v 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 display. 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 flag or the verbose subcom- mand 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 attempt 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 OSF/1 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, transferring multiple files in a single request, creating and removing directories, and escaping to the local shell to perform shell commands. The ftp command also provides for security by sending passwords to the remote host and per- mits automatic login, file transfer, and logoff. If you execute ftp and do not specify a hostname, ftp immediately displays the ftp> prompt and waits for an ftp subcommand. To connect to a remote host, you then execute the open subcommand. When the ftp command connects to the remote host, ftp then prompts for the username and password before displaying the ftp> prompt again. ftp fails if no password is defined at the remote host for the specified username. 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 directory or home directory. If the file exists, ftp searches the file for an entry that initiates the login process and command macro definitions for the remote host. If the $HOME/.netrc file or autologin entry does not exist, ftp prompts you for a username and password. This occurs 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 defined 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 display- ing the ftp> prompt. Once ftp completes the autologin process, ftp exe- cutes the init macro if the macro is defined in the autologin entry. If the init macro does not exist or does not contain 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 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 command 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 follow- ing 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 | (vertical bar), the remainder of the argument is interpreted as a shell command. ftp then forks a shell, using popen() with the argument supplied, and reads (writes) from stdout (stdin). If the shell command includes 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; c.f., 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. ++ For get and mget subcommands with unspecified local filenames, the local filename is the same as the remote filename, which may be altered by a case, ntrans, or nmap setting. The resulting filename can then be altered if runique is on. ++ For mput commands and put commands with unspecified remote filenames, the remote filename is the same as the local 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
. 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 requested file. Additionally, if the remote server does something unexpected, 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: ftp-control Low delay ftp-data 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). ![command [argument ...]] Invokes an interactive shell on the local host. An optional command, with one or more optional arguments, can be specified. $ macro [argument ...] Executes the specified macro, previously defined with the macdef sub- command. Arguments are not expanded. See the macdef subcommand for further information. ? [subcommand] Displays a help message describing the subcommand. If you do not specify subcommand, ftp displays a list of known subcommands. append local_file [remote_file] 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 append- ing the file. For more information on these subcommands, see their individual descriptions. ascii 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 sys- tem. File transfer may be more efficient with binary-image transfer. bell Sounds a bell after the completion of each file transfer. binary 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. bye Ends the File Transfer session and exits ftp. Same as quit. case 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 lowercase when written in the local directory. The default is off (uppercase remote filenames are written in uppercase in the local directory). cd remote_directory Changes the remote working directory to the specified directory. cdup Changes the working directory on the remote host to the parent of the current directory. close Ends the File Transfer session, but does not exit ftp. Defined macros are erased. Same as disconnect. cr Strips the carriage-return character from a carriage-return/linefeed sequence when receiving records during ASCII-type file transfers. (ftp terminates each ASCII-type record with a carriage-return/linefeed sequence during file transfers.) This conforms with the OSF/1 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. cr toggles between on and off. delete remote_file Deletes the specified remote file. debug [on | off] Prints each command sent to the remote host preceded by the string --> when debug on is specified. dir [remote_directory][local_file] Writes a listing of the contents of remote_directory to the file local_file. If remote_directory is not specified, dir lists the con- tents of the current remote directory. If local_file is not specified or is a - (dash), dir displays the listing on the local terminal. disconnect See close. form format Specifies the form of the file transfer. The only format available is non-print. get remote_file [local_file] Copies the remote file to the local host. If local_file is not speci- fied, the remote filename is used locally and is altered by any set- tings made by the case, ntrans, and nmap subcommands. The ftp command uses the current settings for type, form, mode, and struct while transferring the file. For additional information, refer to the description of each of these subcommands. glob Toggles filename expansion (globbing) for mdelete, mget, and mput. If globbing is off, filename arguments for these subcommands are not expanded. When globbing is enabled and a pattern-matching character is used in a subcommand that expects a single filename, results may be different than expected. For example, the append and put subcommands perform filename expansion and then use only the first filename gen- erated. 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 directory 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. hash Toggles # (hash sign) printing. When hash is on, ftp displays one hash sign for each data block (1024 bytes) transferred. help [subcommand] Displays help information. Refer to the ? subcommand. lcd [directory] Changes the working directory on the local host. If you do not specify a directory, ftp uses your home directory. ls [remote_directory] [local_file] Writes an abbreviated file listing of a remote directory to a local file. If remote_directory is not specified, ftp lists the current remote directory. If local_file is not specified or is a - (dash), ftp displays the listing on the local terminal. macdef macro 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 executed. 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 invocation line (refer to the $ subcommand). A $ followed by an i indicates 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 parame- ter is used on the second pass, and so on. A \ prevents special treat- ment of the next character. Use the \ to turn off the special meanings of $ and \. mdelete remote_files Expands remote_files and deletes the indicated remote files. mdir [remote_directory ... local_file] Expands remote_directory at the remote host and writes a listing of the contents of the remote_directory to the local_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 interactive 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. mget remote_file ... 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 information on filename expansion. The remote filenames are used locally 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 addi- tional information. mkdir [remote_directory] Creates the directory remote_directory on the remote host. mls [remote_directory ... local_file] Expands remote_directory at the remote host and writes an abbreviated file listing of the indicated remote directories to a local file. If the remote_directory argument contains a pattern-matching character, mls 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 -, mls displays the listing on the local terminal. If interactive 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. mode [mode] Sets file transfer mode. The only mode available is stream. modtime [remote_file] Shows the last modification time of file on the remote machine. mput [local_file ...] Expands local_file at the local host and copies the indicated local files to the remote host. Refer to the glob subcommand for more infor- mation 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 additional information. nlist [remote_directory] [local_file] 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. nmap [inpattern outpattern] 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 operations and for get and put operations when the destination filename is not specified. This subcommand is useful when the local and remote hosts use different filenaming conventions or practices. Mapping follows the pattern set by inpattern and outpattern. The inpattern variable specifies the template for incoming filenames, 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 exam- ple, 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 vari- ables $1 through $9 are replaced by their values as derived from inpat- tern and the variable $0 is replaced by the original filename. Addi- tionally, 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 example, the following subcommand would yield myfile.data from myfile.data or myfile.data.old, myfile.file from myfile, and myfile.myfile from .myfile: 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 outpat- tern. ntrans [in_characters [out_characters]] Sets or unsets the filename character translation mechanism. If no arguments are specified, character translation is turned off. If argu- ments are specified, characters in source filenames are translated for mget and mput operations and for get and put operations when the desti- nation filename 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_characters and out_characters. Characters in a source filename matching charac- ters in in_characters are replaced by the corresponding characters in out_characters. If the string in_characters is longer than the string out_characters, characters in in_characters are deleted if they have no corresponding character in out_characters. open host [port] 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. prompt Toggles interactive prompting. If interactive prompting is on (the default), ftp will prompt for verification before retrieving, sending, or deleting multiple files during mget, mput, and mdelete operations. Otherwise, ftp will perform the operation on all files specified. proxy [subcommand] Executes an ftp command on a secondary control connection. This sub- command 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 subcom- mand. Enter the subcommand proxy ? to see the other ftp subcommands that are executable on the secondary connection. The following subcom- mands behave differently when prefaced by proxy: ++ The open subcommand does not define new macros during the autologin process. ++ The close subcommand does not erase existing macro definitions. ++ The get and mget subcommands transfer files from the host on the pri- mary 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. put local_file [remote_file] 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 information. pwd Displays the name of the current directory on the remote host. quit Ends the file transfer session and exits ftp. A synonym for bye. quote string Sends the specified string verbatim to the remote host. Unpredictable results can occur when you quote commands that involve data transfers. recv remote_file [local_file] Copies the remote file to the local host. A synonym for get. reget remote_file [local_file] 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 failure. This subcommand is useful when transferring very large files over networks that are prone to dropping connections. remotehelp [subcommand] Requests help from the remote FTP server. rename from to Renames a file on the remote host. reset Clears the reply queue. This command resynchronizes the command pars- ing. restart marker Restarts the immediately following get or put at the indicated marker. On systems that treat files as unstructured byte arrays (such as OSF/1 and UNIX systems), marker is simply a byte offset into the file. rmdir remote_directory Removes the directory remote_directory at the remote host. runique Toggles whether unique filenames are created for local destination files during get and mget operations. If creating unique local filenames 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 destina- tion file with .1. If a local file is already using the new name, ftp appends the postfix .2 to the specified name. If a local file is already using this second name, ftp continues incrementing the postfix until it either finds a unique filename or reaches .99 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 generated from a shell command. send local_file [remote_file] Stores a local file on the remote host. A synonym for put. sendport Toggles the use of FTP PORT instructions. By default, ftp uses a PORT instruction when establishing 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. size Returns the size of file on the remote machine in bytes. status Displays current status of ftp. struct [structure] Sets data transfer structure type. The only structure supported is file. sunique 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 overwrites 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. system Shows the type of operating system running on the remote machine. tenex Sets the file transfer type to that needed for TENEX machines. trace Toggles packet tracing. type [type] Sets the file transfer type to type. If type is not specified, the current type is printed. The default type is ASCII. user user [password] [account] Identifies the local user as user to the remote FTP server. If pass- word 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. verbose Toggles verbose 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 com- pleted. Aborting a File Transfer To abort a file transfer, use the Interrupt key sequence (often ). Sending transfers are immediately halted. Receiving transfers are halted by sending an FTP protocol ABOR command to the remote server, and discard- ing 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 pro- cessing 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. EXAMPLES 1. 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 ses- sion. $ 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 message 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 subcommand 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 connection for /usr/bin/ls (518.104.22.1685) (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 following 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 connection for testfile (522.214.171.1245) (1201 bytes) 226 Transfer complete. local: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. 2. 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 Password: 230 User smith logged in ftp> 3. 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> 4. 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 Password: 230 User fred logged in ftp> FILES $HOME/.netrc Contains automatic login information. RELATED INFORMATION Commands: csh(1), ftpd(8), rcp(1), stty(1), tftp(1) Functions: popen(3) Files: netrc(4), iptos(4).