hpux 10.20 - ftp (1)
NAME
ftp - file transfer program
SYNOPSIS
ftp [-g] [-i] [-n] [-v] [-B size] [server-host]
DESCRIPTION
ftp is a user interface to the File Transfer Protocol. ftp copies
files over a network connection between the local ``client'' host and
a remote ``server'' host. ftp runs on the client host.
Options
The ftp command supports the following options:
-g Disable file name ``globbing''; see the glob command, below.
By default, when this option is not specified, globbing is
enabled.
-i Disable interactive prompting by multiple-file commands; see
the prompt command, below. By default, when this option is
not specified, prompting is enabled.
-n Disable ``auto-login''; see the open command, below. By
default, when this option is not specified, auto-login is
enabled.
-v Enable verbose output; see the verbose command, below. If
this option is not specified, ftp displays verbose output
only if the standard input is associated with a terminal.
-B Set the buffer size of the data socket to size blocks of
1024 bytes. The valid range for size is an integer from 1 to
64 (default is 56).
Note: A large buffer size will improve the performance of
ftp on fast links (e.g., FDDI), but may cause long
connection times on slow links (e.g., X.25).
The name of the server host that ftp communicates with can be
specified on the command line. If the server host is specified, ftp
immediately opens a connection to the server host; see the open
command, below. Otherwise, ftp waits for commands from the user.
File Transfer Protocol specifies file transfer parameters for type,
mode, form, and struct. ftp supports the ASCII, binary, and tenex
File Transfer Protocol types. ASCII is the default FTP type. (It
should be noted though that, whenever ftp establishes a connection
between two similar systems, it switches automatically to the more
efficient binary type.) ftp supports only the default values for the
file transfer parameters mode which defaults to stream, form which
defaults to non-print, and struct which defaults to file.
COMMANDS
ftp supports the following commands. Command arguments with embedded
spaces must be enclosed in quotes (for example, "argument with
embedded spaces").
![command [args]]
Invoke a shell on the local host. The SHELL environment variable
specifies which shell program to invoke. ftp invokes /usr/bin/sh
if SHELL is undefined. If command is specified, the shell
executes it and returns to ftp. Otherwise, an interactive shell
is invoked. When the shell terminates, it returns to ftp.
$ 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 is prompted for an account
password in a non-echoing input mode.
append local-file [remote-file]
Copy local-file to the end of remote-file. 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.
ascii
Set the file transfer type to network ASCII. This is the default
type.
bell Sound a bell after each file transfer completes.
binary
Set the file transfer type to binary.
bye Close the connection to the server host if a connection was open,
and exit. Typing an end-of-file (EOF) character also terminates
and exits the session.
case Toggle remote computer file name case mapping during mget
commands. When case is on (the default is off), remote computer
file names with all letters in uppercase are written in the local
directory with the letters mapped to lowercase.
cd remote-directory
Set the working directory on the server host to remote-directory.
cdup Set the working directory on the server host to the parent of the
current remote working directory.
chmod mode file-name
Change the permission modes of the file file-name on the remote
system to mode.
close
Terminate the connection to the server host. The close command
does not exit ftp. Any defined macros are erased.
cr Toggle carriage return stripping during ascii type file
retrieval. Records are denoted by a carriage-return/line-feed
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 line-feed record delimiter. Records
on non-UNIX remote systems may contain single line-feeds; when an
ascii type transfer is made, these line-feeds can be
distinguished from a record delimiter only when cr is off.
delete remote-file
Delete remote-file. The remote-file can be an empty directory.
No globbing is done.
dir [remote-directory] [local-file]
Write a remote-directory listing to standard output or optionally
to local-file. If neither remote-directory nor local-file is
specified, list the remote working directory to standard output.
If interactive prompting is on, ftp prompts the user to verify
that the last argument is indeed the target file for dir output.
Globbing characters are always expanded.
disconnect
A synonym for close.
form format
Set the file transfer form to format. The only supported format
is non-print
get remote-file [local-file]
Copy remote-file to local-file. If local-file is unspecified,
ftp uses the specified remote-file name as the local-file name,
subject to alteration by the current case, ntrans, and nmap
settings.
glob Toggle file name globbing. When file name globbing is enabled,
ftp expands csh(1) metacharacters in file and directory names.
These characters are *, ?, [, ], ~, {, and }. The server host
expands remote file and directory names. Globbing metacharacters
are always expanded for the ls and dir commands. If globbing is
enabled, metacharacters are also expanded for the multiple-file
commands mdelete, mdir, mget, mls, and mput.
hash Toggle printing of a hash-sign (#) for each 1024 bytes
transferred.
help [command]
Print an informative message about the ftp command called ftp-
command. If ftp-command is unspecified, print a list of all ftp
commands.
idle [seconds]
Set the inactivity timer on the remote server to seconds seconds.
If seconds is omitted, ftp prints the current inactivity timer.
lcd [local-directory]
Set the local working directory to local-directory. If local-
directory is unspecified, set the local working directory to the
user's local home directory.
ls [remote-directory] [local-file]
Write a listing of remote-directory to local-file. The listing
includes any system-dependent information that the server chooses
to include; for example, most UNIX systems produce output from
the command ls -l (see also nlist). If neither remote-directory
nor local-file is specified, list the remote working directory.
If globbing is enabled, globbing metacharacters are expanded.
macdef macro-name
Define a macro. Subsequent lines are stored as the macro macro-
name; an empty input line 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 $ 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 to 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 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 remote-files. If globbing is enabled, globbing
metacharacters are expanded.
mdir remote-files local-file
Write a listing of remote-files to local-file. If globbing is
enabled, globbing metacharacters are expanded. If interactive
prompting is on, ftp prompts the user to verify that the last
argument is indeed the target local file for mdir output.
mget remote-files
Copy remote-files to the local system. If globbing is enabled,
globbing metacharacters are expanded. The resulting local file
names are processed according to case, ntrans, and nmap settings.
mkdir directory-name
Create remote directory-name.
mls remote-files local-file
Write an abbreviated listing of remote-files to local-file. If
globbing is enabled, globbing metacharacters are expanded. If
interactive prompting is on, ftp prompts the user to verify that
the last argument is indeed the target local file for mls output.
mode [mode-name]
Set the FTP file transfer mode to mode-name. The only supported
mode is stream.
modtime remote-file
Show the last modification time of remote-file.
mput local-files
Copy local-files from the local system to the remote system. The
remote files have the same name as the local files processed
according to ntrans and nmap settings. If globbing is enabled,
globbing characters are expanded.
newer file-name
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 newer. Otherwise, this command is identical to get.
nlist [remote-directory] [local-file]
Write an abbreviated listing of remote-directory to local-file.
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 nlist output.
nmap [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 mput commands
and put commands issued without a specified remote target
filename. If arguments are specified, local filenames are mapped
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. 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). 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 are used to determine the
nmap inpattern variable values. For example, given inpattern
$1.$2 and the remote file name mydata.data, $1 would have the
value mydata, and $2 would have 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]
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 can be included 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 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 server-host [port-number]
Establish a connection to server-host, using port-number (if
specified). If auto-login is enabled, ftp attempts to log into
the server host.
prompt
Toggle interactive prompting. By default, ftp prompts the user
for a yes or no response for each output file during multiple-
file commands. If interactive prompting is disabled, ftp
performs the command for all specified 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 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]
Copy local-file to remote-file. If remote-file is unspecified,
ftp assigns the local-file name, processed according to any
ntrans or nmap settings, to the remote-file name.
pwd Write the name of the remote working directory to stdout.
quit A synonym for bye.
quote arguments
Send arguments, verbatim, to the server host. See ftpd(1M).
recv remote-file [local-file]
A synonym for get.
reget remote-file [local-file]
reget 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 command is
useful when transferring very large files over networks that tend
to drop connections.
rhelp [command-name]
Request help from the server host. If command-name is specified,
supply it to the server. See ftpd(1M).
rstatus [file-name]
With no arguments, show status of remote machine. If file-name
is specified, show status of file-name on remote machine.
rename remote-from remote-to
Rename remote-from, which can be either a file or a directory, to
remote-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 remote-directory
Delete remote-directory. remote-directory must be an empty
directory.
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, 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. ftp reports the 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]
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. If the PORT command fails, ftp uses the default data
port. When the use of PORT commands is disabled, ftp makes no
attempt to use PORT commands for each data transfer. This is
useful for certain FTP implementations that ignore PORT commands
but (incorrectly) indicate that they've been accepted. See
ftpd(1M). Turning sendport off may cause delays in the execution
of commands.
site arguments
Send arguments, verbatim, to the server host as a SITE command.
See ftpd(1M).
size remote-file
Show the size of remote-file.
status
Show the current status of ftp.
struct [struct-name]
Set the FTP file transfer struct to struct-name. The only
supported struct is file.
sunique
Toggle storing of files on remote machine under unique file
names. The remote server reports the unique name. By default,
sunique is off.
system
Show the type of operating system running on the remote machine.
tenex
Set the FTP file transfer type to tenex.
type [type-name]
Set the FTP file transfer type to type-name. If type-name is
unspecified, write the current type to stdout. Ascii, binary,
and tenex are the types currently supported.
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]
Log into the server host on the current connection, which must
already be open. A .netrc file in the user's local home
directory can provide the user-name, password, and optionally the
account; see netrc(4). Otherwise ftp prompts the user for this
information. The HP-UX FTP server does not require an account.
For security reasons, ftp always requires a password. It does
not log into remote accounts that do not have a password.
verbose
Toggle verbose output. If verbose output is enabled, ftp
displays responses from the server host, and when a file transfer
completes it reports statistics regarding the efficiency of the
transfer.
? [command]
A synonym for the help command. Prints the help information for
the specified command.
Aborting A File Transfer
To abort a file transfer, use the terminal interrupt key (usually
Ctrl-C). Sending transfers are halted immediately. ftp halts
incoming (receive) transfers by first sending a FTP protocol ABOR
command to the remote server, then discarding any further received
data. 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, an ftp> prompt does not appear until the
remote server completes sending the requested file.
The terminal interrupt key sequence is ignored while ftp awaits 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 manually.
File Naming Conventions
Files specified as arguments to ftp commands are processed according
to the following rules.
+ If the file name - is specified, ftp uses the standard input (for
reading) or standard output (for writing).
+ If the first character of the file name is |, ftp interprets the
remainder of the argument as a shell command. ftp forks a shell,
using popen() (see popen(3S)) with the supplied argument, and reads
(writes) from standard output (standard input). 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".
+ Otherwise, if globbing is enabled, ftp expands local file names
according to the rules used by the C shell (see csh(1)); see the
glob command, below. If the ftp command expects a single local
file (e.g. put), only the first filename generated by the globbing
operation is used.
+ For mget commands and get commands with unspecified local file
names, the local filename is named the same as the remote filename,
which may be altered by a case, ntrans, or nmap setting. The
resulting filename may then be altered if runique is on.
+ For mput commands and put commands with unspecified remote file
names, the remote filename is named the same as the local filename,
which may be altered by a ntrans or nmap setting. The resulting
filename may then be altered by the remote server if sunique is on.
WARNINGS
Correct execution of many commands depends upon proper behavior by the
remote server.
AUTHOR
ftp was developed by the University of California, Berkeley.
SEE ALSO
csh(1), rcp(1), ftpd(1M), netrc(4), ftpusers(4), hosts(4).