.\" Copyright (c) 1983 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)ftp.1	6.2 (Berkeley) %G%
.\"
.TH FTP 1C ""
.UC 5
.SH NAME
ftp \- ARPANET file transfer program
.SH SYNOPSIS
.B ftp
[ 
.B \-v
] [
.B \-d
] [
.B \-i
] [
.B \-n
] [
.B \-g
] [
.B \-t
] [
.I host
]
.SH DESCRIPTION
.I Ftp
is the user interface to the ARPANET standard File Transfer Protocol.
\fIFtp\fP transfers files to and from a remote network site.
.LP
The client host with which 
.I ftp
is to communicate may be specified on the command line.
If this is done,
.I ftp
immediately attempts to establish a connection to an FTP server on that host;
otherwise, \fIftp\fP enters its command interpreter and awaits instructions
from the user.  When \fIftp\fP is awaiting commands from the user, it
displays the prompt \*(lqftp>\*(rq.  The following commands are recognized
by
.IR ftp :
.TP
\fB\&! \fR[ \fIcommand \fR]
Run
.I command
as a shell command on the local machine.
If no 
.I command
is given, invoke an interactive shell.
.TP
\fBappend\fP \fIlocal-file\fP [ \fIremote-file\fP ]
Append a local file to a file on the remote machine.  If
.I remote-file
is left unspecified, the local file name is used in naming the
remote file.  File transfer uses the current settings for
\*(lqrepresentation type\*(rq, \*(lqfile structure\*(rq,
and \*(lqtransfer mode\*(rq.
.TP
.B ascii
Set the \*(lqrepresentation type\*(rq
to \*(lqnetwork ASCII\*(rq.  This is the default type.
.TP
.B bell
Arrange that a bell be sounded after each file transfer
command is completed.
.TP
.B binary
Set the \*(lqrepresentation type\*(rq to \*(lqimage\*(rq.
.TP
.B bye
Terminate the FTP session with the remote server
and exit
.IR ftp .
.TP
.BI cd " remote-directory"
Change the working directory on the remote machine
to 
.IR remote-directory .
.TP
.B close
Terminate the FTP session with the remote server, and
return to the command interpreter.
.TP
.BI delete " remote-file"
Delete the file
.I remote-file
on the remote machine.
.TP
\fBdebug\fP [ \fIdebug-value\fP ]
Toggle debugging mode.  If an optional
.I debug-value
is specified it is used to set the debugging level.
When debugging is on,
.I ftp
prints each command sent to the remote machine, preceded
by the string \*(lq-->\*(rq.
.TP
\fBdir\fP [ \fIremote-directory\fP ] [ \fIlocal-file\fP ]
Print a listing of the directory contents in the
directory,
.IR remote-directory ,
and, optionally, placing the output in
.IR local-file .
If no directory is specified, the current working
directory on the remote machine is used.  If no local
file is specified, or \fIlocal-file\fP is \fB\-\fP,
output comes to the terminal.
.TP
\fBform\fP [ \fIformat-name\fP ]
Set the carriage control format subtype of the
\*(lqrepresentation type\*(rq to
.IR format-name .
The only valid
.I format-name
is
.BR non-print ,
which corresponds to the default \*(lqnon-print\*(rq subtype.
.TP
\fBget\fP \fIremote-file\fP [ \fIlocal-file\fP ]
Retrieve the 
.I 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.
The current settings for \*(lqrepresentation type\*(rq,
\*(lqfile structure\*(rq, and \*(lqtransfer mode\*(rq
are used while transferring the file.
.TP
\fBglob\fR
Toggle filename expansion, or "globbing",  
for \fBmdelete\fP, \fBmget\fP and \fBmput\fP.
If globbing is turned off, filenames are taken literally.
.IP
Globbing for \fBmput\fP is done as in \fIcsh\fP\|(1).
For \fBmdelete\fP and \fBmget\fP, each remote file name is
expanded separately on the remote machine, and the lists are not merged.
.IP
Expansion of a directory name is likely to be radically
different from expansion of the name of an ordinary file:
the exact result depends on the remote operating system and
FTP server,
and can be previewed by doing `\fBmls\fP\ \fIremote-files\fP\ \fB\-\fP'.
.IP
\fBmget\fP and \fBmput\fP are not meant to transfer
entire directory subtrees of files.  You can do this by
transferring a \fItar\fP\|(1) archive of the subtree (using a
\*(lqrepresentation type\*(rq of \*(lqimage\*(rq as set by the
.B binary
command).
.TP
\fBhash\fP
Toggle hash-sign (``#'') printing for each data block
transferred.  The size of a data block is 1024 bytes.
.TP
\fBhelp\fP [ \fIcommand\fP ]
Print an informative message about the meaning of
.IR command .
If no argument is given, 
.I ftp
prints a list of the known commands.
.TP
\fBlcd\fP [ \fIdirectory\fP ]
Change the working directory on the local machine.  If
no 
.I directory
is specified, the user's home directory is used.
.TP
\fBls\fP [ \fIremote-directory\fP ] [ \fIlocal-file\fP ]
Print an abbreviated listing of the contents of a
directory on the remote machine.  If
.I remote-directory
is left unspecified, the current working directory
is used.  If no local file is specified, 
or if \fIlocal-file\fR is \fB\-\fR,
the output is sent to the terminal.
.TP
\fBmdelete\fP [ \fIremote-files\fP ]
Delete the \fIremote-files\fP on the remote machine.
.TP
\fBmdir\fP \fIremote-files\fP \fIlocal-file\fP
Like \fBdir\fP, except multiple remote files may be specified.
.TP
\fBmget\fP \fIremote-files\fP
Expand the \fIremote-files\fP on the remote machine
and do a \fBget\fP for each file name thus produced.
See \fBglob\fR for details on the filename expansion.
Files are transferred into the local working directory,
which can be changed with `\fBlcd\fP\ \fIdirectory\fP';
new local directories can be created with
`\fB!\fP\ \fBmkdir\fP\ \fIdirectory\fP'.
.TP
\fBmkdir\fP \fIdirectory-name\fP
Make a directory on the remote machine.
.TP
\fBmls\fP \fIremote-files\fP \fIlocal-file\fP
Like \fBls\fP, except multiple remote files may be specified.
.TP
\fBmode\fP [ \fImode-name\fP ]
Set the \*(lqtransfer mode\*(rq to
.IR mode-name .
The only valid
.I mode-name
is
.BR stream ,
which corresponds to the default \*(lqstream\*(rq mode.
.TP
\fBmput\fP \fIlocal-files\fP
Expand wild cards in the list of local files given as arguments
and do a \fBput\fR for each file in the resulting list.
See \fBglob\fP for details of filename expansion.
.TP
\fBopen\fP \fIhost\fP [ \fIport\fP ]
Establish a connection to the specified
.I host
FTP server.  An optional port number may be supplied,
in which case, 
.I ftp
will attempt to contact an FTP server at that port.
If the 
.I auto-login
option is on (default), 
.I ftp
will also attempt to automatically log the user in to
the FTP server (see below).
.TP
.B prompt
Toggle interactive prompting.  Interactive prompting
occurs during multiple file transfers to allow the
user to selectively retrieve or store files.
By default, prompting is turned on.
If prompting is turned off, any \fBmget\fP or \fBmput\fP
will transfer all files, and any \fBmdelete\fP will delete all files.
.TP
\fBput\fP \fIlocal-file\fP [ \fIremote-file\fP ]
Store a local file on the remote machine.  If 
.I remote-file
is left unspecified, the local file name is used
in naming the remote file.  File transfer uses the
current settings for \*(lqrepresentation type\*(rq,
\*(lqfile structure\*(rq, and \*(lqtransfer mode\*(rq.
.TP
.B pwd
Print the name of the current working directory on the remote
machine.
.TP
.B quit
A synonym for \fBbye\fP.
.TP
\fBquote\fP \fIarg1\fP \fIarg2\fP ...
Send the arguments specified, verbatim, to the remote FTP
server.  A single FTP reply code is expected in return.
.TP
\fBrecv\fP \fIremote-file\fP [ \fIlocal-file\fP ]
A synonym for \fBget\fP.
.TP
\fBremotehelp\fP [ \fIcommand-name\fP ]
Request help from the remote FTP server.  If a 
.I command-name
is specified it is supplied to the server as well.
.TP
\fBrename\fP \fIfrom\fP \fIto\fP
Rename the file
.I from
on the remote machine to have the name
.IR to .
.TP
.BI rmdir " directory-name"
Delete a directory on the remote machine.
.TP
\fBsend\fP \fIlocal-file\fP [ \fIremote-file\fP ]
A synonym for \fBput\fP.
.TP
.B sendport
Toggle the use of PORT commands.  By default, 
.I ftp
will attempt to use a PORT command when establishing
a connection for each data transfer.  If the PORT
command fails, 
.I 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 ignore PORT
commands but incorrectly indicate they've been accepted.
.TP
.B status
Show the current status of
.IR ftp .
.TP
\fBstruct\fP [ \fIstruct-name\fP ]
Set the \*(lqfile structure\*(rq to
.IR struct-name .
The only valid
.I struct-name
is
.BR file ,
which corresponds to the default \*(lqfile\*(rq structure.
.TP
.B tenex
Set the \*(lqrepresentation type\*(rq to that needed to
talk to TENEX machines.
.TP
.B trace
Toggle packet tracing (unimplemented).
.TP
\fBtype\fP [ \fItype-name\fP ]
Set the \*(lqrepresentation type\*(rq to
.IR type-name .
The valid
.IR type-name s
are
.B ascii
for \*(lqnetwork ASCII\*(rq,
.B binary
or
.B image
for \*(lqimage\*(rq,
and
.B tenex
for \*(lqlocal byte size\*(rq with a byte size of 8 (used to talk to
TENEX machines).
If no type is specified, the current type
is printed.  The default type is \*(lqnetwork ASCII\*(rq.
.TP
\fBuser\fP \fIuser-name\fP [ \fIpassword\fP ] [ \fIaccount\fP ]
Identify yourself to the remote FTP server.  If the
password is not specified and the server requires it,
.I ftp
will prompt 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.  Unless
.I ftp
is invoked with \*(lqauto-login\*(rq disabled, this
process is done automatically on initial connection to
the FTP server.
.TP
.B verbose
Toggle verbose mode.  In verbose mode, all responses from
the FTP server are displayed to the user.  In addition,
if verbose mode is on, when a file transfer completes, statistics
regarding the efficiency of the transfer are reported.  By default,
verbose mode is on if
.IR ftp 's
commands are coming from a terminal, and off otherwise.
.TP
\fB?\fP [ \fIcommand\fP ]
A synonym for \fBhelp\fP.
.LP
Command arguments which have embedded spaces may be quoted with
quote (") marks.
.LP
If any command argument which is not indicated as being optional is
not specified,
.I ftp
will prompt for that argument.
.SH "FILE NAMING CONVENTIONS"
Local files specified as arguments to
.I ftp
commands are processed according to the following rules.
.TP
1)
If the file name \*(lq-\*(rq is specified, the
standard input (for reading) or standard output
(for writing) is used.
.TP
2)
If the first character of the file name is \*(lq|\*(rq, the
remainder of the argument is interpreted as a shell command.
.I ftp
then forks a shell, using 
.IR popen (3S)
with the argument supplied, and reads (writes) from the standard output
(standard input) of that shell.  If the shell command includes spaces,
the argument
must be quoted; e.g. \*(lq"| ls -lt"\*(rq.  A particularly
useful example of this mechanism is: \*(lqdir |more\*(rq.
.TP
3)
Failing the above checks, if ``globbing'' is enabled,
local file names are expanded
according to the rules used in the 
.IR csh (1);
c.f. the
.I glob
command.
.LP
Note that remote file names are not processed, but are passed just as they
are typed, except for the \fBmdelete\fP, \fBmdir\fP, \fBmget\fP,
and \fBmls\fP commands, where they are expanded according to the rules of
the remote host's operating system, if any.
.SH "FILE TRANSFER PARAMETERS"
The FTP specification specifies many parameters which may
affect a file transfer.
.LP
The \*(lqrepresentation type\*(rq
may be one of \*(lqnetwork ASCII\*(rq, \*(lqEBCDIC\*(rq, \*(lqimage\*(rq,
or \*(lqlocal byte size\*(rq with a specified byte size (for PDP-10's
and PDP-20's mostly).  The \*(lqnetwork ASCII\*(rq and \*(lqEBCDIC\*(rq
types have a further subtype which specifies whether vertical format control
(newlines, form feeds, etc.) are to be passed through (\*(lqnon-print\*(rq),
provided in TELNET format (\*(lqTELNET format controls\*(rq),
or provided in ASA (FORTRAN) (\*(lqcarriage control (ASA)\*(rq) format.
.I ftp
supports the \*(lqnetwork ASCII\*(rq (subtype \*(lqnon-print\*(rq only)
and \*(lqimage\*(rq types, plus \*(lqlocal byte size\*(rq
with a byte size of 8 for communicating with TENEX machines.
.LP
The \*(lqfile structure\*(rq may be one of \*(lqfile\*(rq
(no record structure), \*(lqrecord\*(rq, or \*(lqpage\*(rq.
.I ftp
supports only the default value, which is \*(lqfile\*(rq.
.LP
The \*(lqtransfer mode\*(rq may be one of \*(lqstream\*(rq,
\*(lqblock\*(rq, or \*(lqcompressed\*(rq.
.I ftp
supports only the default value, which is \*(lqstream\*(rq.
.SH OPTIONS
Options may be specified at the command line, or to the 
command interpreter.
.TP
.B \-v
show all responses from the remote server, as well
as report on data transfer statistics.  This is turned on by
default if
.I ftp
is running interactively with its input coming from the user's terminal.
.TP
.B \-n
do not attempt \*(lqauto-login\*(rq upon initial connection.
If auto-login is enabled, 
.I ftp
checks the
.BI . netrc
file in the user's home directory for an entry describing
an account on the remote machine.  If no entry exists,
.I ftp
uses the login name on the local machine as the user
identity on the remote machine, and prompts for a password
and, optionally, an account with which to login.
.TP
.B \-i
turn off interactive prompting during multiple file transfers.
.TP
.B \-g
disable filename "globbing."
.TP
.B \-d
enable debugging.
.TP
.B \-t
enable packet tracing (unimplemented).
.SH "SEE ALSO"
rcp(1), ftpd(8c)
.SH BUGS
Many FTP server implementations do not support experimental
operations such as print working directory.
.PP
Aborting a
.B get
often causes the connection to be closed;
aborting a
.B put
gives no indication that the transfer failed to complete.