.TH ftp "" "" "Command"
.PC "Client to execute Internet file transfer protocol"
\fBftp [\-d] [\-g] [\-i] [-n] [\-v] [\fIremotehost\^\fB]\fR
.PP
.HS
.SH Options
.IC \fB\-d\fR
Debug:
.B ftp
shows what actions it would take if it were running,
but does not actually transfer any files
.IC \fB\-g\fR
No glob:
.B ftp
does not expand wildcards (or ``globs'') in file names
.IC \fB\-i\fR
Turn off prompting during mass transfers of files; the default is to
prompt before the transfer of each file
.IC \fB\-n\fR
No autologin:
force
.B ftp
to log you into the remote host explicitly, whether or not
your home directory on the remote host contains a
.B .netrc
file
.IC \fB\-v\fR
Verbose:
give detailed information about actions
.HE
.B ftp
is a client program with which you can contact other systems on
your network, log in, and transfer files.
Its name comes from the fact that it implements the
Department of Defense's File-Transfer Protocol (MIL-STD-1780).
.PP
The rest of this article uses the terms ``remote host''
and ``local host''.
In terms of networking, the
.I "local host"
is the machine that you have
logged into primarily \(em either through a serial port, through its
console, or some other device that is plugged directly into it.
The
.I "remote host"
is the system you are trying to contact over the network.
The remote host can be a computer in the next room, or on the other
side of the planet.
.SH "Command-line Options"
.B ftp
recognizes the following command-line options:
.IP \fB\-d\fR 0.3i
Debug:
.B ftp
displays what actions it would take if it were running,
but does not actually execute them.
.IP \fB\-g\fR
.II glob
No glob:
.B ftp
does not expand wildcard characters (or ``globs'') in file names.
(For a description of what a ``wildcard'' is, see the entry for
.B wildcards
in the \*(CO Lexicon.)
.IP \fB\-i\fR
Turn off prompting during the transfer of a mass of files.
By default,
.B ftp
prompts you before it transfers each file.
.IP \fB\-n\fR
No autologin.
This option forces
.B ftp
to log you into the remote host,
whether or not your home directory on that host contains the file
.BR .netrc .
If autologin is enabled,
.B ftp
reads
.B .netrc
for an entry that names your account on your local host;
if one exists, then it lets you into the remote host without logging in.
.B .netrc
is described in more detail below.
.IP \fB\-v\fR
Verbose:
.B ftp
shows all responses from the server, and displays information on
the speed with which data are transferred between hosts.
.IP \fIremotehost\fR
Connect to
.IR remotehost .
You can identify the
.I remotehost
either through its name or through its Internet address.
Please note that
.B ftp
can connect only to hosts that are named in the file
.B /etc/hosts
on your local host.
.SH "ftp Commands"
When you invoke
.BR ftp ,
it enters command mode, as shown by its prompt:
.DM
	ftp>
.DE
If you named a
.I remotehost
on the
.B ftp
command line,
.B ftp
enters command mode only after it has attempted to log you into
.IR remotehost ;
otherwise, it enters command mode immediately.
.PP
When
.B ftp
is in command mode, you can give it any of the following commands:
.IP "! [\fIcommand \fB[\fIarguments\^\fB] ]\fR"
Invoke a shell on your local host.
If you name a
.IR command ,
.B ftp
passes it to the shell for execution along with its
.IR arguments ,
if any.
.B ftp
suspends your session with the remote host until the shell has finished
executing
.IR command .
When invoked without a
.IR command ,
.B !
invokes the shell
.BR sh ,
and suspends your session with the remote host until you exit from the shell.
.IP "\fB? [\fIcommand\^\fB]\fR"
The command
.B ?
is a synonym for
.BR help .
.IP "\fB$ \fImacro \fB[\fIarguments\^\fB]\fR"
Execute the
.I macro
with the optional
.IR arguments .
.B ftp
does not expand any wildcard characters in the
.IR arguments .
You must first have used the command
.B macdef
to create
.I macro
before you can execute it.
.IP "\fBaccount [\fIpassword\^\fB]\fR"
Pass the supplemental
.I password
to the remote host after you have successfully logged into it.
Some hosts require the supplemental password before they grant users
access to resources; for example, many \*(CO systems use a
remote-access password to provide an extra layer of security against intruders.
If you do not give the
.IR password ,
.B ftp
prompts you for it and lets you enter it in no-echo mode.
You may prefer to use this method if you are working in a busy area.
.IP "append \fIlocalfile \fB[remotefile\^\fB]\fR"
Append
.I localfile
(which is a file on your local host)
onto
.I remotefile
(which is a file on the remote host).
If you do not name
.IR remotefile ,
.B ftp
assumes that you wish to append
.I localfile
onto a file of the same name on the remote host.
.IP \fBascii\fR
Set the type of file transfer to ASCII (i.e., text).
This is the default type.
.IP \fBbell\fR
Tell
.B ftp
to ring your terminal's bell after it transfers a file.
.IP \fBbinary\fR
Set the type of file transfer to binary.
You should use this mode of transfer if you are transferring files other
than text, i.e., executable binary files, object modules, archives,
compressed files, or images (including GIF files).
.IP \fBbye\fR
Break the connection with the remote host and exit from
.BR ftp .
.IP \fBcase\fR
Toggle whether
.B ftp
maps upper-case file names while it executes its command
.BR mget .
When toggled on,
.B ftp
converts file names that are all in upper-case characters
to all lower-case characters before it writes the file onto your local host.
The default is for case-mapping to be toggled off.
.IP "\fBcd \fIdirectory\fR"
Change to
.I directory
on the remote host.
To change directories on your local host, use the command
.BR lcd .
.IP \fBcdup\fR
On the remote host, change to the parent directory of the current directory.
This is a synonym for the \*(CO command \fBcd ..\fR.
.IP \fBclose\fR
Close the connection with the remote host.
.B ftp
erases all macros that you have defined.
You can then use the command
.B open
to connect to another host on your network.
.IP \fBcr\fR
Toggle whether
.B ftp
strips carriage-return characters from a file
when it copies a file while it is in
.B ascii
mode.
Usually you should toggle this on
when you copy a text file from an \*(MD machine to
your \*(CO host,
to strip the extra carriage-return character from the
CR/LF pair that \*(MD uses to mark the end of a line of text.
The default is for carriage-return stripping to be on.
.IP "\fBdelete \fIremotefile\fR"
Delete
.I remotefile
from the current directory on the remote host.
.IP "debug [\fIlevel\^\fB]\fR"
Toggle debugging mode.
If you toggle debugging to on,
.B ftp
sets the debugging level to
.IR level ,
should you name one.
When debugging is on,
.B ftp
prints each command that it sends to the
remote machine, preceded by the string ``-->''.
.IP "\fBdir [\fIremotedirectory\^\fB] [\fIlocalfile\^\fB]\fR"
List the name, size, and date of last modification for each file in
.I remotedirectory
on the remote host.
If you do not name a
.IR remotedirectory ,
.B ftp
lists the contents of the current directory on the remote host.
.B ftp
writes the output of this command into
.IR localfile ,
should you name one.
.IP \fBdisconnect\fR
This is a synonym for the command
.BR close .
.IP \fBexit\fR
This is a synonym for the command
.BR close .
.IP "\fBget \fIremotefile \fB[\fIlocalfile\^\fB]\fR"
Copy
.I remotefile
from the remote host to your local host.
If you name a
.IR localfile ,
.B ftp
copies
.I remotefile
into it; otherwise, it copies
.I remotefile
into a file of the same name on your local host.
If a file of that name exists on your local host,
.B ftp
overwrites it.
.B ftp
assumes that
.I remotefile
is in your current directory on the remote host.
.IP "\fBglob\fR"
Toggle whether
.B ftp
expands wildcards (or ``globs'') within file names.
If toggled off,
.B ftp
passes wildcards to the remote system's operating system unexpanded.
(For information on what a ``wildcard'' is, see the entry for
.B wildcards
in the \*(CO Lexicon.)
.IP \fBhash\fR
Toggle whether
.B ftp
prints a pound sign `#' (also called the ``hash sign'')
whenever it transfers one block (512 bytes) of data.
(This command has nothing to do with hash tables or related
programming techniques.)
The default is off.
.IP "\fBhelp [\fIcommand\fB]\fR"
Print a message that describes
.IR command .
If you do not name a
.IR command ,
.B ftp
lists its available commands.
.IP "\fBlcd [\fIdirectory\fB]\fR"
Change the current directory on your local host.
If you do not name a
.IR directory ,
.B ftp
moves you to your home directory.
To change directories on the remote host, use the command
.BR cd ,
described above.
.IP "\fBls [\fIlocaldirectory\fB] [\fIlocalfile\^\fB]\fR"
List the name of each file in
.I localdirectory
on the local host.
If you do not name a
.IR localdirectory ,
.BR ftp
lists every file in the current directory.
.B ftp
writes its output into
.IR localfile ,
should you name one; otherwise, it writes its output onto the standard
output device.
.IP "\fBmacdef \fImacro\fR"
Define a
.IR macro .
.B ftp
stores everything that you type up to the next null line
(that is, a line that consists just of a carriage-return character)
under the name
.IR macro .
To invoke
.IR macro ,
type its name precfixed with a dollar sign `$'.
You can have no more than 16 macros at any time; and your macros together
cannot exceed 4,096 bytes.
When you use the command
.B close
to close a connection with a remote host,
.B ftp
erases all macros.
.IP "\fBmdelete \fIremotefile ...\fR
Delete each
.I remotefile
from the remote host.
.IP "\fBmdir \fIremotefile ... localfile\fR"
List the name, size, and date of last modification for each
.IR remotefile .
.B ftp
writes its output into
.IR localfile ,
which it assumes is always the last file in the list.
If you name only one file,
.B ftp
assumes that it is the
.IR localfile ,
and writes information about every file in the current directory on the
remote system.
Do not use this command unless you are
.I very
sure that
.I localfile
does not contain something vital.
.I "Caveat utilitor!"
.IP "\fBmget \fIremotefile ...\fR"
Copy each
.I remotefile
from the remote host into your current directory on the local host.
If wildcard expansion is toggled on,
.B ftp
expands all wildcard characters to name files, just as the shell does.
To toggle the expansion of wildcards,
use the command
.BR glob ,
described above.
.B ftp
gives each downloaded file the same name on your local system that it has on
the remote system.
If a file's name exceeds 14
characters, that name will be truncated on your \*(CO system, which
could create problems.
If your local directory on the local host contains a file
whose name matches that of a file being copied,
.B ftp
overwrites it.
.IP "\fBmkdir \fIdirectory\fR"
Create
.I directory
on the remote host.
.B ftp
creates the directory only if the remote system had granted you
permission to do so.
.IP "\fBmls \fIremotefile ... localfile\fR"
Same as
.BR mdir .
Before you use this command, see the caveats described above for the
command
.BR mdir .
.IP "\fBmode [\fImode\^\fB]\fR"
Set the mode of file transfer to
.IR mode .
The default mode is
.BR stream ,
descibed below.
.IP "\fBmput \fIlocalfile ...\fR"
Copy each
.I remotefile
from the local host into the current directory on the remote host.
If wildcard expansion is toggled on,
.B ftp
expands every wildcard characters within file names, just as the shell does.
To toggle the expansion of wildcards,
use the command
.BR glob ,
described above.
If the local directory on the remote host contains a file
whose name matches that of a
.IR localfile ,
.B ftp
overwrites it.
.IP "\fBnmap [\fIinpattern outpattern\^\fB]\fR
Automatically transform (or ``map'') the names of files being copied.
For example, if the name of a file on your local host contains a character
that is illegal to the operating system of the remote host,
use this command to map that character to something innocuous.
If you invoke
.B nmap
with no argument,
.B ftp
erases the existing map, if any.
.IP
Mapping follows the templates
.I inpattern
and
.IR outpattern :
the former describes the name of the file as input to
.BR ftp ,
and the latter describes the name that
.B ftp
should write.
The variables
.B $1
through
.B $9
represent tokens within the file name.
A token is delimited by white space plus any characters that you name
literally in
.IR inpattern .
The variable
.B $0
represents the entire file name as input to
.BR ftp .
To indicate a literal `$', use the escape sequence \fB\e$\fR.
The sequence \fB[$\fIX\fB,$\fIY\fB]\fR in
.I outpattern
tells
.B ftp
to use token 
.BI $ X
if it is not null, or use token
.BI $ Y
if it is.
.B ftp
writes the characters within
.I outpattern
literally into the file name that it outputs.
To output a literal
.BR $ ,
.BR [ ,
.BR ] ,
or 
.BR , ,
prefix it with a backslash `\e'.
.IP
For example, consider the problem of downloading a file from \*(CO to \*(MD.
\*(CO lets a file name be up to 14 characters long, and places no restriction
on how many periods a name can contain, or where those periods can appear.
\*(MD, on the other hand, permits a file to have only one period in its name,
and the period can be followed by no more than three characters.
The following
.B nmap
command maps files from the \*(CO to the \*(MD standard:
.DM
	nmap $1.$2.$3 [$1,$2].[$2,ftp]
.DE
.IP
Here,
.B ftp
breaks the \*(CO file name into three tokens, as delimited by periods.
It constructs a file name \fIfirsttoken\fB.\fIsecondtoken\fR,
or \fBfirsttoken\fB.ftp\fR should there be no second token.
It throws away the third token (that is, everything from the second period
to the end of the file name).
.IP "\fBntrans [\fIinchars \fB[\fIoutchars\^\fB]]\fR"
Transform file names character by character.
You can use this command to map out characters that would create problems
under a given operating system.
.B ntrans
maps each character within
.I inchars
to the corresponding character within
.IR outchars .
.IP
For example, the characters `*', `|', and `?' have special significance
under \*(CO; although it is legal to embed those characters within file
names, it is not wise to do so.
The following command filters these characters out of the name of any
file you download to your system:
.DM
	ntrans @$! ABC
.DE
.IP
After you issue this command
.B ftp
transforms every `@' to an `A', every `$' to a `B', and every `!' to a `C'.
.IP
If a character within
.I inchars
has no corresponding character in
.IR outchars ,
.B ftp
throws it away.
For example, the command
.DM
	ntrans @$!~ ABC
.DE
.IP
tells
.B ftp
to map every `@', `$', and `!' as described above, and to throw away every
`~'.
.IP
Invoking
.B ntrans
without arguments turns off character mapping.
.IP "\fBopen \fIhost \fB[\fIport\^\fB]\fR"
Open a connection with the remote
.IR host .
The optional argument
.I port
names the port through which
.B ftp
is to contact
.IR host .
.I host
can be either the remote host's name or its Internet address.
.IP \fBprompt\fR
Toggle whether
.B ftp
prompts you to confirm the transfer of each file in a multi-file transaction.
The default is on.
.IP "\fBproxy \fIcommand \fB[\fIarguments\^\fB]\fR"
Execute an
.B ftp
command on a second remote host while you maintain connected to the first.
In effect, this command lets you conduct two
.B ftp
sessions simultaneously.
The first
.B proxy
command should be:
.DM
	proxy open \fIotherremotehost\fR
.DE
.IP
This opens the connection with the
.IR otherremotehost .
Note that the following commands behave differently when run via
.BR proxy :
.RS
.IP \fBopen\fR
You cannot define new macros.
.IP \fBclose\fR
This command does not erase existing macros.
.IP "\fBget\fR, \fBmget\fR
These commands copy files from the primary remote host
to the secondary remote host.
.IP "\fBput\fR, \fBmput\fR, \fBappend\fR"
These commands copy files from the secondary remote host to the
primary remote host.
.RE
.IP
Whether you can transfer file between remote hosts depends upon whether the
.B ftp
server on the primary remote host supports this feature.
.IP "\fBput \fIlocalfile [\fIremotefile\^\fB]\fR"
Copy
.I remotefile
from your local host to the remote host.
If you name a
.IR remotefile ,
.B ftp
copies
.I localfile
into it; otherwise, it copies
.I localfile
into a file of the same name on the remote host.
If a file of that name exists on the remote host,
.B ftp
overwrites it.
.B ftp
assumes that
.I localfile
is in your current directory on the local host.
.IP \fBpwd\fR
Print your working directory on the remote host.
.IP \fBquit\fR
This command is a synonym for
.BR bye .
.IP "\fBquote \fIargument argument ...\fR"
Send each
.I argument
literally to the server on the remote host.
This lets you bypass any mechanisms you have already set up for
changing things automatically (e.g., transforming file names).
.IP "\fBrecv \fIremotefile \fB[\fIlocalfile\^\fB]\fR"
This is a synonym for the command
.BR get .
.IP "\fBremotehelp [\fIcommand\^\fB]\fR"
Ask the
.B ftp
server on the remote host to send you some information about
.IR command .
If you do not name a
.IR command ,
what you receive varies, depending on the implementation of the remote server.
.IP "\fBrename [\fIoldname\^\fB] [\fInewname\^\fB]\fR"
Rename file
.I oldname
on the remote host to
.IR newname .
.IP \fBreset\fR
Reset the reply queue.
This command helps the client and server to resynchronize themselves,
should they come out of step due to a violation of the
.B ftp
protocol.
.IP "\fBrmdir \fIdirectory\fR"
Remove
.I directory
from the remote host.
The remote host's operating system determines
who can remove which directories, and when they can be removed.
.IP \fBrunique\fR
Toggle whether
.B ftp
generates unique names for files being copied onto the local host.
If this feature is toggled on,
.B ftp
does not overwrite a file on your local host should an incoming file
have its name; rather, it appends the suffix
.B \&.1
onto the incoming file's name.
If the current directory on your local host already contains a file
with that name plus \fB.1\fR,
.B ftp
appends \fB.2\fR instead \(em and so on, through \fB.99\fR.
The default is off.
.IP "\fBsend \fIlocalfile \fB[\fIremotefile\^\fB]\fR"
This is a synonym for the command
.BR put .
.IP \fBsendport\fR
Toggle whether
.B ftp
uses
.B PORT
commands.
By default,
.B ftp
attempts to use a
.B PORT
command whenever it transfers a file to or from a remote host.
This can delay the transfer of files.
.\"If the
.\".B PORT
.\"command fails,
.\".B ftp
.\"uses the default data port.
.\"When you have disabled the use of
.\".B PORT
.\"commands,
.\".B ftp
.\"makes no attempt to use
.\".B PORT
.\"commands for each data transfer.
.\"This is useful for communicating with certain
.\"implementations of
.\".B ftp
.\"that ignore
.\".B PORT
.\"commands but, incorrectly, indicate that they have been accepted.
.IP "\fBstatus\fR"
Show the current status of
.BR ftp .
.IP "\fBstruct [\fIstructname\^\fB]\fR"
Set the file-transfer structure to
.IR structname .
By default,
.B ftp
uses the structure
.BR stream .
.IP \fBsunique\fR
Toggle the generation of unique file names for files being
copied onto the remote host.
This complements the command
.BR runique .
The rules by which unique names are generated depend upon the
.B ftp
server that is running on the remote system.
By default, this feature is toggled off.
.IP \fBtenex\fR
Set the file-transfer type to that required by
.BR tenex -based
machines.
.IP \fBtrace\fR
Toggle packet tracing.
.IP "\fBtype [\fItypename\^\fB]\fR"
Set the type of file transfer to
.IR typename .
If you invoke this command without an argument, it returns the type of
transfer now in use.
The default type is network ASCII.
.IP "\fBuser \fIname \fB[\fIpassword\^\fB] [\fIaccount\^\fB]\fR"
Identify yourself as user
.I name
to the
.B ftp
server on the remote host.
.I password
and
.I account
give, respectively, your password and the name of your
account on the remote host.
If you do not name these on the command line and the remote host requires
either,
.B ftp
will prompt you for them.
.IP \fBverbose\fR
Toggle verbose mode.
In verbose mode, the
.B ftp
client on your local host displays every response that it receives from the
server on the remote host, and summarizes the speed of transfer after
every file transfer.
The default is on.
.SH "Aborting a File Transfer"
To abort a file transfer, type \fB<ctrl-C>\fR.
.\"(your system's interrupt character).
How quickly a transfer from the remote host can be aborted
depends upon the remote server; in some cases, you may
not be able to abort such a transfer.
.SH "Conventions for Naming Files"
.B ftp
interprets file names as follows:
.IP \fB1.\fR 0.3i
.B ftp
interprets `-' to mean the standard input or output (depending on the context
in which it appears).
.IP \fB2.\fR
If the first character of a file name is `|',
.B ftp
interprets the rest of the entry as naming a command.
.B ftp
attempts to execute the named command on your local host, and pipes
the standard output to it.
For example, the command
.DM
	dir |more
.DE
.IP
executes the
.B ftp
command
.B dir
and pipes it output to the command
.B more
on your local host.
When used judiciously, this mechanism can be very helpful.
.IP \fB3\fR
.B ftp
expands wildcards in the usual manner.
To turn off wildcard expansion,
use the command
.BR glob .
.SH "The .netrc File"
.B ftp
automatically reads file \fB.netrc\fR from your home directory
when you invoke it.
This file can contain information with which
.B ftp
can automatically log you into a remote host, and can also define macros.
.PP
To auto-login to a remote host, your \fB.netrc\fR should have a line with
the following information:
.DS
.B
	host	username	password	account
.R
.DE
.PP
To define a macro in \fB.netrc\fR, use the command
.BR macdef ,
followed by the name of the macro being created.
The rest of the text on that line will compose the body of the macro.
If you define a macro named
.BR init ,
.B ftp
executes it automatically as soon as it has logged you into a remote host.
.SH "See Also"
.B
commands,
ftpd
.R
.br
Baker, S.:
Defense to the rescue.
\fIUNIX Review\fR, March 1992, pp. 13-22.
.SH Notes
If you wish, you can request detailed information on the File Transfer Protocol
from the National Information Center in Chantilly, Virginia.
Send mail to \fBservice@nic.ddn.mil\fR, and name \fBRFC 959\fR as the subject
of your message.
Please note that this document is long and very technical.
You can also down RFCs from UUNET.
