10.0;ftp (file_transfer_program), revision 1.0, 88/05/26
ftp - ARPANET file transfer program.
usage: ftp [-v] [-d] [-i] [-n] [-g] [host]
DESCRIPTION
ftp is the user interface to the ARPANET standard File Transfer Protocol
(FTP). The program allows you to transfer files to and from a remote
network site.
You can specify the client host with which ftp is to communicate on the
command line. If you do, ftp immediately attempts to establish a
connection to an FTP server on that host; otherwise, ftp enters its
command interpreter and awaits instructions from you. When ftp is
awaiting commands from you, it displays the prompt "ftp>".
COMMANDS
ftp: recognizes the following commands:
! [ command [ args ] ]
Invoke an interactive shell on the local machine. If you
specify arguments, ftp takes the first to be a command to
execute directly, with the rest of the arguments as its
arguments.
$ macro-name [ args ]
Execute the macro macro-name that was defined with the macdef
command. Arguments are passed to the macro unglobbed.
account [ passwd ]
Supply a supplemental password required by a remote system for
access to resources once a login has been successfully
completed. If you do not specify an argument, ftp prompts you
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 do
not specify remote-file, ftp uses the local filename, after
applying the changes required by any ntrans or nmap setting, to
name the remote file. ftp uses the current settings for type,
form, mode, and structure.
ascii Set the file transfer type to network ASCII. This is the
default type.
bell Arrange that a bell be sounded after each file transfer command
is completed.
binary Set the file transfer type to support binary image transfer.
bye Terminate the FTP session with the remote server and exit ftp.
An end-of-file also terminates the session and exits.
case Toggle remote computer filename case-mapping during mget
commands. When case is on (the 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 remote-
directory.
cdup Change the remote-machine working directory to the parent of
the current remote-machine working directory.
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. 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 single
linefeeds; when an ASCII-type transfer is made, you can
distinguish these linefeeds from a record delimiter only when
cr is off.
delete remote-file
Delete the file remote-file on the remote machine.
debug [ debug-value ]
Toggle debugging mode. If you specify an optional debug-value,
ftp uses it to set the debugging level. 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 directory,
remote-directory, and, optionally, place the output in local-
file. If you do not specify a directory, ftp uses the current
working directory on the remote machine. If you do not specify
a local file, or local-file is -, ftp sends output to the
terminal.
disconnect
A synonym for close.
form format
Set the file transfer form to format. The default and only
supported format is file.
get remote-file [ local-file ]
Retrieve the remote-file and store it on the local machine. If
you do nt specify the local filename, ftp gives it the same
name it has on the remote machine, subject to alteration by the
current case, ntrans, and nmap settings. ftp uses the current
settings for type, form, mode, and structure while transferring
the file.
glob Toggle filename expansion for mdelete, mget and mput. If you
turn globbing off with glob, ftp takes the filename arguments
literally and does not expand them. Globbing for mput is done
as in csh(1). For mdelete and mget, each remote filename 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 an ordinary filename: the exact
result depends on the foreign operating system and FTP server,
You can preview the results by executing `mls remote-files -'.
Note: mget and mput are not meant to transfer entire directory
subtrees of files. You can do that by transferring a tar(1)
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 do not specify an argument, ftp prints a list of the known
commands.
lcd [ directory ]
Change the working directory on the local machine. If you do
not specify a directory, ftp uses your home directory.
ls [ remote-directory ] [ local-file ]
Print an abbreviated listing of the contents of a directory on
the remote machine. If you do not specify remote-directory ,
ftp uses the current working directory. If you do not specify
a local file, or if local-file is -, ftp sends the output 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 is a limit of 16 macros and 4096 total
characters in all defined macros. Macros remain defined until
you execute a close command. 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'
signals that 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 character. Use
the '\' to prevent special treatment of the '$'.
mdelete [ remote-files ]
Delete the remote-files on the remote machine.
mdir remote-files local-file
This command works like dir, except that 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 execute a get
for each filename thus produced. See glob for details on the
filename expansion. Resulting filenames are then processed
according to case, ntrans, and nmap settings. Files are
transferred into the local working directory, which you can
change with `lcd directory'; You can create new local
directories with `! mkdir directory'.
mkdir directory-name
Make a directory on the remote machine.
mls remote-files local-file
This command is like ls, except that 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 mls output.
mode [ mode-name ]
Set the file transfer mode to mode-name. The default and only
supported mode-name is stream.
mput local-files
Expand wildcards in the list of local files given as arguments
and execute a put for each file in the resulting list. See
glob for details of filename expansion. Resulting filenames
are then processed according to ntrans and nmap settings.
nmap [ inpattern outpattern ]
Set or unset the filename-mapping mechanism. If you do not
specify an argument, the filename-mapping mechanism is unset.
If you specify an argument, nmap maps remote filenames during
mput commands and put commands issued without a specified
remote-target filename. and maps local filenames during mget
commands and get commands issued without a specified local-
target filename. This command is useful when you are
connecting to a non-UNIX remote computer with different file-
naming conventions or practices.
The mapping follows the pattern set by inpattern and
outpattern. Inpattern is a template for incoming filenames
(which may have already been processed according to the ntrans
and case settings). Include the sequences '$1', '$2', ...,
'$9' in inpattern, if you want variable templating. Use '\' to
prevent this special treatment of the '$' character. nmap
treats all other characters literally, and uses them to
determine the nmap inpattern variable values. For example,
given inpattern $1.$2 and the remote filename "mydata.data", $1
has the value "mydata", and $2 has 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 is not a null string;
otherwise it is replaced by seq2. For example, the command
nmap $1.$2.$3 [$1,$2].[$2,file] yields the output filename
myfile.data for input filenames myfile.data and
myfile.data.old, myfile.file for the input filename myfile; and
myfile.myfile for the input filename .myfile. You can include
spaces in outpattern, 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 mechanism. If
you do not specify an argument, the filename-character-
translation mechanism is unset. If you specify an argument,
ntrans translates characters in remote filenames during mput
commands and put commands issued without a specified remote-
target filename, and translates characters in local filenames
during mget commands and get commands issued without a
specified local-target filename.
This command is useful when you are connecting to a non-UNIX
remote computer with different file-naming conventions or
practices. ntrans replaces characters in a filename matching a
character in inchars with the corresponding character in
outchars. If the character's position in inchars is longer
than the length of outchars, ntrans deletes the character from
the filename.
open host [ port ]
Establish a connection to the specified host FTP server. You
can specify an optional port number, in which case ftp attempts
to contact an FTP server at that port. If the auto-login
option is on (default), ftp also attempts to automatically log
you in to the FTP server (see below).
prompt Toggle interactive prompting. Interactive prompting occurs
during multiple file transfers to allow you to 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 you to connect simultaneously to two remote FTP
servers for transferring files between them. 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: open does
not define new macros during the auto-login process, close does
not erase existing macro definitions, get and mget transfer
files from the host on the primary control connection to the
host on the secondary control connection, and put, mput, and
append transfer files from the host on the secondary control
connection to the host on the primary control 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 you do not
specify remote-file, put uses the local filename after
processing according to any ntrans or nmap settings in naming
the remote file. ftp uses the current settings for type,
form, mode, and structure.
pwd Print the name of the current working directory on the remote
machine.
quit This is a synonym for bye.
quote arg1 arg2 ...
This command sends the arguments you specify, verbatim, to the
remote FTP server.
recv remote-file [ local-file ]
This is a synonym for get.
remotehelp [ command-name ]
Request help from the remote FTP server. If a command-name is
specified it is supplied to the server as well.
rename [ from ] [ to ]
Rename the file from on the remote machine, to the file to.
reset Clear the reply queue. This command resynchronizes
command/reply sequencing with the remote FTP server.
Resynchronization may be necessary following a violation of the
FTP protocol by the remote server.
rmdir directory-name
Delete the specified directory on the remote machine.
runique Toggle storing of files on the local system with unique
filenames. If a file already exists with a name equal to the
target local filename for a get or mget command, runique
appends a .1 to the name. If the resulting name matches
another existing file, runique appends a .2 to the original
name. If this process continues up to .99, runique prints an
error message. ftp does not execute the transfer, and reports
the generated unique filename. Note that runique does not
affect local files generated from a shell command (see below).
The default value is off.
send local-file [ remote-file ]
This is 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 you
perform multiple file transfers. If the PORT command fails, ftp
uses the default data port. When the use of PORT commands is
disabled,ftp does not attempt to use PORT commands for each
data transfer. This is useful for certain FTP implementations
that ignore PORT commands but indicate, incorrectly, that they
are accepted.
status Show the current status of ftp.
struct [ struct-name ]
Set the file transfer structure to struct-name; either stream
or record. By default, struct uses stream structure.
sunique Toggle storing of files on remote machine under unique
filenames. The remote FTP server must support the FTP protocol
STOU command for successful completion. The remote server
reports unique names. The default value is off.
tenex Set the file transfer type to that needed to talk to TENEX
machines.
trace Toggle packet tracing.
type [ type-name ]
Set the file transfer type to type-name; one of ascii, binary,
image, or tenex. If you do not specify a type, type prints the
current type. The default type is ascii (network ASCII).
user user-name [ password ] [ account ]
Identify yourself to the remote FTP server. If the password is
not specified and the server requires it, ftp will prompt the
user for it (after disabling local echo). If the FTP server
requires an account field and you do not specify it, ftp
prompts for it. If you specify an account field, ftp relays an
account command to the remote server after the log-in sequence
is completed, if the remote server did not require it for
logging in. Unless you invoke ftp with "auto-login" disabled,
ftp executes this process automatically, on initial connection
to the FTP server.
verbose Toggle verbose mode. In verbose mode, ftp displays all
responses from the FTP server and also reports statistics
regarding the efficiency of a file transfer, when the transfer
completes. By default, verbose is on.
? [ command ]
This is a synonym for help.
You can enclose command arguments that have embedded spaces in quotation
(") marks.
ABORTING A FILE TRANSFER
Use the terminal interrupt key (usually CTRL/C) to abort a file transfer.
ftp immediately stops sending transfers. You can stop receiving
transfers by sending a FTP protocol ABOR command to the remote server and
discarding any further data received. The speed at which this is
accomplished depends on the remote server's support for ABOR processing.
If the remote server does not support the ABOR command, an "ftp>" prompt
does not appear until the remote server has completed sending the
requested file.
The terminal interrupt key sequence is 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 program by hand.
FILE-NAMING CONVENTIONS
ftp processes files that you specify as arguments according to the
following rules.
1) If you specify the filename as a dash (-), ftp uses stdin (for
reading) or stdout (for writing).
2) If the first character of the filename is "|", ftp interprets the
remainder of the argument as a shell command, then forks a shell,
using the UNIX popen subroutine with the argument you specify, and
reads (writes) from stdout (stdin). If the shell command includes
spaces, you must enclose the argument in quotation marks; for
example, ""| ls -lt"". A particularly useful example of this
mechanism is "dir |more".
3) Failing the above checks, if globbing is enabled, ftp expands local
filenames according to the rules used in the csh; See the glob
command for a comparison. If ftp expects a single local file (for
example, put), it uses only the first filename generated by the
"globbing" operation.
4) For mget commands and get commands with unspecified local filenames,
the local filename is the remote filename, that a case, ntrans, or
nmap setting can change. The remote server can then change the
resulting filename, if runique is on.
5) For mput commands and put commands with unspecified remote
filenames, the remote filename is the local filename, that a ntrans
or nmap setting can change. he remote server can then change the
resulting filename, if sunique is on.
FILE TRANSFER PARAMETERS
The FTP specification specifies many parameters that may affect a file
transfer. The type can be one of ascii, image (binary), ebcdic, and
local byte size. 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 transfer
parameters: mode, form, and struct.
OPTIONS
You can specify options on the command line, or to the command
interpreter.
-v (verbose on) Forces ftp to show all responses from the remote
server, as well as report on data transfer statistics.
-n Restrains ftp from attempting "auto-login" on initial
connection. If auto-login is enabled, ftp checks the .netrc
(see below) file in your home directory for an entry describing
an account on the remote machine. If no entry exists, ftp
prompts for the remote machine log-in name (the default is the
user identity on the local machine), and, if necessary, prompts
for a password and an account with which to log in.
-i Turns off interactive prompting during multiple file transfers.
-d Enables debugging.
-g Disables filename globbing.
THE .netrc FILE
The .netrc file contains log-in and initialization information used by
the auto-login process. It resides in your home directory. by spaces,
tabs, or newlines:
machine name
Identify a remote machine name. The auto-login process
searches the .netrc file for a machine token that matches the
remote machine specified on the ftp command line or as an open
command argument. Once a match is made, the subsequent .netrc
tokens are processed, stopping when the end-of-file is reached
or another machine token is encountered.
login name
Identify a user on the remote machine. If this token is
present, the auto-login process initiates a login using the
specified name.
password string
Supply a password. If this token is present, the auto-login
process supplies the string if the remote server requires a
password as part of the log-in process. Note that if this
token is present in the .netrc file, ftp aborts the auto-login
process if the .netrc is readable by anyone besides the user.
account string
Supply an additional account password. If this token is
present, the auto-login process supplies the string if the
remote server requires an additional account password, or the
auto-login process initiates an ACCT command if it does not.
macdef name
Define a macro. This token functions like the ftp macdef
command functions. A macro is defined with the specified name;
its contents begin with the next .netrc line and continue until
a null line (consecutive new-line characters) is encountered.
If a macro named init is defined, ftp automatically executes it
as the last step in the auto-login process.
CAUTIONS
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 UNIX 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.