info inetutils

File: inetutils.info, Node: Ftp commands, Next: Ftp environment, Prev: Ftp options, Up: ftp invocation

11.2 Commands interpreted by 'ftp'
==================================

When 'ftp' is awaiting commands from the user, a prompt is displayed.
The default string is 'ftp>', but it can been changed with a command
line option, perhaps to enhance uniqueness while recording a session.

Be aware that correct execution of many commands depends upon a
proper behavior of the remote server. The following commands are
recognized by 'ftp' itself. Command names can be abbreviated to the
shortest unique string with identical beginning.

'! [COMMAND [ARGS]]'
Invoke an interactive shell on the local machine. If there are
arguments, the first is taken 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 no argument is included, the user will be prompted for an
account password in non-echoing input mode.

'append LOCAL-FILE [REMOTE-FILE]'
Append a local file to a file on the remote machine. If
REMOTE-FILE is left unspecified, the local file name is used in
naming the remote file after being altered by any 'ntrans' or
'nmap' setting. File transfer uses the current settings for type,
format, mode, and structure.

'ascii'
Set the file transfer type to network ASCII. This is the default
type, except when two unices are communicating.

'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. This
transfer type is selected during initial handshake, should the
client on a Unix system recognize that the server is also running
on a Unix system.

'bye'
'quit'
Terminate the FTP session with the remote server and exit 'ftp'.
An end of file will also terminate the session and exit.

'case'
Toggle the remote computer's use of letter case mapping during
'mget' commands. When 'case' is 'on', a file name at the remote
site whose every letter appear in upper case, will be renamed in
such a way that all letters are changed to lower case for a local
copy of the same file. The default setting is 'off',

'cd REMOTE-DIRECTORY'
Change the working directory on the remote machine to
REMOTE-DIRECTORY.

'cdup'
Change the remote machine's working directory to the parent of the
current working directory.

'chmod MODE FILE-NAME'
Change the access permission of the file FILE-NAME on the remote
system to MODE.

'close'
'disconnect'
Terminate the FTP session with the present 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, these linefeeds may be distinguished 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 an optional DEBUG-VALUE is specified it
is used 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 contents in the directory REMOTE-DIRECTORY,
and, optionally, place the output in LOCAL-FILE. If interactive
prompting is set, 'ftp' will prompt the user to verify that the
last argument is the intended local file to receive output. If no
directory is specified, the current working directory on the remote
machine is used. If no local file is specified, or if LOCAL-FILE
is a dash '-', then output is displayed on the terminal.

'epsv4'
Toggle the use of EPSV/EPRT for IPv4 addressing. Default is off.

'form FORMAT'
Set the file transfer form to FORMAT. The only supported format is
'non-print'.

'get REMOTE-FILE [LOCAL-FILE]'
'recv REMOTE-FILE [LOCAL-FILE]'
Retrieve the REMOTE-FILE and store it on the local machine. If a
local file name is not specified, the local copy is given the same
name as is stated for the remote original, subject to alteration by
the current 'case', 'ntrans', and 'nmap' settings. The current
settings for 'type', 'form', 'mode', and 'structure' are effective
during file transfer.

'glob'
Toggle file name expansion for 'mdelete', 'mget', and 'mput'. If
globbing is turned off with 'glob', the file name arguments are
taken literally and are not expanded. Globbing for 'mput' is done
as in 'csh' syntax. 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 operating system and on the FTP
server, and can be previewed by issuing 'mls remote-files -'.

Note: 'mget' and 'mput' are not meant to transfer entire directory
subtrees of files. That can be achieved by transferring an already
created 'tar' or 'cpio' archive of the subtree, then making certain
that 'ftp' uses binary mode.

'hash [SIZE]'
In the absence of an argument, toggle the state of hash-sign ('#')
printing after each transferred data block. The optional argument
selects the size of data blocks, and unconditionally activates
printing. The default size is 1024 bytes. For convenience, the
size can be written with postfix multipliers 'k', 'K', 'm', 'M',
and 'g', 'G', to specify kilobytes, Megabytes, and Gigabytes,
respectively.

'help [COMMAND]'
'? [COMMAND]'
Print an informative message about the meaning of command. If no
argument is given, 'ftp' prints a list of the known commands.

