ftp(1) CLIX ftp(1)
NAME
ftp - Runs the ARPANET file transfer program
SYNOPSIS
ftp [-v] [-d [value]] [-i] [-n] [-g] [-r] [-p[value]] [-h|-H] [host
[port]]
FLAGS
-v Turns on verbose mode. Verbose mode displays all responses
from the remote server and reports data transfer statistics.
By default, verbose is on.
-d [value] Enables debugging. If an integer value is specified, value
becomes the debugging level. If no value is specified, the
default of 1 is used.
-i Turns off interactive prompting during multiple file
transfers.
-n Suppresses auto-login on initial connection. If auto-login
is enabled, ftp checks the .netrc file in the user's home
directory for an entry describing parameters to be used in
logging in to the remote machine. If no entry exists, ftp
prompts for a login name to be used on the remote machine.
If no login name is given, a login is attempted with the
user's local login name. If the username exists, ftp prompts
for a password and an account (see account in the
``Commands'' subsection).
-g Disables filename globbing. (Does not expand wildcard
characters (see glob in the ``Commands'' subsection).)
-r Displays the ftp version number before entering the command
interpreter.
-p[value] Suppresses transmission of the PWD command primitive when
initially connecting to a remote host. Also specifies
explicitly whether the remote host supports the old FTP
protocol command set (value=0), or the newer protocol command
set (value=1). There should be no space between -p and
value.
By default, ftp sends the PWD primitive (defined only in the
newer protocol command set) whenever it establishes a
connection to a remote host to determine if the remote system
understands the newer protocol.
By using this flag, the PWD primitive is suppressed when a
2/94 - Intergraph Corporation 1
ftp(1) CLIX ftp(1)
command connection is established. If a value of 0 is
specified (the default if no value is specified), ftp assumes
the remote server runs the older set of protocol commands
described in RFC 765. If a nonzero value is specified, ftp
assumes the newer protocol set (defined in RFC 959) is
understood by the remote host.
-h Disables history file usage. Instead, an in-memory buffer is
used for command-line recall.
-H filename Specifies an alternate file for ftp command-line history
entries. The default history file is ~/.ftp_history.
DESCRIPTION
The ftp command is the user interface to the ARPANET standard File
Transfer Protocol (FTP) and transfers files to and from a remote or local
network site. If a remote host is specified on the command line, ftp
attempts to establish a command connection to an FTP server on that host.
After a connection is established and the user has successfully logged in
to the remote host, the ftp> command prompt appears. If no host is
specified on the command line, ftp immediately enters command mode
(displaying the ftp> prompt) and waits for an ftp command to be keyed in.
Optionally, a port number can be specified on the command line following
the hostname. In this case, ftp attempts to connect to an FTP server at
the indicated port.
The remote username must have a valid password in the remote system's
/etc/passwd file for ftp to make a connection. The only exceptions to
this password restriction are the "ftp" and "anonymous" logins. If either
of these two usernames is set up on the remote system (and does not have a
password), ftp will allow you to log in without prompting you for a
password; however you will be restricted to to the use of that login
directory and its subdirectories. For all ftp commands to work properly,
"ftp" and "anonymous" login directories must be set up according to the
access restrictions described in the ftpd(8) manual page.
The ftp command can also be used to communicate with Intergraph ISO/OSI
nodes on the network by using the FTAM/FTP gateway product, which enables
the file transfer between an OSI node and a TCP/IP node.
When using ftp with the FTP/FTAM gateway, the true destination is encoded
in the username (that is user@osihost) or using the ftp SITE command. If
further accounting information is required by the true destination, the
ftp ACCT command is used separately and the SITE command must be used to
specify the destination.
Note that the FTP/FTAM gateway is currently available only on a different
port than the ftp command on the gateway. To select the FTP/FTAM gateway,
you must tell your ftp client program to connect to port 701 on the
2 Intergraph Corporation - 2/94
ftp(1) CLIX ftp(1)
gateway host.
The /etc/ftpusers file can be used to limit ftp access to a machine. If
an ftp connection request comes from a remote user whose username is
listed in the /etc/ftpusers file on the local machine, the connection will
be refused.
Commands
The following commands are valid in ftp interactive mode when entered at
the ftp> prompt:
! [command [args]]
Invokes an interactive shell on the local machine. If there are
arguments, the first is interpreted as a command to execute; the
remaining arguments are the command's arguments.
$ 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 (if a remote system requires it)
to access resources. If no argument is included, the user is
prompted for an account password in a nonechoing input mode.
append local-file [remote-file]
Appends a local file to a file on the remote machine. If remote-
file is unspecified, the local-file name is used to name the remote
file after the local filename is altered by any ntrans or nmap
setting. File transfer uses the current settings for type, form,
mode, and struct.
ascii Sets the file transfer type to network ASCII. This is the default
type.
bell Toggles on and off the bell that sounds after each completed data
transfer (default is off).
binary Sets the file transfer type to support binary image transfer.
bye Terminates the FTP session with the remote server and exits ftp.
An end-of-file signal also terminates the session and exits.
case Toggles remote filename case mapping during mget commands (default
is off). When case is on, for every remote file being transferred
whose filename contains letters which are all uppercase, that
filename is written locally with the letters mapped to lowercase.
cd remote-directory
Changes the working directory on the remote machine to remote-
2/94 - Intergraph Corporation 3
ftp(1) CLIX ftp(1)
directory.
cdup Changes the remote working directory to the parent of the current
remote working directory.
close Terminates the FTP session with the remote server and returns to
the command interpreter. Any defined macros are erased.
cr Toggles carriage-return stripping during ASCII-type file retrieval
(default is on). Records are denoted by a <Return> <Line Feed>
sequence during ASCII-type file transfer. When cr is on, carriage
returns are stripped from this sequence to conform to the CLIX
single linefeed record delimiter. Records on non-CLIX 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
Deletes the file remote-file on the remote machine.
debug [debug-value]
Sets or toggles the debugging mode (default is off). If an
optional debug-value is specified, this value sets the debugging
level. If debug-value is not specified, debugging mode is toggled.
If debugging is toggled on, the default debugging value is 1. When
debugging is on, ftp displays each command sent to the remote
machine, preceded by the string -->. If debug-value is set to 1, a
user's password is not displayed.
dir [remote-directory] [local-file]
Displays a long listing of the contents of the remote-directory
and, optionally, places the output in local-file. 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
specified with a dash (-), the output is written to stdout.
disconnect
A synonym for close.
edit [mode]
Sets or displays the editing mode. The valid choices for the mode
parameter include vi, emacs, memacs, gmacs, and xemacs. The
default is vi, or the editor defined by the VISUAL environment
variable. If no arguments are included with the edit command, the
current setting is displayed.
form form
Sets the file transfer format to form. The only format currently
supported is non-print.
get remote-file [local-file]
4 Intergraph Corporation - 2/94
ftp(1) CLIX ftp(1)
Retrieves the remote-file and stores it on the local machine. If
the local filename is not specified, it is given the name it has on
the remote machine. However, the current case, ntrans, and nmap
settings can alter this name. The current settings for type, form,
mode, and struct are used while the file is being transferred.
glob Allows or disallows the use of wildcard characters in filenames.
The glob (global) command is a toggle command, which is on by
default. When glob is on, wildcard characters are allowed and are
used to specify multiple files with the mdelete, mget, mls, and
mput commands. If glob is off, ftp interprets filename characters
literally and not as wildcard characters. Globbing for mput is
performed as it is in sh. For mdelete and mget, each remote
filename is expanded separately on the remote machine and the lists
are not merged. Expansion of a directory name will likely differ
from expansion of an ordinary filename: the exact result depends on
the foreign operating system and the FTP server and can be
previewed by executing the mls command as follows, where the dash
(-) specifies the output be sent to stdout:
mls remote-files -
The mget and mput commands are not meant to transfer entire
directory subtrees of files. This can be done by transferring a
tar archive of the subtree (in binary mode).
hash Toggles on and off the displaying of the number or ``hash'' sign
(#) for each data block transferred (default is off). The size of
a data block is 1024 bytes.
help [command]
Displays an informative message about the meaning of command. If
no argument is given, ftp displays a list of the known commands.
lcd [directory]
Changes the working directory on the local machine. If no
directory is specified, the user's home directory is used.
ls [-ls] [remote-directory] [local-file]
Displays an abbreviated listing of a remote directory's contents.
If the -ls flag is included, a long listing, including block size
for each file, is given. Otherwise, only filenames are listed. If
remote-directory is unspecified, the current working directory is
used. If no local-file is specified, or if local-file is a dash
(-), the output is sent to stdout. Note that the -ls flag is
hard-coded, thus any character immediately following the dash is
interpreted as -ls. The dir command duplicates the output of the
-ls flag.
macdef macro-name
2/94 - Intergraph Corporation 5
ftp(1) CLIX ftp(1)
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 a dollar sign ($) and a
backslash (\) as special characters. A dollar sign followed by a
number (or numbers) is replaced by the corresponding 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 command line; on the second pass it is
replaced by the second argument; and so on. A backslash followed
by any character is replaced by that character. Use the backslash
to prevent special treatment of the dollar sign.
mdelete [remote-files]
Deletes remote-files on the remote machine. If remote-files are
not specified following the command, the user is prompted for them.
mdir remote-files local-file
Resembles dir except multiple remote files and directories can be
specified. If interactive prompting is on, ftp prompts the user to
verify that the last argument is the target local file for
receiving mdir output. Therefore, a dash (-) should be specified
for the local-file parameter to see the output (if stdout is a
terminal).
mget remote-files
Expands the remote-files on the remote machine and executes get for
each filename produced. See glob for details on the filename
expansion. Resulting filenames are then processed according to
case, ntrans, and nmap settings. Files are transferred into the
local working directory, which can be changed by entering lcd
directory; new local directories can be created by entering ! mkdir
directory.
mkdir directory-name
Makes a directory on the remote machine.
mls remote-files local-file
Similar to ls, except multiple remote files can be specified. If
interactive prompting is on, ftp prompts the user to verify that
the last argument is indeed the target local file for receiving mls
output. (See mdir described previously.)
mode [mode-name]
Sets the file transfer mode to mode-name. The only mode currently
supported is stream mode.
mput local-files
6 Intergraph Corporation - 2/94
ftp(1) CLIX ftp(1)
Expands wildcards in the list of local files given as arguments,
and executes put for each file in the resulting list. See glob for
details of filename expansion. Resulting filenames are then
processed according to ntrans and nmap settings.
nmap [inpattern outpattern]
Sets or unsets the filename mapping mechanism. If arguments are
not 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-CLIX remote computer with different file naming conventions or
practices. The mapping follows the pattern set by inpattern and
outpattern. The inpattern is a template for incoming filenames
(which may have been processed according to the ntrans and case
settings). Variable templating is accomplished by including the
sequences $1, $2, ... , $9 in inpattern. A backslash (\) prevents
this special treatment of the dollar sign ($) character. All other
characters are treated literally and determine the nmap inpattern
variable values. For example, given inpattern $1.$2 and the remote
filename 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 following
command would yield the output filename myfile.data for input
filenames myfile.data and myfile.data.old, the output filename
myfile.file for the input filename myfile, and the output filename
myfile.myfile for the input filename .myfile .
nmap $1.$2.$3 [$1,$2].[$2,file]
Spaces can be included in outpattern when enclosed in double
quotes.
A backslash prevents special treatment of the dollar sign, open
bracket ([), close bracket (]), and comma (,) characters.
ntrans [inchars [outchars]]
Sets or unsets the filename character translation mechanism. If
arguments are not 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. An example ntrans command would be
2/94 - Intergraph Corporation 7
ftp(1) CLIX ftp(1)
as follows:
ftp> ntrans "( )" ..
This command will translate a filename such as file(33)txt to
file.33.txt. The ntrans command is useful when connecting to a
non-CLIX 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 filename.
open host [port]
Establishes a connection to the specified host FTP server. An
optional port number can be supplied. If a port number is
specified, ftp attempts to contact an FTP server at that port. If
the auto-login option is on (default), ftp also attempts to
automatically log the user in to the FTP server. (See the
description for proxy.)
prompt Toggles interactive prompting (default is on). Interactive
prompting occurs during multiple file transfers to selectively
retrieve or store files. If prompting is turned off, any mget or
mput transfers all specified files, and any mdelete deletes all
specified files.
proxy ftp-command
Executes an ftp command on a secondary control connection. This
command simultaneously connects 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
that are executable on the secondary connection. The following
commands work differently when prefixed 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 on the server on the secondary control connection supporting
the FTP protocol PASV command.
put local-file [remote-file]
Stores a local file on the remote machine. If remote-file is not
specified, the local filename is used after processing according to
any ntrans or nmap settings in naming the remote file. File
transfer uses the current settings for type, form, mode, and
struct.
pwd Displays the name of the current working directory on the remote
8 Intergraph Corporation - 2/94
ftp(1) CLIX ftp(1)
machine.
quit A synonym for bye.
quote arg1 arg2 ...
Sends, verbatim, the specified arguments to the remote FTP server.
Not all ftp commands can be sent using the quote command. It is
used primarily as a debugging tool.
recv remote-file [local-file]
A synonym for get.
remotehelp [command-name]
Requests help from the remote FTP server. If a command-name is
specified, it is supplied to the server.
rename [from] [to]
Renames the file from on the remote machine to the file to.
reset Clears the reply queue. This command resynchronizes command/reply
sequencing with the remote FTP server. Resynchronization may be
necessary following a violation of the FTP protocol by the remote
server.
rmdir directory-name
Deletes a directory on the remote machine.
runique
Toggles storing of files on the local system with unique filenames
(default is off). 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 displayed and the
transfer does not occur. The generated unique filename is
reported. Note that runique does not affect local files generated
from a shell command. (See the subsection titled ``File Naming
Conventions.'')
send local-file [remote-file]
A synonym for put.
sendport
Toggles the use of PORT commands. By default, ftp attempts to use
a PORT command when establishing a connection for each data
transfer. PORT commands can prevent delays during multiple file
transfers. If the PORT command fails, ftp uses the default data
port. When PORT commands are disabled, no attempt is made to use
PORT commands for each data transfer. This is useful for certain
FTP implementations that ignore PORT commands but incorrectly
indicate that they have been accepted.
2/94 - Intergraph Corporation 9
ftp(1) CLIX ftp(1)
status Shows the current status of ftp.
struct [struct-name]
Sets the file transfer structure to struct-name. The only
structure currently supported is file.
sunique
Toggles storing of files on remote machine under unique filenames
(default is off). The remote FTP server must support the FTP
protocol STOU command for successful completion. The remote server
reports a unique name.
tenex Sets the file transfer type to that needed to communicate with
TENEX machines.
trace Toggles packet tracing. This mode is not currently implemented.
type [type-name]
Sets the file transfer type to type-name. If no type is specified,
the current type is displayed. The default type is network ASCII.
user username [password] [account]
Identifies the user to the remote FTP server if the -n flag is not
used. If password is not specified and the server requires it, ftp
prompts the user for it (after disabling local echo). If account
is not specified and the FTP server requires it, the user is
prompted for it. If an account field is specified, an FTP ACCT
command is relayed to the remote server after the login sequence is
complete if the remote server did not require it for logging in.
Unless ftp is invoked with auto-login disabled, this process occurs
automatically when the FTP server is initially connected to. If an
invalid username or password was given in the auto-login process or
in a previous user command, the user command should be used to
specify a valid username.
verbose
Toggles verbose mode (default is on). 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.
? [command]
A synonym for help.
Aborting File Transfer
To abort a file transfer, press the terminal interrupt key (usually the
<Ctrl-C> sequence). Transfer of local files to the remote machine is
immediately halted. Transfer of remote files to the local system is
halted by sending an FTP protocol ABOR command to the remote server and
discarding any further data received. The speed at which this is
10 Intergraph Corporation - 2/94
ftp(1) CLIX ftp(1)
accomplished depends on 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 has completed sending the
requested file.
The terminal 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
previously or from the remote server behaving unexpectedly, including
violation of the FTP protocol. If the delay results from unexpected
remote server behavior, the local ftp must be killed manually.
File Naming Conventions
Files specified as arguments to ftp commands are processed according to
the following rules.
⊕ If a dash (-) is specified for the filename, stdin (for reading) or
stdout (for writing) is used.
⊕ 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. It
then reads from stdout (or writes to stdin). If the shell command
includes spaces, the argument must be quoted as in "| ls -lt". A
useful example of this mechanism is "dir * | pg".
⊕ Failing the previous checks, if globbing is enabled, local filenames
are expanded according to the rules used in the sh (see glob in the
``Commands'' subsection). If the ftp command expects a single local
file (such as put), only the first filename generated by the globbing
operation is used.
⊕ For mget and get commands with unspecified local filenames, the local
filename is the remote filename, which may be altered by a case,
ntrans, or nmap setting. The local client can then alter the resulting
filename if runique is on.
⊕ For mput and put commands with unspecified remote filenames, the remote
filename is the local filename, which may be altered by an ntrans or
nmap setting. The resulting filename may then be altered by the remote
server if sunique is on.
File Transfer Parameters
The FTP specification specifies many parameters that may affect a file
transfer. The file type can be ASCII, image (binary), EBCDIC, or local
byte size (mostly for PDP-10s and PDP-20s). The ftp command supports the
ASCII and image file transfer types plus local byte size 8 for TENEX mode
transfers. The ftp command treats image and TENEX 8 file types the same
when transferred.
2/94 - Intergraph Corporation 11
ftp(1) CLIX ftp(1)
Command-line Recall
While in ftp interactive mode (at the ftp> prompt), command-line recall
and editing features are available for both emacs and vi editors,
depending on the editor defined by any of the following environment
variables found in your .env file (listed in order of preference):
VISUAL
EDITOR
FCEDIT
These variables can be set to vi, emacs, memacs, gmacs, or xemacs. If
none of these variables are defined, the default editor is vi.
The previous commands are maintained in a history file. The size, in
lines, of the history file can be set with the FTPHISTSIZE environment
variable. The default size is 100 lines.
The emacs editing mode is entered by enabling either the emacs or gmacs
option. (The only difference between these two modes is the way they
handle <Ctrl-T>. To edit, move the cursor to the point needing correction
and insert or delete characters or words as needed. All editing commands
are control characters or escape sequences. For example, <Ctrl-F> is
entered by pressing <Ctrl> followed by <F>. (The <Shift> key is not
pressed.)
For escape sequences, the notation is <Esc> followed by a character. For
example, <Esc> <f>is <Esc> followed by <F>. <Esc> <F> would be the
notation for <Esc> followed by <Shift> <F>.
All emacs edit commands operate from any place on the line (not just at
the beginning).
The vi editor has two typing modes. Initially, when you enter a command,
you are in the input mode. To edit, enter control mode by pressing <Esc>,
move the cursor to the point needing correction, and insert or delete
characters or words as needed. Most control commands accept an optional
repeat count prior to the command.
When in vi mode on most systems, canonical processing is initially
enabled, and the command will be echoed again if the speed is 1200 baud or
greater and it either contains any control characters or less than one
second has elapsed since the prompt was printed. The <Esc> character
terminates canonical processing for the remainder of the command, and the
user can then modify the command line. This scheme has the advantages of
canonical processing with the type-ahead echoing of raw mode.
EXAMPLES
12 Intergraph Corporation - 2/94
ftp(1) CLIX ftp(1)
1. To open an FTP connection to host bob, enter:
ftp bob
2. To start ftp in command mode with verbose on, debugging on at its
default level (1), and interactive prompting off, enter:
ftp -vdi
3. To start ftp with a connection to host bob that suppresses the PWD
command (taking the default 0), suppresses auto-login to the host,
disables filename globbing, and displays the current version number
prior to displaying the ftp prompt, enter:
ftp -ngr -p bob
4. The following is an example session of using ftp to connect to an
ISO/OSI host:
$ ftp
ftp> open gateway 701
Name (gateway:user): user@host
Password:
FILES
/etc/resolv.conf
Domain Name System client configuration file. DNS is the
preferred method for host address resolution.
/etc/hosts Hostname database.
/etc/services Service name database.
$HOME/.netrc ftp configuration file (residing in the user's home
directory).
/etc/ftpusers File restricting ftp access to a machine.
NOTES
Correct command execution depends on the remote server working properly.
Command arguments that have embedded spaces must be quoted by enclosing
the argument in quotation marks (" ").
Hosts names are looked up in the /etc/hosts file.
2/94 - Intergraph Corporation 13
ftp(1) CLIX ftp(1)
DIAGNOSTICS
ftp: ftp/tcp unknown service
The FTP service must be added to the /etc/services file.
ftp: lost connection with remote server
Unexpected termination of command connection, or error while
reading or writing on the command connection.
Other pertinent error messages are generated by the perror() function.
The cause for the error message can be derived from either a connection-
related function, such as select(), connect(), socket(), setsockopt(),
bind(), accept(), or from an I/O problem, such as a read or write to the
specified file.
EXIT VALUES
The ftp command exits with a value of 0 if exiting with the quit command.
If an error occurs, it exits with a nonzero value.
RELATED INFORMATION
Commands: ftam(1), ftamd(8), ftamd-ftp(8), ftpd(8), ftpd-ftam(8),
osiconfig(8), iso_listener(8), inetd(8), sh(1)
Functions: popen(3)
Files: ftpusers(4), hosts(4), hosts.ftam(4), inetd.conf(4),
isoservices(4), netrc(4), services(4)
TCP/IP User's Guide
14 Intergraph Corporation - 2/94