ftp

ARPANET file transfer program

Syntax:

ftp [-d] [-g] [-i] [-n] [-v] [host]

Options:

-d
Enable debugging.
-g
Disable filename globbing.
-i
Don't perform interactive prompting during multiple file transfers.
-n
Don't attempt ``autologin'' upon initial connection.

If autologin is enabled, ftp checks the .netrc file (see below) in your home directory for an entry describing an account on the remote machine.

If no entry exists, ftp prompts for the login name of the remote machine (default is the user ID on the local machine) and, if necessary, for a password and an account.

-v
Be verbose: show all responses from the remote server and report on data-transfer statistics.
host
An Internet address specified in dot notation or a host name.

Description:

The ftp utility is the user interface to the ARPANET-standard File Transfer Protocol. With this utility, you can transfer files to and from a remote network site.

When you invoke ftp at the command line, you can specify the host that ftp is to communicate with. If you do, ftp immediately attempts to establish a connection to an FTP server on that host. If you don't specify a host, ftp enters its command interpreter, displays the ftp> prompt, and waits for you to enter commands.

Commands

Note: The following pages contain several references to commands that are represented in uppercase (e.g. PORT, SITE); these are FTP server commands. For more information on these commands, see ftpd.

If a command's arguments have embedded spaces, you can quote the arguments with double quotes (").

The ftp utility recognizes the following commands:

! [command [args]]
Invoke an interactive shell on the local machine. If you supply arguments, the first is executed as a command and the rest are taken as its arguments.
$ macroname [args]
Execute the macro macroname that was defined with the macdef command (see below). Arguments are passed to the macro unglobbed.
account [passwd]
Once a login has successfully completed, supply a supplemental password; this password is required by the remote system for access to resources. If you omit passwd, you'll 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 you omit remote_file, the local filename is used in naming the remote file after being altered by any ntrans or nmap setting. File transfer uses the current settings for type, format, mode, and structure.
ascii
Set the file transfer type to network ASCII.
bell
Ring a bell after each file transfer command is completed.
binary
Set the file transfer type to support binary image transfer. This is the default type.
bye
Terminate the FTP session with the remote server and exit ftp. An end-of-file ( Ctrl -D ) also terminates the session and exits.
case
Toggle remote-computer filename case mapping during mget commands. When case is on (default is off), remote computer filenames with all letters in uppercase are written in the local directory with the letters mapped to lowercase.
cd remote_directory
Change the working directory on the remote machine to the specified directory.
cdup
Change the remote machine's working directory to its parent directory.
chmod mode file
Change the permission modes of file on the remote system to mode.
close
Terminate the FTP session with the remote server and return to the command interpreter. Any defined macros are erased.
cr
Toggle carriage-return stripping during ASCII-type file retrieval. During ASCII-type file transfer, records are denoted by a carriage return/linefeed sequence. When cr is on (the default), carriage returns are stripped from this sequence to conform with the UNIX single-linefeed record delimiter.

Records on non-UNIX remote systems may contain single linefeeds. When ASCII-type transfers are made, these linefeeds are distinguishable from record delimiters only when cr is off.

delete remote_file
Delete the specified file on the remote machine.
debug
Toggle debugging mode (default is off). 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 remote_directory. If local_file is specified, place the output in that file. If interactive prompting is on (see prompt, below), ftp prompts you to verify that the last argument is indeed the target local file for receiving dir output. If you omit remote_directory, the contents of the current working directory on the remote machine are printed. If you omit local_file, or if you specify it as -, output comes to the terminal.
disconnect
A synonym for close.
form format
Set the file transfer form to format (default format is file).
get remote_file [local_file]
Retrieve the remote_file and store it on the local machine. If you omit local_file, the file is given the same name it has on the remote machine, subject to alteration by the current case, ntrans, and nmap settings. The current settings for type, form, mode, and structure are used while transferring the file.
glob
Toggle filename expansion for mdelete, mget, and mput (default is on). If globbing is turned off with glob, the filename arguments are taken literally and not expanded. Globbing for mput is done as in the QNX Shell. For mdelete and mget, each remote filename is expanded separately on the remote machine and the lists aren't merged.