'idle [SECONDS]'
Set the inactivity timer on the remote server to SECONDS seconds.
If seconds is omitted, the current inactivity timer is printed.

'ipv4'
Select IPv4 as the only addressing scheme.

'ipv6'
Select IPv6 as the only addressing scheme.

'ipany'
Allow IPv4 as well as IPv6 addressing.

'lcd [DIRECTORY]'
Change the working directory on the local machine. If no directory
is specified, the user's home directory is used.

'lpwd'
Print the name of the current working directory on the local
machine.

'ls [REMOTE-DIRECTORY] [LOCAL-FILE]'
Print a listing of the contents of a directory on the remote
machine. The listing includes any system-dependent information
that the server chooses to include; for example, most UNIX systems
will produce output like the command 'ls -l' does. Use 'nlist' for
a simple file listing.

If REMOTE-DIRECTORY is left unspecified, the current working
directory is used. With interactive prompting set, 'ftp' will
prompt the user to verify that the last argument is indeed the
intended local file for storing output. Should no local file be
specified, or if LOCAL-FILE is a dash '-', then output is sent to
the terminal.

'macdef MACRO-NAME'
Define a macro called MACRO-NAME, with subsequent lines as the
macro definition. A null line (consecutive newline characters in a
file, or carriage returns at a terminal) terminates macro input
mode. There is a limit of 16 macros and a total of 4096 characters
shared by all defined macros. Only the first eight characters in
MACRO-NAME are significant when determining which macro to execute.
Macros remain defined until a close command is executed.

The macro processor interprets '$' and '\' as special characters.
A '$' followed by a number (one or more digits) is replaced by the
corresponding argument on the macro's invocation command line. A
'$' followed by the letter 'i' tells the macro processor that the
macro is to perform a loop. On the first pass, '$i' is replaced by
the first argument on the macro's invocation command line, while on
the second pass it is replaced by the second argument, and so
forth. Iteration proceeds until all arguments have been consumed.

A backslash '\' followed by any character is replaced by that
character. Use the backslash '\' to prevent special treatment of
the dollar sign '$', as was just explained.

A macro can execute a macro, allowing recursion. In order to avoid
exhausting the stack and thus crashing 'ftp', the nesting depth of
macro execution is limited to a compile time constant.

'mdelete [REMOTE-FILES]'
Delete all REMOTE-FILES on the remote machine.

'mdir REMOTE-FILES LOCAL-FILE'
Like 'dir', except multiple remote files may be specified. If
interactive prompting is on, 'ftp' will prompt the user to verify
that the last argument is indeed the intended local file for
storing any output from 'mdir'.

'mget REMOTE-FILES'
Expand the REMOTE-FILES on the remote machine and execute a 'get'
for each file name thus produced. Resulting file names will then
be processed according to 'case', 'ntrans', and 'nmap' settings.
Files are transferred to the local working directory, which can be
changed with 'lcd directory'; new local directories can be created
with '! mkdir directory'.

'mkdir DIRECTORY-NAME'
Make a directory on the remote machine.

'mls REMOTE-FILES LOCAL-FILE'
Like 'nlist', except multiple remote files may be specified, and
the LOCAL-FILE must be specified. If interactive prompting is on,
'ftp' will prompt the user to verify that the last argument is the
intended local file for storing output. A dash '-' is accepted as
last argument without check!

'mode [MODE-NAME]'
Set the file transfer mode to MODE-NAME. The default mode is
'stream', and it is also the only implemented mode.

'modtime FILE-NAME'
Show the last modification time of the file on the remote machine.

'mput LOCAL-FILES'
Consider the arguments to be local names and expand any wild card.
Execute a 'put' for each file in the resulting list. The remote
file names are then computed by use of 'ntrans' and 'nmap'
settings.

'newer FILE-NAME'
Get the file only if the modification time of the remote file is
more recent than the file on the current system. If the file does
not exist on the current system, the remote file is considered
newer. In other respects, this command is identical to 'get'.

'nlist [REMOTE-DIRECTORY] [LOCAL-FILE]'
Print a list of the files in a directory on the remote machine. If
REMOTE-DIRECTORY is left unspecified, the current working directory
is used. If interactive prompting is on, 'ftp' will prompt the
user to verify that the last argument is the intended local file
for storing output. If no local file is specified, or if
LOCAL-FILE is '-', the output is sent to the terminal.

