ftp(1c)ftp(1c)Nameftp - file transfer program
Syntaxftp [-d] [[-g] -i] [-n] [-v] [host]
Description
The command is the user interface to the ARPANET standard File Transfer
Protocol. The program allows you to transfer files to and from a
remote network site.
If you specify the client host on the command line, immediately
attempts to establish a connection to an FTP server on that host; oth‐
erwise, enters its command interpreter and awaits instructions. While
is awaiting commands, it displays the prompt
Options-d Enables debugging.
-g Disables file name expansion.
-i Disables interactive prompting during multiple file trans‐
fers.
-n Disables autologin during an initial connection. If auto-
login is enabled, will check the .netrc file in the user's
home directory for an entry describing an account on the
remote machine. If no entry exists, will use the login name
on the local machine as the user identity on the remote
machine, prompt for a password and, optionally, an account
with which to log in.
-v Displays all responses from the remote server as well as all
data transfer statistics.
Commands
The commands listed in this section are recognized by
Command arguments that have embedded spaces may be quoted with quota‐
tion marks (") to retain the spaces.
? [ command ]
A synonym for help.
! Invokes a shell on the local machine.
$ macro-name [ args ]
Executes the macro macro-name that was defined with the
macdef command. Arguments are passed to the macro unglobbed.
account [ passwd ]
Supplies a supplemental password required by a remote system
for access to resources once a login has been successfully
completed. If you do not supply a argument, you are prompted
for an account password in a non-echoing input mode.
append local-file [ remote-file ]
Appends a local file to a file on the remote machine. If
remote-file is not specified, the local file name is used in
naming the remote file. File transfer uses the current set‐
tings for type, format, mode, and structure.
ascii Sets the file transfer type to network ASCII. This is the
default type.
bell Sounds a bell after each file transfer command is completed.
binary Sets the file transfer type to support binary image transfer.
bye Terminates the FTP session with the remote server and exits
case Toggles the remote computer's file name case mapping during
mget commands. When case is on (the default is off), the
remote computer's file names are written in the local direc‐
tory with all letters in uppercase mapped to lowercase.
cd remote-directory
Changes the working directory on the remote machine to
remote-directory.
cdup Changes the remote machine working directory to the parent of
the current remote machine working directory.
close Terminates the FTP session with the remote server and returns
to the command interpreter.
cr Toggles the 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 can contain single line‐
feeds; when an ascii type transfer is made, these linefeeds
can be distinguished from a record delimiter only when cr is
off.
debug [ debug-value ]
Toggles the debugging mode. If an optional debug-value is
specified, it is used to set the debugging level. When
debugging is on, prints each command sent to the remote
machine, preceded by the string
delete remote-file
Deletes the file remote-file on the remote machine.
dir [ remote-directory ] [ local-file ]
Prints a listing of the contents of the directory remote-
directory, and optionally places the output in local-file.
If you do not specify a directory, uses the current working
directory. If you do not specify a local file, displays the
listing on the terminal.
disconnect
A synonym for close.
form format
Sets the file transfer form to format. The default format is
file.
get remote-file [ local-file ]
Copies the remote-file to the local machine. If you do not
specify a local file name, uses the same name it has on the
remote machine. The current settings for type, form, mode,
and structure are used while transferring the file.
glob Toggles file name expansion for mdelete, mget, and mput. If
globbing (file name substitution) is turned off with glob,
the file name arguments are taken literally and not expanded.
Globbing for mput is done as in 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 remote oper‐
ating system and server, and can be previewed by entering:
mls remote-files. Neither mget nor mput is meant to transfer
entire directory subtrees of files. That can be done by
transferring a archive of the subtree (in binary mode).
hash Toggles the number-sign (#) printing for each data block
transferred. The size of a data block is 1024 bytes.
lcd [ directory ]
Changes the working directory on the local machine. If you
do not specify a local directory directory, uses your home
directory.
ls [ remote-directory ] [ local-file ]
Prints an abbreviated listing of the contents of the remote
directory. If remote-directory is left unspecified, uses
your current working directory. If you do not specify a
local file, the listing is displayed on the terminal.
macdef macro-name
Defines 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 a close command is executed.
The macro processor interprets dollar signs ($) and back‐
slashes (\) as special characters. A dollar sign ($) fol‐
lowed by a number (or numbers) is replaced by the correspond‐
ing argument on the macro invocation command line. A dollar
sign ($) followed by an i signals 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 com‐
mand line. On the second pass it is replaced by the second
argument, and so on. A backslash (\) followed by any charac‐
ter is replaced by that character. Use the backslash (\) to
prevent special treatment of the dollar sign ($).
mdelete remote-files
Deletes the specified files on the remote machine. If glob‐
bing (file name substitution) is enabled, the wildcard speci‐
fication of remote files is first expanded with ls.
mdir remote-files local-file
Obtains a directory listing of multiple files on the remote
machine and places the result in local-file.
mget remote-files
Retrieves the specified files from the remote machine and
places them in the current local directory. If globbing is
enabled, the specification of remote files is first expanding
with
mkdir directory-name
Makes a directory on the remote machine.
mls remote-files local-file
Obtains an abbreviated listing of multiple files on the
remote machine and places the result in local-file.
mode [ mode-name ]
Sets the file transfer mode to mode-name. The default mode
is the stream mode.
mput local-files
Transfers multiple local files from the current local direc‐
tory to the current working directory on the remote machine.
nmap [ inpattern outpattern ]
Sets or disables the file name mapping mechanism. If no
arguments are specified, the file name mapping mechanism is
disabled. If arguments are specified, remote file names are
mapped during mput commands and put commands that are issued
without a specified remote target file name. If arguments
are specified, local file names are mapped during mget com‐
mands and get commands that are issued without a specified
local target file name.
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 and outpat‐
tern.
The inpattern is a template for incoming file names (which
may have already been processed according to the ntrans and
case settings). Specify variable templates by including the
sequences $1, $2, ..., $9 in inpattern. Use a backslash (\)
to prevent this special treatment of the dollar sign ($)
character. All other characters are treated literally, and
are used to determine the nmap inpattern variable values.
For example, given inpattern $1.$2 and the remote file name
$1 has the value and $2 has the value
The outpattern determines the resulting mapped file name.
The sequences $1, $2, ...., $9 are replaced by any value
resulting from the inpattern template. The sequence $0 is
replace by the original file name. 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 yields the output file name for input file names
and for the input file name and for the input file name
.myfile. Spaces can be included in outpattern, as in the
example: Use the backslash (\) to prevent special treatment
of the dollar sign ($), left bracket ([), right bracket (]),
and comma (,).
ntrans [ inchars [ outchars ] ]
Sets or disables the file name character translation mecha‐
nism. If no arguments are specified, the file name character
translation mechanism is disabled. If arguments are speci‐
fied, characters in remote file names are translated during
mput commands and put commands that are issued without a
specified remote target file name. If arguments are speci‐
fied, characters in local file names are translated during
mget commands and get commands that are issued without a
specified local target file name.
This command is useful when connecting to a non-UNIX remote
computer with different file naming conventions or practices.
Characters in a file name matching a character in inchars are
replaced with the corresponding character in outchars. If
the character's position in inchars is longer than the length
of outchars, the character is deleted from the file name.
open host [ port ]
Establishes a connection to the specified host server. If an
optional port number is supplied, attempts to contact an
server at that port. If the auto-login option is on (the
default), automatically attempts to log the user in to the
server (see the description of the .netrc file).
prompt Toggles interactive prompting. Interactive prompting occurs
during multiple file transfers to allow the user to retrieve
or store files selectively. If prompting is turned off (the
default), any mget or mput transfers all files.
proxy ftp-command
Executes an command on a secondary control connection. This
command allows simultaneous connection to two remote servers
for transferring files between the two servers. The first
proxy command should be an open, to establish the secondary
control connection. Type the command to see other commands
executable on the secondary connection. The following com‐
mands 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 con‐
trol connection to the host on the secondary control connec‐
tion.
put, mput, and append transfer files from the host on the
secondary control connection to the host on the primary con‐
trol connection. Third-party file transfers depend upon sup‐
port of the FTP PASV command by the server on the secondary
control connection.
put local-file [ remote-file ]
Copies a local file to the remote machine. If you do not
specify a remote-file, the local file name is used to name
the remote file. File transfer uses the current settings for
type, format, mode, and structure.
pwd Prints the name of the current working directory on the
remote machine.
quit A synonym for bye.
quote arg1 arg2 ...
Sends the arguments that are specified, verbatim, to the
remote server. A single FTP reply code is expected in
return.
recv remote-file [ local-file ]
A synonym for get.
remotehelp [ command-name ]
Requests help from the remote server. If a command name is
specified, it is supplied to the server as well.
rename [ from ] [ to ]
Renames the file from on the remote machine to the file to.
reset Clears the reply queue. This command resynchronizes com‐
mand/reply sequencing with the remote server. If the remote
server violates FTP, resynchronization may be necessary.
rmdir directory-name
Deletes a directory on the remote machine.
runique Toggles storing of files on the local system with unique file
names. If a file already exists with a name equal to the
target local file name for a get or mget command, a .1 is
appended to the name. If the resulting name matches another
existing file, a .2 is appended to the original name. If
this process continues up to .99, an error message is
printed, and the transfer does not take place. The generated
unique file name 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 Toggles the use of PORT commands. By default, attempts to
use a PORT command when establishing a connection for each
data transfer. If the PORT command fails, uses the default
data port. When the use of PORT commands is disabled, no
attempt is made to use PORT commands for each data transfer.
This is useful for certain FTP implementations that do ignore
PORT commands but, incorrectly, indicate that the commands
have been accepted.
status Shows the current status of
struct [ struct-name ]
Sets the file transfer structure to struct-name. By default
the file structure is used.
sunique Toggles storing of files on a remote machine under unique
file names. The remote server must support the FTP STOU com‐
mand for successful completion of this command. The remote
server reports the unique name. The default value is off.
tenex Sets the file transfer type to that needed to talk to TENEX
machines.
trace Toggles packet tracing.
type [ type-name ]
Sets the file transfer type to type-name. If no type is
specified, the current type is printed. The default type is
network ASCII.
user user-name [ password ] [ account ]
Identifies you to the remote server. If the password is not
specified and the server requires it, disables the local echo
and then prompts you for it. If an account field is not
specified, and the server requires it, you are prompted for
it also. Unless is invoked with auto-login disabled, this
process is done automatically on initial connection to the
server.
verbose Toggles the verbose mode. In verbose mode, all responses
from the server are displayed. In addition, if verbose is
on, statistics regarding the efficiency of a file transfer
are reported when the transfer is complete. By default, ver‐
bose is on.
Aborting a File Transfer
To abort a file transfer, use the terminal interrupt key (usually
CTRL/C). Sending transfers are halted immediately. Receiving trans‐
fers are halted by sending an FTP 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 process‐
ing. If the remote server does not support the ABOR command, an prompt
appears when the remote server has completed sending the requested
file.
The terminal interrupt key sequence is ignored when has completed any
local processing and is awaiting a reply from the remote server. A
long delay in this mode may result from ABOR processing, or from unex‐
pected behavior by the remote server, including violations of the FTP.
If the delay results from unexpected remote server behavior, the local
program must be killed by hand.
File-Naming Conventions
Files specified as arguments to commands are processed according to the
following rules:
1) Standard input is used for reading and standard output is used for
writing when the file name is specified as a minus sign (-).
2) If the first character of the file name is a vertical bar (|), the
remainder of the argument is interpreted as a shell command. The
command then forks a shell, using with the argument supplied, and
reads or writes from standard output or standard input respec‐
tively. If the shell command includes spaces, the argument must be
quoted, as in "|ls -lt". A particularly useful example of this
mechanism is: "dir |more".
3) If globbing is enabled, local file names are expanded according to
the rules used in the (compare to the command). If the command
expects a single local file, such as put, only the first file name
generated by the globbing operation is used.
4) For mget commands and get commands with unspecified local file
names, the local file name is the remote file name and can be
altered by a case, ntrans, or nmap setting. The resulting file
name may then be altered if runique is on.
5) For mput commands and put commands with unspecified remote file
names, the remote file name is the local file name and can be
altered by a ntrans or nmap setting. The resulting file name can
then be altered by the remote server if sunique is on.
File Transfer Parameters
Many parameters can affect a file transfer. The type can be ascii,
image (binary), ebcdic, or local byte size. The command supports the
ascii
and image types of file transfer and local byte size 8 for tenex mode
transfers.
The command supports only the default values for the remaining file
transfer parameters: mode, form, and struct.
The .netrc File
The .netrc file contains login and initialization information used by
the auto-login process. It resides in your home directory. See for a
description and example of a .netrc file. The following tokens in the
.netrc file are recognized; they can be separated by spaces, tabs, or
new-lines:
machine name
Identifies a remote machine name. The auto-login process
searches the .netrc file for a machine token that matches the
remote machine specified on the 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
Identifies a user on the remote machine. If this token is
present, the auto-login process initiates a login using the
specified name.
password string
Supplies a password. If this token is present, the auto-
login process supplies the specified string if the remote
server requires a password as part of the login process.
Note that if this token is present in the .netrc file, and if
the .netrc is readable by anyone other than the user, aborts
the auto-login process.
account string
Supplies an additional account password. When this token is
present, the auto-login process supplies the the remote
server with an additional account password if the remote
server requires it. If it does not, the auto-login process
initiates an ACCT command.
macdef name
Defines a macro. This token functions like the macdef com‐
mand. A macro is defined with a 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, it is automatically executed as
the last step in the auto-login process.
Restrictions
Correct execution of many commands depends on proper behavior by the
remote server.
The server prevents the unauthorized users listed in the file from
transferring files.
An error in the treatment of carriage returns in the 4.2BSD UNIX asci‐
itype 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.
Files
Contains the list of unauthorized users
See Alsonetrc(5), services(5), ftpd(8c), inetd(8c), syslog(8)ftp(1c)
