ftp.1

UNIX FTP client

.\" Copyright (c) 1985, 1989, 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	from: @(#)ftp.1	6.18 (Berkeley) 7/30/91
.\"	$Id: ftp.1,v 1.2 1997/06/08 20:01:35 dholland Exp $
.\"
.Dd July 30, 1991
.Dt FTP 1
.Os BSD 4.2
.Sh NAME
.Nm ftp
.Nd
.Tn ARPANET
file transfer program
.Sh SYNOPSIS
.Nm ftp
.Op Fl v
.Op Fl d
.Op Fl i
.Op Fl n
.Op Fl g
.Op Ar host
.Sh DESCRIPTION
.Nm Ftp
is the user interface to the
.Tn ARPANET
standard File Transfer Protocol.
The program allows a user to transfer files to and from a
remote network site.
.Pp
Options may be specified at the command line, or to the
command interpreter.
.Bl -tag -width flag
.It Fl v
Verbose option forces
.Nm ftp
to show all responses from the remote server, as well
as report on data transfer statistics.
.It Fl n
Restrains
.Nm ftp
from attempting \*(Lqauto-login\*(Rq upon initial connection.
If auto-login is enabled,
.Nm ftp
will check the
.Pa .netrc
(see below) file in the user's home directory for an entry describing
an account on the remote machine.
If no entry exists,
.Nm ftp
will prompt for the remote machine login name (default is the user
identity on the local machine), and, if necessary, prompt for a password
and an account with which to login.
.It Fl i
Turns off interactive prompting during
multiple file transfers.
.It Fl d
Enables debugging.
.It Fl g
Disables file name globbing.
.El
.Pp
The client host with which
.Nm ftp
is to communicate may be specified on the command line.
If this is done,
.Nm ftp
will immediately attempt to establish a connection to an
.Tn FTP
server on that host; otherwise,
.Nm ftp
will enter its command interpreter and await instructions
from the user.
When
.Nm ftp
is awaiting commands from the user the prompt
.Ql ftp>
is provided to the user.
The following commands are recognized
by
.Nm ftp  :
.Bl -tag -width Fl
.It Ic \&! Op Ar command Op Ar 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.
.It Ic \&$ Ar macro-name Op Ar args
Execute the macro
.Ar macro-name
that was defined with the
.Ic macdef
command.
Arguments are passed to the macro unglobbed.
.It Ic account Op Ar 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 a non-echoing input mode.
.It Ic append Ar local-file Op Ar remote-file
Append a local file to a file on the remote machine.
If
.Ar remote-file
is left unspecified, the local file name is used in naming the
remote file after being altered by any
.Ic ntrans
or
.Ic nmap
setting.
File transfer uses the current settings for
.Ic type  ,
.Ic format ,
.Ic mode  ,
and
.Ic structure .
.It Ic ascii
Set the file transfer
.Ic type
to network
.Tn ASCII .
This is the default type.
.It Ic bell
Arrange that a bell be sounded after each file transfer
command is completed.
.It Ic binary
Set the file transfer
.Ic type
to support binary image transfer.
.It Ic bye
Terminate the
.Tn FTP
session with the remote server
and exit
.Nm ftp  .
An end of file will also terminate the session and exit.
.It Ic case
Toggle remote computer file name case mapping during
.Ic mget
commands.
When
.Ic case
is on (default is off), remote computer file names with all letters in
upper case are written in the local directory with the letters mapped
to lower case.
.It Ic \&cd Ar remote-directory
Change the working directory on the remote machine
to
.Ar remote-directory  .
.It Ic cdup
Change the remote machine working directory to the parent of the
current remote machine working directory.
.It Ic chmod Ar mode file-name
Change the permission modes of the file
.Ar file-name
on the remote
sytem to
.Ar mode  .
.It Ic close
Terminate the
.Tn FTP
session with the remote server, and
return to the command interpreter.
Any defined macros are erased.
.It Ic \&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
.Ic \&cr
is on (the default), carriage returns are stripped from this
sequence to conform with the
.Ux
single linefeed record
delimiter.
Records on
.Pf non\- Ns Ux
remote systems may contain single linefeeds;
when an ascii type transfer is made, these linefeeds may be
distinguished from a record delimiter only when
.Ic \&cr
is off.
.It Ic delete Ar remote-file
Delete the file
.Ar remote-file
on the remote machine.
.It Ic debug Op Ar debug-value
Toggle debugging mode.
If an optional
.Ar debug-value
is specified it is used to set the debugging level.
When debugging is on,
.Nm ftp
prints each command sent to the remote machine, preceded
by the string
.Ql \-\->
.It Xo
.Ic dir
.Op Ar remote-directory
.Op Ar local-file
.Xc
Print a listing of the directory contents in the
directory,
.Ar remote-directory  ,
and, optionally, placing the output in
.Ar local-file  .
If interactive prompting is on,
.Nm ftp
will prompt the user to verify that the last argument is indeed the
target local file for receiving
.Ic dir
output.
If no directory is specified, the current working
directory on the remote machine is used.
If no local
file is specified, or
.Ar local-file
is
.Fl  ,
output comes to the terminal.
.It Ic disconnect
A synonym for
.Ar close  .
.It Ic form Ar format
Set the file transfer
.Ic form
to
.Ar format  .
The default format is \*(Lqfile\*(Rq.
.It Ic get Ar remote-file Op Ar local-file
Retrieve the
.Ar remote-file
and store it on the local machine.
If the local
file name is not specified, it is given the same
name it has on the remote machine, subject to
alteration by the current
.Ic case  ,
.Ic ntrans ,
and
.Ic nmap
settings.
The current settings for
.Ic type  ,
.Ic form ,
.Ic mode  ,
and
.Ic structure
are used while transferring the file.
.It Ic glob
Toggle filename expansion for
.Ic mdelete  ,
.Ic mget
and
.Ic mput  .
If globbing is turned off with
.Ic glob  ,
the file name arguments
are taken literally and not expanded.
Globbing for
.Ic mput
is done as in
.Xr csh 1 .
For
.Ic mdelete
and
.Ic 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 foreign operating system and ftp server,
and can be previewed by doing
.Ql mls remote-files \-
Note:
.Ic mget
and
.Ic mput
are not meant to transfer
entire directory subtrees of files.
That can be done by
transferring a
.Xr tar 1
archive of the subtree (in binary mode).
.It Ic hash
Toggle hash-sign (``#'') printing for each data block
transferred.
The size of a data block is 1024 bytes.
.It Ic help Op Ar command
Print an informative message about the meaning of
.Ar command  .
If no argument is given,
.Nm ftp
prints a list of the known commands.
.It Ic idle Op Ar seconds
Set the inactivity timer on the remote server to
.Ar seconds
seconds.
If
.Ar seconds
is ommitted, the current inactivity timer is printed.
.It Ic lcd Op Ar directory
Change the working directory on the local machine.
If
no
.Ar directory
is specified, the user's home directory is used.
.It Xo
.Ic \&ls
.Op Ar remote-directory
.Op Ar local-file
.Xc
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
.Ux
systems will produce
output from the command
.Ql ls \-l .
(See also
.Ic nlist . )
If
.Ar remote-directory
is left unspecified, the current working directory is used.
If interactive prompting is on,
.Nm ftp
will prompt the user to verify that the last argument is indeed the
target local file for receiving
.Ic \&ls
output.
If no local file is specified, or if
.Ar local-file
is
.Sq Fl ,
the output is sent to the terminal.
.It Ic macdef Ar macro-name
Define a macro.
Subsequent lines are stored as the macro
.Ar 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
.Ic close
command is executed.
The macro processor interprets `$' and `\e' 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 `\e' followed by any character is replaced by that character.
Use the `\e' to prevent special treatment of the `$'.
.It Ic mdelete Op Ar remote-files
Delete the
.Ar remote-files
on the remote machine.
.It Ic mdir Ar remote-files local-file
Like
.Ic dir  ,
except multiple remote files may be specified.
If interactive prompting is on,
.Nm ftp
will prompt the user to verify that the last argument is indeed the
target local file for receiving
.Ic mdir
output.
.It Ic mget Ar remote-files
Expand the
.Ar remote-files
on the remote machine
and do a
.Ic get
for each file name thus produced.
See
.Ic glob
for details on the filename expansion.
Resulting file names will then be processed according to
.Ic case  ,
.Ic ntrans ,
and
.Ic nmap
settings.
Files are transferred into the local working directory,
which can be changed with
.Ql lcd directory ;
new local directories can be created with
.Ql "\&! mkdir directory" .
.It Ic mkdir Ar directory-name
Make a directory on the remote machine.
.It Ic mls Ar remote-files local-file
Like
.Ic nlist  ,
except multiple remote files may be specified,
and the
.Ar local-file
must be specified.
If interactive prompting is on,
.Nm ftp
will prompt the user to verify that the last argument is indeed the
target local file for receiving
.Ic mls
output.
.It Ic mode Op Ar mode-name
Set the file transfer
.Ic mode
to
.Ar mode-name  .
The default mode is \*(Lqstream\*(Rq mode.
.It Ic modtime Ar file-name
Show the last modification time of the file on the remote machine.
.It Ic mput Ar local-files
Expand wild cards in the list of local files given as arguments
and do a
.Ic put
for each file in the resulting list.
See
.Ic glob
for details of filename expansion.
Resulting file names will then be processed according to
.Ic ntrans
and
.Ic nmap
settings.
.It Ic newer Ar file-name Op Ar local-file
Get the file only if the modification time of the remote file is more
recent that the file on the current system.
If the file does not
exist on the current system, the remote file is considered
.Ic newer  .
Otherwise, this command is identical to
.Ar get  .
.It Xo
.Ic nlist
.Op Ar remote-directory
.Op Ar local-file
.Xc
Print a  list of the files in a
directory on the remote machine.
If
.Ar remote-directory
is left unspecified, the current working directory is used.
If interactive prompting is on,
.Nm ftp
will prompt the user to verify that the last argument is indeed the
target local file for receiving
.Ic nlist
output.
If no local file is specified, or if
.Ar local-file
is
.Fl  ,
the output is sent to the terminal.
.It Ic nmap Op Ar inpattern outpattern
Set or unset the filename mapping mechanism.
If no arguments are specified, the filename mapping mechanism is unset.
If arguments are specified, remote filenames are mapped during
.Ic mput
commands and
.Ic put
commands issued without a specified remote target filename.
If arguments are specified, local filenames are mapped during
.Ic mget
commands and
.Ic get
commands issued without a specified local target filename.
This command is useful when connecting to a
.No non\- Ns Ux
remote computer
with different file naming conventions or practices.
The mapping follows the pattern set by
.Ar inpattern
and
.Ar outpattern  .
.Op Ar Inpattern
is a template for incoming filenames (which may have already been
processed according to the
.Ic ntrans
and
.Ic case
settings).
Variable templating is accomplished by including the
sequences `$1', `$2', ..., `$9' in
.Ar inpattern  .
Use `\\' to prevent this special treatment of the `$' character.
All other characters are treated literally, and are used to determine the
.Ic nmap
.Op Ar inpattern
variable values.
For example, given
.Ar inpattern
$1.$2 and the remote file name "mydata.data", $1 would have the value
"mydata", and $2 would have the value "data".
The
.Ar outpattern
determines the resulting mapped filename.
The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
from the
.Ar inpattern
template.
The sequence `$0' is replace by the original filename.
Additionally, the sequence
.Ql Op Ar seq1 , Ar seq2
is replaced by
.Op Ar seq1
if
.Ar seq1
is not a null string; otherwise it is replaced by
.Ar seq2 .
For example, the command
.Pp
.Bd -literal -offset indent -compact
nmap $1.$2.$3 [$1,$2].[$2,file]
.Ed
.Pp
would yield
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".
Spaces may be included in
.Ar outpattern  ,
as in the example: `nmap $1 sed "s/  *$//" > $1' .
Use the `\e' character to prevent special treatment
of the `$','[','[', and `,' characters.
.It Ic ntrans Op Ar inchars Op Ar 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
.Ic mput
commands and
.Ic put
commands issued without a specified remote target filename.
If arguments are specified, characters in
local filenames are translated during
.Ic mget