'nmap [INPATTERN OUTPATTERN]'
Set or unset the file name mapping mechanism. If no arguments are
specified, the file name mapping mechanism is unset. Name mapping
is applied during 'mput' and 'put' commands issued without a
specified remote target filename. It as also applied to local file
names during 'mget' and 'get' commands issued without 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 OUTPATTERN.
The template INPATTERN is used on incoming filenames (which may
have already been processed according to the 'ntrans' and 'case'
settings). Variable templating is accomplished by including the
sequences '$1', '$2', ..., '$9' in INPATTERN. Use '\' to prevent
this special treatment of the character '$'. All other characters
are treated literally, and must be matched in a file name for
INPATTERN to bind substrings to variables.

For example, take a pattern '$1.$2' and a file name 'mydata.data'.
Then '$1' would have the value 'mydata', and '$2' would be 'data'.

OUTPATTERN determines the final file name. The sequences '$1' to
'$9' are replaced by any values bound to them by INPATTERN. A
special sequence '$0' always contains the original filename. In
addition, a bracketted sequence '[SEQ1,SEQ2]' expands to SEQ1 if
SEQ1 contains a non-empty string, and expands to SEQ2 otherwise.
For example, the command

nmap $1.$2.$3 [$1,$2].[$2,file]

would yield the output file name 'myfile.data' for input names
'myfile.data' and 'myfile.data.old', but produces 'myfile.file'
from the input 'myfile', and 'myfile.myfile' from '.myfile'.

Spaces may be included in OUTPATTERN, but are easily removed:

nmap $1 |sed "s/ *$//" > $1

Use a backslash '\' to escape the characters '$', '[', ']', and
','.

'ntrans [INCHARS [OUTCHARS]]'
Set or unset the filename character translation mechanism. If no
arguments are specified, the filename character translation
mechanism is unset. If arguments are specified, characters in
remote filenames are translated during 'mput' commands and 'put'
commands issued without a specified remote target filename. If
arguments are specified, characters in local filenames are
translated during 'mget' commands and 'get' commands issued without
a specified local target filename. This command is useful when
connecting to a non-UNIX remote computer with different file naming
conventions or practices.

Characters in a filename 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]'
'open USER@HOST [PORT]'
Establish a connection to the specified FTP server at HOST. An
optional port number may be supplied, in which case, 'ftp' will
attempt to contact the server at that specific TCP port. If the
'autologin' option is on (is so by default), 'ftp' will also
attempt to automatically log the user in to the FTP server.

The second form of invocation sets the remote user name to USER,
which otherwise is taken as identical to the user identity owning
the local session.

'passive'
Toggle passive mode. If passive mode is turned on (default is
off), the 'ftp' client will send a 'PASV' command for all data
connections instead of the usual 'PORT' command. The 'PASV'
command requests that the remote server open a port for the data
connection and return the address of that port. The remote server
listens on that port and the client connects to it. When using the
more traditional 'PORT' command, the client listens on a port and
sends that address to the remote server, who connects back to it.
Passive mode is useful when using 'ftp' through a gateway router or
host that controls the directionality of traffic. (Note that
though 'ftp' servers are required to support the 'PASV' command by
RFC 1123, some do not.) If 'epsv4' has been set to on, the client
will attempt 'EPSV' before 'PASV' for IPv4. As a last resort
'LPSV' is attempted. With IPv6 only 'EPSV' and 'LPSV' are
possible.

'prompt'
Toggle interactive prompting. Interactive prompting occurs during
multiple file transfers to allow the user to selectively retrieve
or store files. If prompting is turned off (default is on), any
'mget' or 'mput' will transfer all files, and any 'mdelete' will
delete all files.

'proxy FTP-COMMAND'
Execute an 'ftp' command on a secondary control connection. This
command allows simultaneous connection to two remote FTP servers
for transferring files between the two servers. The first proxy
command should be 'open', to establish the secondary control
connection. Enter the command 'proxy ?' to see other commands
usable for the secondary connection. The following commands behave
differently when prefaced by 'proxy': 'open' will not define new
macros during the auto-login process, 'close' will 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.