Expansion of a directory name is likely to differ from expansion of the name of a regular file - the exact result depends on the remote operating system and FTP server. To preview the result: 

mls remote_files -

Note that mget and mput aren't meant to transfer entire directory subtrees of files. You can do this by transferring a tar archive of the subtree (in binary mode).

hash
Toggle hash-sign (#) printing for each data block transferred. The size of a data block is 1024 bytes.
help [command]
Print an informative message about the meaning of command. If you omit command, ftp prints a list of the known commands.
idle [seconds]
Set the inactivity timer on the remote server to the specified number of seconds. If you omit seconds, the current inactivity timer is printed.
lcd [directory]
Change the working directory on the local machine. If you omit directory, your home directory is used.
ls [remote_directory] [local_file]
Print a listing of the contents of a directory on the remote machine. The listing includes any system-dependent information that the server chooses to include. For example, most UNIX systems will produce output as if you specified ls -l.

If you omit remote_directory, the current working directory is used. If interactive prompting is on, ftp prompts you to verify that the last argument is indeed the target local file for receiving ls output. If you omit local_file, or if you specify it as -, 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 carriage returns from the terminal) terminates macro input mode. There's a limit of 16 macros and 4096 total characters in all defined macros. Macros remain defined until a close command is executed.

The macro processor interprets $ and \ as special characters.

