ftp - ARPANET file transfer program
ftp [-46AadegimnptVv] [-P port] [-r seconds] [host [port]]
ftp [-o output] ftp://[user:password@]host[:port]/file[/]
ftp [-o output] http://host[:port]/file
ftp [-o output] host:/file[/]
ftp is the user interface to the ARPANET standard File
The program allows a user to transfer files to and from a
The latter three usage formats will fetch a file using either the HTTP or
FTP protocols into the current directory. This is ideal for
Refer to AUTO-FETCHING FILES below for more information.
The options are as follows:
-4 Forces ftp to use IPv4 addresses only.
-6 Forces ftp to use IPv6 addresses only.
-A Force active mode ftp. By default, ftp will try to
mode ftp and fall back to active mode if passive is
by the server. This option causes ftp to always use
connection. It is only useful for connecting to
very old servers
that do not implement passive mode properly.
-a Causes ftp to bypass the normal login procedure and
use an anonymous
-d Enables debugging.
-e Disables command line editing. Useful for Emacs
-g Disables file name globbing.
-i Turns off interactive prompting during multiple file
-m Causes ftp to always display the progress meter in
cases where it
would not do so by default.
-n Restrains ftp from attempting ``auto-login'' upon
If auto-login is enabled, ftp will check the
(see below) in the user's home directory for an entry describing
an account on the remote machine. If no entry exists, ftp will
prompt for the remote machine login name (default is
identity on the local machine), and, if necessary,
prompt for a
password and an account with which to login.
When fetching a single file or URL, save the contents in output.
To make the contents go to stdout, use ``-'' for
Sets the port number to port.
-p Enable passive mode operation for use behind connection filtering
firewalls. This option has been deprecated as ftp
now tries to
use passive mode by default, falling back to active
mode if the
server does not support passive connections.
Retry to connect if failed, pausing for number of
-t Enables packet tracing.
-V Disable verbose mode, overriding the default of enabled when input
is from a terminal.
-v Enable verbose mode. This is the default if input
is from a terminal.
Forces ftp to show all responses from the
as well as report on data transfer statistics.
The client host with which ftp is to communicate may be
specified on the
command line. If this is done, ftp will immediately attempt
a connection to an FTP server on that host; otherwise, ftp
will enter its
command interpreter and await instructions from the user.
When ftp is
awaiting commands, the prompt ``ftp>'' is provided to the
user. The following
commands are recognized by ftp:
! [command [args]]
Invoke an interactive shell on the local machine. If there
are arguments, the first is taken to be a command to execute
directly, with the rest of the arguments as its
$ macro-name [args]
Execute the macro macro-name that was defined
with the macdef
command. Arguments are passed to the macro unglobbed.
A synonym for help.
Supply a supplemental password required by a remote system
for access to resources once a login has been
completed. If no argument is included, the user
prompted for an account password in a non-echoing input mode.
append local-file [remote-file]
Append a local file to a file on the remote machine. If
remote-file is left unspecified, the local file
name is used
in naming the remote file after being altered by
or nmap setting. File transfer uses the current
type, format, mode, and structure.
ascii Set the file transfer type to network ASCII.
This is the default
bell Arrange that a bell be sounded after each file
binary Set the file transfer type to support binary image transfer.
bye Terminate the FTP session with the remote server
ftp. An end-of-file will also terminate the
session and exit.
case Toggle remote computer file name case mapping
commands. When case is on (default is off), remote computer
file names with all letters in upper case are
written in the
local directory with the letters mapped to lower
Change the working directory on the remote machine to remote-
cdup Change the remote machine working directory to
the parent of
the current remote machine working directory.
chmod mode file-name
Change the permission modes of the file
file-name on the remote
system to mode.
close Terminate the FTP session with the remote server
to the command interpreter. Any defined macros
cr Toggle carriage return stripping during ASCII
type file retrieval.
Records are denoted by a carriage return/linefeed
sequence during ASCII type file transfer. 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
when an ASCII type transfer is made,
may be distinguished from a record delimiter only when cr is
Toggle debugging mode. If an optional
debug-value is specified,
it is used to set the debugging level.
is on, ftp prints each command sent to the remote machine,
preceded by the string `-->'.
Delete the file remote-file on the remote machine.
dir [remote-directory [local-file]]
A synonym for ls.
disconnect A synonym for close.
edit Toggle command line editing, and context sensitive command
and file completion. This is automatically enabled if input
is from a terminal, and disabled otherwise.
epsv4 Toggle use of EPSV/EPRT command on IPv4 connection.
exit A synonym for bye.
Set the file transfer form to format. The default format is
ftp host [port]
A synonym for open.
gate [host [port]]
Toggle gate-ftp mode. This will not be permitted if the
gate-ftp server hasn't been set (either explicitly by the user,
or from the FTPSERVER environment variable).
If host is
given, then gate-ftp mode will be enabled, and
server will be set to host. If port is also
given, that will
be used as the port to connect to on the gateftp server.
get remote-file [local-file]
Retrieve the remote-file and store it on the local machine.
If the local file name is not specified, it is
given the same
name it has on the remote machine, subject to
the current case, ntrans, and nmap settings.
settings for type, form, mode, and structure are
transferring the file.
glob Toggle filename expansion for mdelete, mget and
globbing is turned off with glob, the file name
taken literally and not expanded. Globbing for
mput is done
as in csh(1). For mdelete and mget, each remote
file name is
expanded separately on the remote machine and
the lists are
not merged. Expansion of a directory name is
likely to be
different from expansion of the name of an ordinary file: the
exact result depends on the foreign operating
system and ftp
server, and can be previewed by doing ``mls remote-files -''.
Note: mget and mput are not meant to transfer
subtrees of files. That can be done by
tar(1) archive of the subtree (in binary mode).
Toggle hash mark (`#') printing for each data
The size of a data block defaults to
This can be changed by specifying size in bytes.
Print an informative message about the meaning
If no argument is given, ftp prints a list of
the known commands.
Set the inactivity timer on the remote server to
If seconds is omitted, the current inactivity timer is
Change the working directory on the local machine. If no
directory is specified, the user's home directory is used.
less file A synonym for page.
lpwd Print the working directory on the local machine.
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 from the command `ls -l'.
If remote-directory is left unspecified, the
directory is used. If interactive prompting is
on, ftp will
prompt the user to verify that the last argument
the target local file for receiving ls output.
If no local
file is specified, or if local-file is ``-'',
the output is
sent to the terminal.
Define a macro. Subsequent lines are stored as
macro-name; a null line (consecutive newline
characters in a
file or carriage returns from the terminal) terminates macro
input mode. There is a limit of 16 macros and
characters in all defined macros. Macros remain
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 is replaced by the second argument, and
so on. A `'
followed by any character is replaced by that
the `' to prevent special treatment of the `$'.
Delete the remote-files on the remote machine.
mdir remote-files local-file
A synonym for mls.
Expand the remote-files on the remote machine
and do a get
for each file name thus produced. See glob for
the filename expansion. Resulting file names
will then be
processed according to case, ntrans, and nmap
Files are transferred into the local working directory, which
can be changed with `lcd directory'; new local
can be created with `! mkdir directory'.
Make a directory on the remote machine.
mls remote-files local-file
Like ls, except multiple remote files may be
the local-file must be specified. If interactive prompting
is on, ftp will prompt the user to verify that
the last argument
is indeed the target local file for receiving mls output.
Set the file transfer mode to mode-name. The
default mode is
Show the last modification time of the file on
the remote machine.
more file A synonym for page.
Expand wild cards in the list of local files
given as arguments
and do a put for each file in the resulting list. See
glob for details of filename expansion. Resulting file names
will then be processed according to ntrans and
A synonym for mput.
Get the file only if the modification time of
the remote file
is more recent than the file on the current system. If the
file does not exist on the current system, the
remote file is
considered newer. Otherwise, this command is
nlist [remote-directory [local-file]]
Print a list of the files in a directory on the
If remote-directory is left unspecified,
working directory is used. If interactive
prompting is on,
ftp will prompt the user to verify that the last
indeed the target local file for receiving nlist
no local file is specified, or if local-file is
output is sent to the terminal. Note that on
the nlist command will only return information
files (not directories or special files).
nmap [inpattern outpattern]
Set or unset the filename mapping mechanism. If
are specified, the filename mapping mechanism is
arguments are specified, remote filenames are
mput commands and put commands issued without a
target filename. If arguments are specified, local
filenames are mapped during mget commands and
issued without a specified local target filename. This command
is useful when connecting to a non-UNIX remote computer
with different file naming conventions or practices.
The mapping follows the pattern set by inpattern
outpattern. inpattern is a template for incoming filenames
(which may have already been processed according
ntrans and case settings). Variable templating
by including the sequences `$1', `$2',
inpattern. Use `' to prevent this special
treatment of the
`$' character. All other characters are treated
and are used to determine the nmap inpattern
For example, given inpattern $1.$2 and the remote file name
"mydata.data", $1 would have the value "mydata",
and $2 would
have the value "data". The outpattern determines the resulting
mapped filename. The sequences `$1', `$2',
..., `$9' are
replaced by any value resulting from the
The sequence `$0' is replaced by the original
the sequence `[seq1, seq2]' is replaced by [seq1]
if seq1 is not a null string; otherwise it is
seq2. For example:
nmap $1.$2.$3 [$1,$2].[$2,file]
This command would yield the output filename
input filenames myfile.data and myfile.data.old;
for the input filename myfile; and myfile.myfile
for the input
filename .myfile. Spaces may be included in
as in the example
nmap $1 sed "s/ *$//" > $1
Use the `' character to prevent special treatment of the
`$', `[', `]', and `,' characters.
ntrans [inchars [outchars]]
Set or unset the filename character translation
If no arguments are specified, the filename
mechanism is unset. If arguments are
in remote filenames are translated during
and put commands issued without a specified remote target
filename. If arguments are specified, characters in local
filenames are translated during mget commands and get
commands issued without a specified local target
This command is useful when connecting to a nonUNIX remote
computer with different file naming conventions
Characters in a filename matching a character in
replaced with the corresponding character in
the character's position in inchars is longer
than the length
of outchars, the character is deleted from the
open host [port]
Establish a connection to the specified host FTP
optional port number may be supplied, in which
case ftp will
attempt to contact an FTP server at that port.
If the auto-
login option is on (default), ftp will also attempt to automatically
log the user in to the FTP server (see
page file Retrieve file and display with the program defined in PAGER
(defaulting to more(1) if PAGER is null or not
passive Toggle passive mode. If passive mode is turned
is on), the ftp client will send a PASV command
for all data
connections instead of the usual PORT command.
The PASV command
requests that the remote server open a port
for the data
connection and return the address of that port.
server listens on that port and the client connects to it.
When using the more traditional PORT command,
the client listens
on a port and sends that address to the remote server,
who connects back to it. Passive mode is useful
ftp through a gateway router or host that controls the directionality
of traffic. (Note that though ftp
servers are required
to support the PASV command by RFC 1123,
some do not.)
preserve Toggle preservation of modification times on retrieved files.
progress Toggle display of transfer progress bar. The
will be disabled for a transfer that has
local-file as ``-''
or a command that starts with `|'. Refer to
CONVENTIONS for more information.
prompt Toggle interactive prompting. Interactive
during multiple file transfers to allow the user
retrieve or store files. If prompting is
(default is on), any mget or mput will transfer
and any mdelete will delete all files.
When prompting is on, the following commands are
a Answer ``yes'' to the current file and
answer ``yes'' to any remaining
files for the
n Do not transfer the file.
p Answer ``yes'' to the current file and
prompt mode (as if ``prompt off'' had
y Transfer the file.
Execute an ftp command on a secondary control
This command allows simultaneous connection to
two remote ftp
servers for transferring files between the two
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
The following commands behave differently when
proxy: open will not define new macros during
process; close will not erase existing macro
and mget transfer files from the host on the
connection to the host on the secondary control
and put, mput, and append transfer files from
the host on the
secondary control connection to the host on the
connection. 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
left unspecified, the local file name is used
according to any ntrans or nmap settings in
remote file. File transfer uses the current
type, format, mode, and structure.
pwd Print the name of the current working directory
on the remote
quit A synonym for bye.
quote arg1 arg2 ...
The arguments specified are sent, verbatim, to
the remote FTP
recv remote-file [local-file]
A synonym for get.
reget remote-file [local-file]
Reget 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
continued from the apparent point of failure.
is useful when transferring very large files
that are prone to dropping connections.
rename [from [to]]
Rename the file from on the remote machine to
the file to.
reset Clear reply queue. This command re-synchronizes
sequencing with the remote ftp server.
may be necessary following a violation of the
ftp protocol by
the remote server.
Restart the immediately following get or put at
marker. On UNIX systems, marker is usually a
byte offset into
Request help from the remote FTP server. If a
is specified, it is supplied to the server as
Delete a directory on the remote machine.
With no arguments, show status of remote machine. If file-
name is specified, show status of file-name on
runique Toggle storing of files on the local system with
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
existing file, a ``.2'' is appended to the original name. If
this process continues up to ``.99'', an error
printed, and the transfer does not take place.
unique filename will be reported. Note that
runique will not
affect local files generated from a shell command (see below).
The default value is off.
send local-file [remote-file]
A synonym for put.
sendport Toggle the use of PORT commands. By default,
ftp will attempt
to use a PORT command when establishing a
for each data transfer. The use of PORT commands can prevent
delays when performing multiple file transfers.
If the PORT
command fails, ftp will use the default data
port. When the
use of PORT commands is disabled, no attempt
will be made to
use PORT commands for each data transfer. This
is useful for
certain FTP implementations which do ignore PORT
but, incorrectly, indicate they've been accepted.
site arg1 arg2 ...
The arguments specified are sent, verbatim, to
the remote FTP
server as a SITE command.
Return size of file-name on remote machine.
status Show the current status of ftp.
sunique Toggle storing of files on remote machine under
names. The remote ftp server must support the
STOU command for successful completion. The remote server
will report the unique name. Default value is
system Show the type of operating system running on the
tenex Set the file transfer type to that needed to
talk to TENEX
trace Toggle packet tracing.
Set the file transfer type to type-name. If no
type is specified,
the current type is printed. The default
Set the default umask on the remote server to
newmask is omitted, the current umask is printed.
user user-name [password [account]]
Identify yourself to the remote FTP server. If
is not specified and the server requires it, ftp
the user for it (after disabling local echo).
If an account
field is not specified, and the FTP server requires it, the
user will be prompted for it. If an account
field is specified,
an account command will be relayed to the
after the login sequence is completed if the remote server
did not require it for logging in. Unless ftp
with ``auto-login'' disabled, this process is
on initial connection to the FTP server.
verbose Toggle verbose mode. In verbose mode, all responses from the
FTP server are displayed to the user. In addition, if verbose
is on, when a file transfer completes,
the efficiency of the transfer are reported. By default,
verbose is on.
Command arguments which have embedded spaces may be quoted
Commands which toggle settings can take an explicit on or
off argument to
force the setting appropriately.
If ftp receives a SIGINFO (see the ``status'' argument of
whilst a transfer is in progress, the current transfer rate
will be written to the standard error output, in the same
format as the
standard completion message.
In addition to standard commands, this version of ftp supports an autofetch
feature. To enable auto-fetch, simply pass the list
on the command line.
The following formats are valid syntax for an auto-fetch element:
host:/file[/] ``Classic'' ftp
ftp://[user:password@]host[:port]/file[/] An ftp URL, retrieved using
the ftp protocol
http via the
proxy defined in
is given and
as user with a
http://host[:port]/file An http URL, retrieved using
the http protocol. If
http_proxy is defined, it is
used as a URL to
an HTTP proxy
If a classic format or an ftp URL format has a trailing `/',
will connect to the site and cd to the directory given as
the path, and
leave the user in interactive mode ready for further input.
If successive auto-fetch ftp elements refer to the same
host, then the
connection is maintained between transfers, reducing overhead on connection
creation and deletion.
If file contains a glob character and globbing is enabled
then the equivalent of mget file is performed.
If no -o option is specified, and the directory component of
no globbing characters, then it is stored in the current directory
as the basename(1) of file. If -o output is specified, then
stored as output. Otherwise, the remote name is used as the
ABORTING A FILE TRANSFER [Toc] [Back]
To abort a file transfer, use the terminal interrupt key
Sending transfers will be immediately halted. Receiving transfers
will be halted by sending an ftp protocol ABOR command to
server, and discarding any further data received. The speed
this is accomplished depends upon the remote server's support for ABOR
processing. If the remote server does not support the ABOR
`ftp>' prompt will not appear until the remote server has
the requested file.
The terminal interrupt key sequence will be ignored when ftp
any local processing and is awaiting a reply from the remote server.
A long delay in this mode may result from the ABOR processing described
above, or from unexpected behavior by the remote server, including violations
of the ftp protocol. If the delay results from unexpected remote
server behavior, the local ftp program must be killed by
FILE NAMING CONVENTIONS [Toc] [Back]
Files specified as arguments to ftp commands are processed
the following rules.
1. If the file name ``-'' is specified, the standard input
or standard output (for writing) is used.
2. If the first character of the file name is `|', the remainder of the
argument is interpreted as a shell command. ftp then
forks a shell,
using popen(3) with the argument supplied, and reads
the standard output (standard input). If the shell
spaces, the argument must be quoted; e.g., "ls -lt". A
useful example of this mechanism is: "dir |more".
3. Failing the above checks, if ``globbing'' is enabled,
names are expanded according to the rules used in the
the glob command. If the ftp command expects a single
(e.g., put), only the first filename generated by the
operation is used.
4. For mget commands and get commands with unspecified local file
names, the local filename is the remote filename, which
may be altered
by a case, ntrans, or nmap setting. The resulting filename
may then be altered if runique is on.
5. For mput commands and put commands with unspecified remote file
names, the remote filename is the local filename, which
may be altered
by a ntrans or nmap setting. The resulting filename may then
be altered by the remote server if sunique is on.
FILE TRANSFER PARAMETERS [Toc] [Back]
The FTP specification specifies many parameters which may
affect a file
transfer. The type may be one of ``ascii'', ``binary'',
``ebcdic'' (currently not supported) or ``tenex'' (local
byte size 8, for
PDP-10's and PDP-20's mostly). ftp supports the ASCII and
image types of
file transfer, plus local byte size 8 for tenex mode transfers.
ftp supports only the default values for the remaining file
mode, form, and struct.
The .netrc file contains login and initialization information used by the
auto-login process. It resides in the user's home directory. The following
tokens are recognized; they may be separated by
spaces, tabs, or
Identify a remote machine name. The auto-login
the .netrc file for a machine token that matches the remote
machine specified on the ftp command line or as an
argument. Once a match is made, the subsequent
are processed, stopping when the end of file is
reached or another
machine or a default token is encountered.
default This is the same as machine name except that
any name. There can be only one default token,
and it must be
after all machine tokens. This is normally used
default login anonymous password user@site
thereby giving the user automatic anonymous ftp
login to machines
not specified in .netrc. This can be overridden by using
the -n flag to disable auto-login.
Identify a user on the remote machine. If this
token is present,
the auto-login process will initiate a login
Supply a password. If this token is present, the
process will supply the specified string if the
requires a password as part of the login process.
Note that if
this token is present in the .netrc file for any
than anonymous, ftp will abort the auto-login process if the
.netrc is readable by anyone besides the user.
Supply an additional account password. If this
token is present,
the auto-login process will supply the specified string
if the remote server requires an additional account password,
or the auto-login process will initiate an ACCT
command if it
Define a macro. This token functions like the ftp
functions. A macro is defined with the specified name;
its contents begin with the next .netrc line and
a null line (consecutive new-line characters) is
If a macro named init is defined, it is automatically executed
as the last step in the auto-login process.
ftp supports interactive command line editing, via the editline(3) library.
It is enabled with the edit command, and is enabled
by default if
input is from a tty. Previous lines can be recalled and
edited with the
arrow keys, and other GNU Emacs-style editing keys may be
used as well.
The editline(3) library is configured with a .editrc file -
editrc(5) for more information.
An extra key binding is available to ftp to provide context
command and filename completion (including remote file completion). To
use this, bind a key to the editline(3) command
ftp-complete. By default,
this is bound to the TAB key.
ftp utilizes the following environment variables:
FTPMODE Overrides the default operation mode. Recognized values
passive passive mode ftp only
active active mode ftp only
auto automatic determination of passive
(this is the default)
gate gate-ftp mode
FTPSERVER Host to use as gate-ftp server when gate is
FTPSERVERPORT Port to use when connecting to gate-ftp server when gate
is enabled. Default is port returned by a
lookup of ``ftpgate/tcp''.
HOME For default location of a .netrc file, if one
PAGER Used by page to display files.
SHELL For default shell.
TMPDIR Directory to put temporary files.
ftp_proxy URL of FTP proxy to use when making FTP URL
not defined, use the standard ftp protocol).
http_proxy URL of HTTP proxy to use when making HTTP URL
For active mode data connections, ftp will listen to a random high TCP
port. The interval of ports used are configurable using
net.inet.ip.porthifirst and net.inet.ip.porthilast.
basename(1), csh(1), more(1), stty(1), tar(1), tftp(1), editline(3),
getservbyname(3), popen(3), editrc(5), services(5), ftpproxy(8), ftpd(8)
The ftp command appeared in 4.2BSD.
Correct execution of many commands depends upon proper behavior by the
An error in the treatment of carriage returns in the 4.2BSD
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.
OpenBSD 3.6 August 18, 1997
[ Back ]