Note that the protocol command 'PASV' must be understood by the
server on the secondary control connection for this kind of file
transfer to succeed.

'put LOCAL-FILE [REMOTE-FILE]'
'send LOCAL-FILE [REMOTE-FILE]'
Store a local file on the remote machine. If REMOTE-FILE is left
unspecified, the local file name is used after processing according
to any 'ntrans' or 'nmap' settings in naming the remote file. File
transfer uses the current settings for type, format, mode, and
structure.

'pwd'
Print the name of the current working directory on the remote
machine.

'quote ARG...'
The arguments specified are sent, verbatim, to the remote FTP
server.

'reget REMOTE-FILE [LOCAL-FILE]'
'reget' acts like 'get', except that if LOCAL-FILE exists and is
smaller than REMOTE-FILE, then 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 command is
useful when transferring very large files over networks that are
prone to dropping connections.

'rhelp [COMMAND-NAME]'
Request help from the remote FTP server. If COMMAND-NAME is
specified it is passed to the server as well.

'rstatus [FILE-NAME]'
With no arguments, show status of remote machine. If filename is
specified, show status of FILE-NAME on remote machine.

'rename [FROM] [TO]'
Rename the file FROM on the remote machine as TO. Name mapping
takes effect without TO.

'reset'
Clear reply queue. This command re-synchronizes command/reply
sequencing with the remote FTP server. Resynchronization may be
necessary following a violation of the FTP protocol by the remote
server.

'restart MARKER'
Restart the immediately following 'get' or 'put' at the indicated
marker. On UNIX systems, 'marker' is usually a byte offset into
the file.

'rmdir DIRECTORY-NAME'
Delete a directory on the remote machine.

'runique'
Toggle the storing of files on the local system with unique
filenames. If a file already exists with a name equal to the
inteded local file name for a 'get' or 'mget' command, then a
string '.1' is appended to the name. If the resulting name matches
another existing file, '.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
filename will be reported. Note that 'runique' will not affect
local files generated from a shell command. The default value is
off.

'sendport'
Toggle the use of 'PORT' commands. By default, 'ftp' will attempt
to use a 'PORT' command when establishing a connection for each
data transfer. The use of 'PORT' commands can prevent delays when
performing multiple file transfers. If the 'PORT' command fails,
'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 do ignore 'PORT' commands but, incorrectly,
indicate they've been accepted.

'site ARG...'
The arguments specified are sent, verbatim, to the remote FTP
server as a 'SITE' command.

'size FILE-NAME'
Return size of FILE-NAME on remote machine.

'status'
Show the current status of 'ftp'.

'struct [STRUCT-NAME]'
Set the file transfer structure to STRUCT-NAME. By default 'file'
structure is used, which also is the only supported value.

'sunique'
Toggle storing of files on remote machine under unique file names.
Remote FTP server must support FTP protocol 'STOU' command for
successful completion. The remote server will report unique name.
Default value is off.

'system'
Show the type of operating system running on the remote machine.

'tenex'
Set the file transfer type to that needed to talk to TENEX
machines.

'trace'
Toggle packet tracing (feature is not implemented).

'type [TYPE-NAME]'
Set the file transfer type to TYPE-NAME. If no type is specified,
the current type is printed. The recognized type names are
'ascii', 'binary', 'ebcdic', 'image', and 'tenex'. The default
type is network ASCII.

'umask [NEWMASK]'
Set the default umask on the remote server to NEWMASK. If NEWMASK
is omitted, the current umask is printed.

'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 an account field is not
specified, and the FTP server requires it, the user will be
prompted for it. If an account field is specified, an account
command will be relayed to the remote server after the login
sequence is completed if the remote server did not require it for
logging in. Unless 'ftp' is invoked with 'auto-login' disabled,
this process is done automatically on initial connection to the FTP
server.

'verbose'
Toggle verbose mode. In verbose mode, all responses from the FTP
server are displayed to the user. In addition, if verbose is on,
when a file transfer completes, statistics regarding the efficiency
of the transfer are reported. By default, verbose is on.

Command arguments which have embedded spaces may be inclosed within
citation characters '"'.