 |
Click this button to go to the index for this section. |
ftp(1)
NAME
ftp - Transfers files between a local and a remote host
SYNOPSIS
ftp [-dginptv] [host]
The ftp command is the interface to the File Transfer Protocol (FTP). This
command uses FTP to transfer files between the local host and a remote host
or between two remote hosts.
OPTIONS
The following options can be entered on the shell command line. (The ftp
command equivalents can also be entered at the ftp> prompt.)
-d Enables debugging by turning on the logging feature. See the debug
subcommand.
-g Disables the expansion of metacharacters in filenames. Interpreting
metacharacters may be referred to as expanding (sometimes called
globbing) a filename. See the glob subcommand.
-i Disables interactive prompting during multiple file transfers. See the
prompt, mget, mput, and mdelete subcommands for descriptions of
prompting during multiple file transfers.
-n Prevents an automatic login on the initial connection. Otherwise, ftp
searches for a $HOME/.netrc entry that describes the login and
initialization process for the remote host. See the user subcommand.
-p Enables the interpretation of the vertical bar (|) as a pipe symbol
when it is the first character in a file name. See the pipe
subcommand.
-t Toggles packet tracing (see trace subcommand).
-v Displays all the responses from the remote server and provides data
transfer statistics. This is the default display mode when the output
of the ftp command is to a device, such as the console or a display.
However, if output is redirected, such as through a pipe or to a file,
or if the ftp command is started by a daemon, such as the cron daemon,
verbose mode is not in effect unless the -v option or the verbose
subcommand is used. See the verbose subcommand.
DESCRIPTION
The FTP protocol is designed to allow transferring data between hosts that
use dissimilar file systems. Therefore, although the protocol provides a
lot of flexibility for transferring data, it does not attempt to preserve
file attributes that are specific to a particular file system (for example,
the protection mode or modification times of a file). Additionally, the FTP
protocol makes few assumptions about the overall structure of a file system
and does not provide or allow such things as recursively copying
subdirectories.
Note that if you are transferring files between DIGITAL UNIX systems (or
other systems compatible with the UNIX operating system) and need to
preserve file attributes or need to recursively copy subdirectories, you
can use the rcp command.
The ftp command provides subcommands for tasks such as listing remote
directories, changing the current local and remote directory, transferring
multiple files in a single request, creating and removing directories, and
escaping to the local shell to perform shell commands. The ftp command
also provides for security by sending passwords to the remote host and
permits automatic login, file transfer, and logoff.
If you execute ftp and do not specify a hostname, ftp immediately displays
the ftp> prompt and waits for an ftp subcommand. To connect to a remote
host, you then execute the open subcommand. When the ftp command connects
to the remote host, ftp then prompts for the username and password before
displaying the ftp> prompt again. The ftp command fails if no password is
defined at the remote host for the specified username.
If you do specify the name of a remote host, ftp immediately tries to
establish a connection to the specified host. If ftp connects
successfully, ftp searches for a local $HOME/.netrc file in your current
directory or home directory. If the file exists, ftp searches the file for
an entry that initiates the login process and command macro definitions for
the remote host. If the $HOME/.netrc file or autologin entry does not
exist, ftp prompts you for a username and password. This occurs whether or
not the hostname is entered on the command line.
If ftp finds a $HOME/.netrc autologin entry for the specified host, ftp
attempts to use the information in that entry to automatically log in to
the remote host. The ftp command also loads any command macros defined in
the entry. In some cases (for example, when the required password is not
listed in an autologin entry), ftp prompts for the password before
displaying the ftp> prompt. Once ftp completes the autologin process, ftp
executes the init macro if the macro is defined in the autologin entry. If
the init macro does not exist or does not contain a quit or bye command,
ftp then displays the ftp> prompt and waits for a subcommand.
The remote username that you specify either at the prompt or in a
$HOME/.netrc file must exist and have a password defined at the remote host
or ftp fails. In addition, the remote user's shell must be listed in the
/etc/shells file.
Users are authenticated as described in ftpd(8). The ftpd(8) reference
page also describes anonymous FTP configuration.
The ftp command interpreter, which handles all commands entered at the ftp>
prompt, provides facilities that are not available with most file transfer
programs, such as: the handling of filename arguments to ftp commands, the
ability to collect a group of commands into a single command macro, and the
ability to load macros from a $HOME/.netrc file. These facilities are
designed to allow simplifying repeated tasks and to allow using ftp in
unattended mode.
The command interpreter handles filename arguments according to the
following rules:
· If a - (dash) is specified for the argument, standard input is used
for read operations and standard output is used for write operations.
· If the first character of the filename is a vertical bar (|), 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 (writes) from stdout (stdin). By default, this feature is
disabled. See the pipe subcommand. If the shell command includes
spaces, the argument must be quoted; for example, | ls -lt. A
particularly useful example of this mechanism is dir |more.
· Failing the above checks, if globbing is enabled, local filenames are
expanded according to the rules used in csh; see the glob subcommand.
If the ftp command expects a single local file (for example, put),
only the first filename generated by the globbing operation is used.
· For get and mget subcommands with unspecified local filenames, the
local filename is the same as the remote filename, which may be
altered by a case, ntrans, or nmap setting. The resulting filename
can then be altered if runique is on.
· For mput commands and put commands with unspecified remote filenames,
the remote filename is the same as the local filename, which can be
altered by a ntrans or nmap setting. The resulting filename can then
be altered by the remote server if sunique is on.
Note that the ftp command interpreter does not support pipes.
To end an ftp session when you are running interactively, use the bye or
quit subcommand or the End-of-File key sequence at the ftp> prompt. To end
a file transfer before it has been completed, use the Interrupt key
sequence. The default Interrupt key sequence is <Ctrl-c>.
The stty command can be used to redefine this key sequence. Sending
transfers (those from the local host to the remote host) are normally
halted immediately. Receiving transfers are halted by sending an FTP ABOR
instruction to the remote FTP server and discarding all incoming file
transfer packets until the remote server stops sending them.
If the remote server does not support the ABOR instruction, the ftp> prompt
will not appear until the remote server has sent all of the requested file.
Additionally, if the remote server does something unexpected, the local ftp
process may need to be ended manually.
The ftp command uses the default Type-of-Service values recommended by
RFC1060, which are as follows:
ftp-control
Low delay
ftp-data
High throughput
You can configure these values by specifying them in the /etc/iptos file.
For more information, see iptos(4).
SUBCOMMANDS
The following ftp subcommands can be entered at the ftp> prompt. If an
argument for a subcommand includes spaces, enclose the argument within
(double quotes).
![command [argument ...]]
Invokes an interactive shell on the local host. An optional command,
with one or more optional arguments, can be specified.
$ macro [argument ...]
Executes the specified macro, previously defined with the macdef
subcommand. Arguments are not expanded. See the macdef subcommand for
further information.
? [subcommand]
Displays a help message describing the subcommand. If you do not
specify subcommand, ftp displays a list of known subcommands.
account [password]
Sends a supplemental password that a remote host may require before
granting access to its resources. If the password is not supplied with
the command, you are prompted for the password. The password does not
appear on the screen.
append local_file [remote_file]
Appends a local file to a file on the remote host. If the remote
filename is not specified, the local filename is used, altered by any
setting made with the ntrans or nmap subcommand. The append subcommand
uses the current values for form, mode, struct, and type while
appending the file. For more information on these subcommands, see
their individual descriptions.
ascii
Sets the file transfer type to network ASCII. This ft command is the
default when ftp cannot determine that the remote system is a UNIX
system. File transfer may be more efficient with binary-image transfer.
bell
Sounds a bell after the completion of each file transfer.
binary
Sets the file transfer type to binary image, by default, if ftp can
determine that the remote system is a UNIX system. This can be more
efficient than an ASCII transfer.
bye Ends the File Transfer session and exits ftp. Same as quit.
case
Sets a toggle for the case of filenames. When case is on, remote
filenames that appear in all capital letters are changed from uppercase
to lowercase when written in the local directory. The default is off
(uppercase remote filenames are written in uppercase in the local
directory).
cd remote_directory
Changes the remote working directory to the specified directory.
cdup
Changes the working directory on the remote host to the parent of the
current directory.
close
Ends the File Transfer session, but does not exit ftp. Defined macros
are erased. Same as disconnect.
cr Strips the carriage-return character from a carriage-return/linefeed
sequence when receiving records during ASCII-type file transfers. (The
ftp command terminates each ASCII-type record with a carriage-
return/linefeed sequence during file transfers.) This conforms with
the DIGITAL UNIX and UNIX system convention for terminating records
with a single linefeed. Records on remote hosts that have different
record termination conventions may have single linefeeds imbedded in
records. To distinguish these imbedded linefeeds from record
delimiters, set cr to off. The cr subcommand toggles between on and
off.
delete remote_file
Deletes the specified remote file.
debug [on | off]
Prints each command sent to the remote host preceded by the string -->
when debug on is specified.
dir [remote_directory][local_file]
Writes a listing of the contents of remote_directory to the file
local_file. If remote_directory is not specified, dir lists the
contents of the current remote directory. If local_file is not
specified or is a - (dash), dir displays the listing on the local
terminal.
disconnect
See close.
form format
Specifies the form of the file transfer. The only format available is
non-print.
get remote_file [local_file]
Copies the remote file to the local host. If local_file is not
specified, the remote filename is used locally and is altered by any
settings made by the case, ntrans, and nmap subcommands. The ftp
command uses the current settings for type, form, mode, and struct
while transferring the file. For additional information, refer to the
description of each of these subcommands.
glob
Toggles filename expansion (globbing) for mdelete, mget, and mput. If
globbing is off, filename arguments for these subcommands are not
expanded. When globbing is enabled and a pattern-matching character is
used in a subcommand that expects a single filename, results may be
different than expected. For example, the append and put subcommands
perform filename expansion and then use only the first filename
generated. Other ftp subcommands, such as cd, delete, get, mkdir,
rename, and rmdir, do not perform filename expansion and take the
pattern-matching characters literally. Globbing for the mput subcommand
is done locally in the same way as for the csh command. For mdelete
and mget, each filename is expanded separately at the remote machine
and the lists are not merged. The expansion of a directory name may be
different than the expansion of a filename, depending on the remote
host and the ftp server. To preview the expansion of a directory name,
use the mls subcommand:
mls remote_file -
To transfer an entire directory subtree of files, transfer a tar
archive of the subtree in binary form, rather than using mget or mput.
hash
Toggles # (hash sign) printing. When hash is on, ftp displays one hash
sign for each data block (1024 bytes) transferred.
help [subcommand]
Displays help information. Refer to the ? subcommand.
lcd [directory]
Changes the working directory on the local host. If you do not specify
a directory, ftp uses your home directory.
ls [remote_directory] [local_file]
Writes an abbreviated file listing of a remote directory to a local
file. If remote_directory is not specified, ftp lists the current
remote directory. If local_file is not specified or is a - (dash), ftp
displays the listing on the local terminal.
macdef macro
Defines a subcommand macro. Subsequent lines up to a null line (two
consecutive linefeeds) are saved as the text of the macro. Up to 16
macros containing at most 4096 bytes for all macros can be defined.
Macros remain defined until redefined or a close is executed.
The special characters $ (dollar sign) and \ (backslash) have special
uses in ftp macros. A $ followed by one or more numbers is replaced by
the corresponding macro parameter on the invocation line (refer to the
$ subcommand). A $ followed by an i indicates that the macro is to
loop, with $i being replaced by consecutive parameters on each pass.
The first macro parameter is used on the first pass, the second
parameter is used on the second pass, and so on. A \ prevents special
treatment of the next character. Use the \ to turn off the special
meanings of $ and \.
mdelete remote_files
Expands remote_files and deletes the indicated remote files.
mdir [remote_directory ... local_file]
Expands remote_directory at the remote host and writes a listing of the
contents of the remote_directory to the local_file. If the
remote_directory argument contains a pattern-matching character, mdir
prompts for a local_file if none is specified. If the remote_directory
argument is a list of remote directories, separated by spaces, the last
argument in the list must be either a local filename or a - (dash). If
local_file is -, mdir displays the listing on the local terminal. If
interactive prompting is on (refer to the prompt subcommand), ftp
prompts you to verify that the last argument is a local file and not a
remote directory.
mget remote_file ...
Expands remote_files at the remote host and copies the indicated remote
files to the current directory on the local host. Refer to the glob
subcommand for more information on filename expansion. The remote
filenames are used locally and are altered by any settings made by the
case, ntrans, and nmap subcommands. The ftp command uses the current
settings for type, form, mode, and structure while transferring the
files. Refer to the description of each of these subcommands for
additional information.
mkdir [remote_directory]
Creates the directory remote_directory on the remote host.
mls [remote_directory ... local_file]
Expands remote_directory at the remote host and writes an abbreviated
file listing of the indicated remote directories to a local file. If
the remote_directory argument contains a pattern-matching character,
mls prompts for a local_file if none is specified. If the
remote_directory argument is a list of remote directories, separated by
spaces, the last argument in the list must be either a local filename
or a - (dash). If local_file is -, mls displays the listing on the
local terminal. If interactive prompting is on (refer to the prompt
subcommand), ftp prompts you to verify that the last argument is a
local file and not a remote directory.
mode [mode]
Sets file transfer mode. The only mode available is stream.
modtime [remote_file]
Shows the last modification time of file on the remote machine.
mput [local_file ...]
Expands local_file at the local host and copies the indicated local
files to the remote host. Refer to the glob subcommand for more
information on filename expansion. The local filenames are used at the
remote host and are altered by any settings made by the ntrans and nmap
subcommands. The ftp command uses the current settings for type, form,
mode, and structure while transferring the files. Refer to the
description of each subcommand for additional information.
nlist [remote_directory] [local_file]
Prints a list of the files of a directory on the remote machine. If
remote_directory is left unspecified, the current working directory is
used. If interactive prompting is on, ftp prompts the user to verify
that the last argument is indeed the target local file for receiving
nlist output. If no local file is specified, the output is sent to the
terminal.
nmap [inpattern outpattern]
Sets or unsets the filename mapping mechanism. If no arguments are
specified, filename mapping is turned off. If arguments are specified,
source filenames are mapped for mget and mput operations and for get
and put operations when the destination filename is not specified.
This subcommand is useful when the local and remote hosts use different
filenaming conventions or practices. Mapping follows the pattern set
by inpattern and outpattern.
The inpattern variable specifies the template for incoming filenames,
which may have already been processed according to the case and ntrans
settings. The template variables $1 through $9 can be included in
inpattern. All characters in inpattern other than $ and protected $s
(that is, \$) define the values of the template variables. For
example, if the inpattern is $1.$2 and the remote filename is
mydata.dat, the value of $1 is mydata and the value of $2 is dat.
The outpattern variable determines the resulting filename. The
variables $1 through $9 are replaced by their values as derived from
inpattern and the variable $0 is replaced by the original filename.
Additionally, the sequence [sequence1,sequence2] is replaced by the
value of sequence1 if sequence1 is not null; otherwise, it is replaced
by the value of sequence2. For example, the following subcommand would
yield myfile.data from myfile.data or myfile.data.old, myfile.file from
myfile, and myfile.myfile from .myfile:
nmap $1.$2.$3 [$1,$2].[$2,file]
Spaces can be included in outpattern. Use the \ (backslash) character
to prevent the special meanings of $, [, ], and , (comma) in
outpattern.
ntrans [in_characters [out_characters]]
Sets or unsets the filename character translation mechanism. If no
arguments are specified, character translation is turned off. If
arguments are specified, characters in source filenames are translated
for mget and mput operations and for get and put operations when the
destination filename is not specified. This subcommand is useful when
the local and remote hosts use different file naming conventions or
practices. Character translation follows the pattern set by
in_characters and out_characters. Characters in a source filename
matching characters in in_characters are replaced by the corresponding
characters in out_characters. If the string in_characters is longer
than the string out_characters, characters in in_characters are deleted
if they have no corresponding character in out_characters.
open host [port]
Establishes a connection to the FTP server at the specified host. If
the optional port number is specified, ftp will attempt to connect to a
server at that port. If the autologin feature is set (that is, -n was
not specified on the command line), ftp will attempt to automatically
log you in to the FTP server. You must also have a $HOME/.netrc file
with the correct information in it and the correct permissions set.
pipe
Toggles the interpretation of the vertical bar (|) as the pipe symbol
when it is the first character in a file name. If the interpretation
is off (the default), the vertical bar is interpreted as a regular
character and has no special meaning. Otherwise, the vertical bar (|)
indicates that the remainder of the argument is interpreted as a shell
command.
prompt
Toggles interactive prompting. If interactive prompting is on (the
default), ftp prompts for verification before retrieving, sending, or
deleting multiple files during mget, mput, and mdelete operations.
Otherwise, ftp will perform the operation on all files specified.
proxy [subcommand]
Executes an ftp command on a secondary control connection. This
subcommand allows ftp to simultaneously connect to two remote FTP
servers for transferring files between the two servers. To establish
the secondary control connection, specify open as the first proxy
subcommand. Enter the subcommand proxy ? to see the other ftp
subcommands that are executable on the secondary connection. The
following subcommands behave differently when prefaced by proxy:
·
The open subcommand does not define new macros during the autologin
process.
·
The close subcommand does not erase existing macro definitions.
·
The get and mget subcommands transfer files from the host on the
primary connection to the host on the secondary connection.
·
The put, mput, and append subcommands transfer files from the host on
the secondary connection to the host on the primary connection. File
transfers require that the FTP server on the secondary connection
support the PASV (passive) instruction.
put local_file [remote_file]
Stores a local file on the remote host. If you do not specify
remote_file, ftp uses the local filename to name the remote file, and
the remote filename is altered by any settings made by the ntrans and
nmap subcommands. The ftp command uses the current settings for type,
form, mode, and structure while transferring the files. Refer to the
description of each subcommand for additional information.
pwd Displays the name of the current directory on the remote host.
quit
Ends the file transfer session and exits ftp. A synonym for bye.
quote string
Sends the specified string verbatim to the remote host. Unpredictable
results can occur when you quote commands that involve data transfers.
recv remote_file [local_file]
Copies the remote file to the local host. A synonym for get.
reget remote_file [local_file]
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 subcommand is useful when transferring very large files
over networks that are prone to dropping connections.
remotehelp [subcommand]
Requests help from the remote FTP server.
rename from to
Renames a file on the remote host.
reset
Clears the reply queue. This command resynchronizes the command
parsing.
restart marker
Restarts the immediately following get or put at the indicated marker.
On systems that treat files as unstructured byte arrays (such as
DIGITAL UNIX and UNIX systems), marker is simply a byte offset into the
file.
rmdir remote_directory
Removes the directory remote_directory at the remote host.
runique
Toggles whether unique filenames are created for local destination
files during get and mget operations. If creating unique local
filenames is not enabled (the default), ftp overwrites local files.
Otherwise, if a local file has the same name as specified for a local
destination file, ftp modifies the specified name of the local
destination file with .1. If a local file is already using the new
name, ftp appends the postfix .2 to the specified name. If a local
file is already using this second name, ftp continues incrementing the
postfix until it either finds a unique filename or reaches .99 without
finding a unique name. If ftp cannot find a unique name, ftp reports
an error and the transfer does not take place. Note that runique does
not affect local filenames generated from a shell command.
send local_file [remote_file]
Stores a local file on the remote host. A synonym for put.
sendport
Toggles the use of FTP PORT instructions. By default, ftp uses a PORT
instruction when establishing a connection for each data transfer. When
the use of PORT instructions is disabled, ftp does not use PORT
instructions for data transfers. The PORT instruction is useful when
dealing with FTP servers that ignore PORT instructions while
incorrectly indicating they were accepted.
size
Returns the size of file on the remote machine in bytes.
status
Displays current status of ftp.
struct [structure]
Sets data transfer structure type. The only structure supported is
file.
sunique
Toggles whether unique filenames are created for remote destination
files during put and mput operations. If creating unique remote
filenames is not enabled (the default), ftp overwrites remote files.
Otherwise, if a remote file has the same name as specified for a remote
destination file, the remote FTP server modifies the name of the remote
destination file. Note that the remote server must support the STOU
instruction.
system
Shows the type of operating system running on the remote machine.
tenex
Sets the file transfer type to that needed for TENEX machines.
trace
Toggles packet tracing.
type [type]
Sets the file transfer type to type. If type is not specified, the
current type is printed. The default type is ASCII.
user user [password] [account]
Identifies the local user as user to the remote FTP server. If
password or account is not specified and the remote server requires it,
ftp prompts for it locally. If account is required, ftp sends it to
the remote server after the remote login process completes.
Note that, unless autologin is disabled by specifying -n on the command
line, this process is done automatically for the initial connection to
the remote server. You also need a $HOME/.netrc file in your home
directory to issue an autologin.
verbose
Toggles verbose mode. When verbose mode is on (the default), ftp
displays all responses from the remote FTP server. Additionally, ftp
displays statistics on all file transfers when the transfers are
completed.
Aborting a File Transfer
To abort a file transfer, use the Interrupt key sequence (often <Ctrl-c>).
Sending transfers are immediately halted. Receiving transfers are halted
by sending an FTP protocol ABOR command to the remote server, and
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 does not support the ABOR command, the prompt ftp>
does not appear until the remote server has completed sending the requested
file.
The 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, the
local ftp program must be killed by hand.
EXAMPLES
1. This example shows how user smith, who is logged in on host1, can log
in on the remote host host2, check the current working directory on
host2 and list its contents, transfer a file, and then end the
session.
$ ftp host2
If the connection to host2 is successful, a verification message is
displayed on the local system:
Connected to host2.abc.org
220 host2 FTP server (Version ...) ready.
Name (host2:smith): smith
Password:
Enter your name and password when prompted by the system. A message
similar to the following is then displayed on your local system:
230 User smith logged in
ftp> _
To set the file transfer type to binary, enter the binary subcommand
after the ftp> prompt:
ftp> binary
A message similar to the following is displayed on your local system:
200 Type set to I
To check the current working directory, enter the pwd command after
the ftp> prompt:
ftp> pwd
A message similar to the following is displayed on your local system:
257 "u/smith" is current directory
To list the contents of the current working directory, enter the ls
command after the ftp> prompt:
ftp> ls
A message similar to the following is displayed on your local system:
200 PORT command successful.
150 Opening data connection for /usr/bin/ls
(555.5.55.555) (0 bytes)
printfile
testfile
226 Transfer complete.
(The Opening data connection message appears on one line, not on two
lines as shown above.) To transfer a file from the remote host to the
local host, enter the get or mget subcommand following the ftp>
prompt:
ftp> get testfile tmp.testfile
A message similar to the following is displayed on your local system:
200 PORT command successful.
150 Opening data connection for testfile
(555.5.55.555) (1201 bytes)
226 Transfer complete.
local:tmp.testfile remote:testfile
(The Opening data connection message appears on one line, not on two
lines as shown above.) To end the ftp session, enter the quit
subcommand after the ftp> prompt:
ftp> quit
221 Goodbye.
$ _
2. This example shows how user smith, who is logged in on host1, can log
in as the user smith on the remote host host2:
$ ftp host2
Connected to host2.abc.org
220 host2 FTP server (Version ...) ready.
Name (host2:smith):
331 Passwd required for smith
Password:
230 User smith logged in
ftp>
3. In this example, user smith makes a typing error:
$ ftp test
Connected to test.abc.org
220 test FTP server (Version ...) ready.
Name (test:fred): msith
530 User msith unknown
ftp> user smith
331 Passwd required for smith
Password:
230 User smith logged in
ftp>
4. In this example, user fred issues the ftp command without specifying a
hostname, then connects to host1 using the open subcommand:
$ ftp
ftp> open host1
Connected to host1.abc.org
220 host1 FTP server (Version ...) ready.
Name (host1:fred):
331 Passwd required for fred
Password:
230 User fred logged in
ftp>
FILES
$HOME/.netrc
Contains automatic login information.
SEE ALSO
Commands: csh(1), rcp(1), stty(1), tftp(1), ftpd(8)
Functions: popen(3)
Files: iptos(4), netrc(4)