A $ followed by a number (or 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's 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 $.

To execute a macro, use the $ macroname command.

mdelete [remote_files]
Delete the specified remote files on the remote machine.
mdir remote_file... local_file
Like dir, except you can specify multiple remote files. If interactive prompting is on, ftp prompts you 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 filename thus produced. (See glob for details on the filename expansion.) Resulting filenames will then be processed according to case, ntrans, and nmap settings. Files are transferred into the local working directory, which can be changed with an lcd directory command; new local directories can be created with a ! mkdir directory command.
mkdir directory_name
Make a directory on the remote machine.
mls remote_file... local_file
Like nlist, except you must specify multiple remote files and the local file. If interactive prompting is on, ftp prompts you to verify that the last argument is indeed the target local file for receiving mls output.
mode [mode_name]
Set the file transfer mode to the specified mode (default is stream mode).
modtime filename
Show the last modification time of the specified remote file.
mput local_files
Expand wildcards 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 filenames will then be processed according to ntrans and nmap settings.
newer filename
Get the remote file only if it's been modified more recently than the corresponding file on the current system. If the file doesn't exist on the current system, the remote file is considered newer.
nlist [remote_directory] [local_file]
Print a list of the files in a directory on the remote machine. If you omit remote_directory, the current working directory is used. If interactive prompting is on, ftp prompts you to verify that the last argument is indeed the target local file for receiving nlist output. If you omit local_file, or if you specify it as -, the output is sent to the terminal.
nmap [inpattern outpattern]
Set or unset the filename mapping mechanism. If arguments aren't specified, the filename mapping mechanism is unset.

If you supply arguments, remote filenames are mapped during any mput and put commands that have been issued without a specified remote target filename. In addition, local filenames are mapped during any mget commands and get commands that have been issued without a specified local target filename.

The nmap command is useful when connecting to a non-UNIX remote computer that uses different file naming conventions or practices.

The mapping follows the pattern set by inpattern and outpattern.

The template inpattern is for incoming filenames (which may have already been processed according to the ntrans and case settings). To do variable templating, you include the sequences $1, $2, ..., $9 in inpattern. Use the \ 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 filename 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 isn't a null string; otherwise it's 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; the output filename myfile.file for the input filename myfile; and myfile.myfile for .myfile.

You can include spaces in outpattern, as in this example: 

nmap $1 sed "s/ *$//" > $1

Use the \ character to prevent special treatment of these characters:

$
[
]
,
ntrans [inchars [outchars]]
Set or unset the mechanism for translating filename characters. If you don't supply arguments, the mechanism is unset.

If you do specify arguments, characters in remote filenames are translated during any mput and put commands that have been issued without a specified remote target filename. In addition, characters in local filenames are translated during any mget and get commands that have been issued without a specified local target filename.

This command is useful when connecting to a non-UNIX remote computer that uses different file naming conventions or practices. Characters in a filename matching a character in inchars are replaced with the corresponding character in outchars. If a character's position in inchars is longer than the length of outchars, the character is deleted from the filename. For example, the character c is deleted when you specify: 

ntrans abc de
open host [port]
Establish a connection to the specified host FTP server. If you supply a port number, ftp attempts to contact an FTP server at that port. If the autologin option is on (default), ftp attempts to automatically log you in (see ``The .netrc file'' section, below).
prompt
Toggle interactive prompting (default is on). Interactive prompting occurs during multiple file transfers so that you can selectively retrieve or store files. If prompting is turned off (default is on), any mget or mput transfers all files, and any mdelete deletes 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 commands executable on the secondary connection.

The following commands behave differently when prefaced by proxy:

Third-party file transfers depend upon support of the FTP-protocol PASV command by the server on the secondary control connection.

put local_file [remote_file]
Store a local file on the remote machine. If you omit remote_file, the local filename is used after processing according to any ntrans or nmap settings in naming the remote file. File transfer uses the current settings for type, format, mode, and structure.
pwd
Print the name of the remote machine's current working directory.
quit
A synonym for bye.
quote arg1 arg2 ...
Take the supplied arguments and send them verbatim to the remote FTP server.
recv remote_file [local_file]
A synonym for get.
reget remote_file [local_file]
The reget command 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 command is useful when transferring very large files over networks that are prone to dropping connections.
help [command_name]
Request help from the remote FTP server. If you specify a command, it's supplied to the server as well.
rstatus [filename]
If no filename is specified, show the status of the remote machine; if filename is specified, show its status on the remote machine.
rename [from] [to]
Rename the file from on the remote machine to the file to.
reset
Clear reply queue. This command, which resynchronizes command/reply sequencing with the remote FTP server, may need to be executed following a violation of the FTP protocol by the remote server.
restart marker
Restart the immediately following get or put at the indicated marker, which is usually a byte offset into the file.
rmdir directory_name
Delete a directory on the remote machine.
runique
Toggle storing of files on the local system with unique filenames (default is off). 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 continues up to .99, an error message is printed and the transfer doesn't take place. The generated unique filename will be reported. Note that runique won't affect local files generated from a shell command (see below).
send local_file [remote_file]
A synonym for put.
sendport
Toggle 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 performing multiple file transfers. If the PORT command fails, ftp uses the default data port.

When the use of PORT commands is disabled, no attempt is made to use PORT commands for each data transfer. This is useful for certain FTP implementations that ignore PORT commands but incorrectly indicate they've been accepted.

site arg1 arg2 ...
Take the supplied arguments and send them verbatim as a SITE command to the remote FTP server.
size filename
Return the size of the specified file on the remote machine.
status
Show the current status of ftp.
struct [structname]
Set the file transfer structure to structname. By default, the stream structure is used.
sunique
Toggle the storing of files on the remote machine under unique filenames (default is off). The remote FTP server must support the FTP-protocol STOU command for successful completion.
system
Show the type of operating system running on the remote machine.
tenex
Set the file transfer type to that needed to talk to TENEX machines.
trace
Toggle packet tracing (default is off).
type [typename]
Set the file transfer type to typename. If you omit typename, the current type is printed. The default type is binary.
umask [newmask]
Set the default umask on the remote server to newmask. If you omit newmask, the current umask is printed.
user username [password] [account]
Identify yourself to the remote FTP server. If you omit the password but the server requires it, ftp prompts you for it (after disabling local echo). If you don't specify an account but the server requires it, you'll be prompted for it. If you do specify an account, an account command is relayed to the remote server after the login sequence is completed. Unless ftp is invoked with autologin disabled, this process is done automatically on initial connection to the FTP server.
verbose
Toggle verbose mode (default is on). If verbose mode is on, you'll see all responses from the FTP server. When a file transfer completes, you'll also see file statistics regarding the efficiency of the transfer.
? [command]
A synonym for help.

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 an FTP-protocol ABOR command to the remote server and by then 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 doesn't support the ABOR command, an ftp> prompt won't appear until the remote server has completed sending the requested file.

The terminal interrupt key sequence will be ignored when ftp has completed 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, you must kill the local ftp utility ``by hand.''

How filenames are processed

When specified as an argument to an ftp command, a filename is processed according to the following rules:

  1. If the filename - is specified, stdin (for reading) or stdout (for writing) is used.
  2. If the first character of the filename is |, 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 from stdout or writes to stdin. If the shell command includes spaces, the argument must be quoted, like this: 
    " ls -lt"

    A particularly useful example of this mechanism is dir | more.

  3. Failing the above checks, if ``globbing'' is enabled, local filenames are expanded according to the rules used in sh (as opposed to the glob command). If the ftp command expects a single local file (e.g. put), only the first filename generated by the globbing operation is used.
  4. For mget commands 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 on.
  5. For mput commands and put commands with unspecified remote filenames, the remote filename is the local filename, which may be altered by an 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 lists many parameters that may affect a file transfer. The type may be one of ``ascii,'' ``image'' (binary), ``ebcdic,'' and ``local byte size'' (for PDP-10s and PDP-20s mostly).

The ftp utility supports the ascii and binary image types of file transfer, plus local byte-size 8 for tenex mode transfers. But it supports only the default values for the remaining file transfer parameters: mode, form, and struct.

The .netrc file

The .netrc file, which resides in your home directory, contains login and initialization information used by ftp's autologin facility. The following tokens are recognized; you can separate them by spaces, tabs, or newline characters:

machine name
Identify a remote machine name. The autologin process searches the .netrc file for a machine token that matches the remote machine specified on the ftp command line or in an open command. Once a match is made, the subsequent .netrc tokens are processed, stopping when the end of file is reached or when another machine or a default token is encountered.
default
This is the same as machine name except that default matches any name. There can be only one default token, and it must be after all machine tokens. This is normally used as: 
default login anonymous password user@site

thereby giving you automatic anonymous ftp login to machines not specified in .netrc.

This can be overridden by using the -n option to disable autologin.

login name
Identify a user on the remote machine. If this token is present, the autologin process initiates a login using the specified name.
password string
Supply a password. When this token is present, the autologin process supplies the specified string if the remote server requires a password as part of the login process.
Note: If this token is present in the .netrc file for any user other than anonymous, ftp aborts the autologin process if .netrc is readable by anyone besides the user. For example: 
-rw------- 1 dabrown   techies         225 Sep 18 1996 .netrc
account string
Supply an additional account password. If this token is present, the autologin process supplies the specified string if the remote server requires an additional account password; if the remote server doesn't require an additional password, the autologin process initiates an ACCT command.
macdef name
Define a macro. This token functions like the ftp macdef command. A macro is defined with the specified name; its contents begin with the next .netrc line and continue until a null line (consecutive newline characters) is encountered. If a macro named init is defined, it's automatically executed as the last step in the autologin process.

Environment variables:

HOME
For default location of a .netrc file, if one exists.
SHELL
For default shell.

Caveats:

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

An error in the treatment of carriage returns in the 4.2BSD ascii-mode transfer code has been corrected. This correction may result in incorrect transfers of binary files to and from 4.2BSD servers using the ascii type. Avoid this problem by using the binary image type.

See also:

ftpd