src/usr.bin/ftp/ftp.1 - diff

Return to ftp.1 CVS log

Up to [local] / src / usr.bin / ftp

Diff for /src/usr.bin/ftp/ftp.1 between version 1.5 and 1.6

version 1.5, 1996/11/09 19:56:23

version 1.6, 1997/02/03 01:02:38

Line 1

.\" $OpenBSD$

.\" $NetBSD: ftp.1,v 1.17 1997/02/01 10:45:01 lukem Exp $

.\" $NetBSD: ftp.1,v 1.11 1995/09/08 01:06:24 tls Exp $

.\"

Line 34

Line 33

.\"

.\" @(#)ftp.1 8.3 (Berkeley) 10/9/94

.\"

.Dd October 9, 1994

.Dd January 20, 1997

.Dt FTP 1

.Os BSD 4.2

.Sh NAME

Line 43

Line 42

.Tn ARPANET

file transfer program

.Sh SYNOPSIS

.Nm ftp

.Nm

.Op Fl t

.Op Fl a

.Op Fl v

.Op Fl d

.Op Fl g

.Op Fl i

.Op Fl n

.Op Fl g

.Op Fl p

.Op Fl r Ar seconds

.Op Fl P Ar port

.Op Ar host

.Op Fl t

.Op Fl v

.Op Fl V

.Op Ar host Op Ar port

.Nm ftp

.Ar http://host/path/file.html

ftp://\fIhost\fR[:\fIport\fR]/\fIfile\fR[/]

.Nm ftp

.Ar ftp://host/path/file.tar.gz

http://\fIhost\fR[:\fIport\fR]/\fIfile\fR

.Nm ftp

.Ar host:/path/file.tar.gz

\fIhost\fR:\fIfile\fR[/]

.Sh DESCRIPTION

.Nm Ftp

.Nm

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

The latter three usage formats will fetch a file using either the

HTTP or FTP protocols into the current directory.

This is ideal for scripts.

.Pp

Options may be specified at the command line, or to the

command interpreter.

.Bl -tag -width flag

.Bl -tag -width "port "

.It Fl t

.It Fl a

Enables packet tracing.

Causes

.It Fl v

.Nm

Verbose option forces

to bypass normal login procedure, and use an anonymous login instead.

.Nm ftp

.It Fl d

to show all responses from the remote server, as well

Enables debugging.

as report on data transfer statistics.

.It Fl g

Disables file name globbing.

.It Fl i

Turns off interactive prompting during

multiple file transfers.

.It Fl n

Restrains

.Nm ftp

.Nm

from attempting \*(Lqauto-login\*(Rq upon initial connection.

from attempting

.Dq auto-login

upon initial connection.

If auto-login is enabled,

.Nm ftp

.Nm

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

.Nm

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

.It Fl p

Turns off interactive prompting during

Enable passive mode operation for use behind connection filtering firewalls.

multiple file transfers.

.It Fl P Ar port

.It Fl d

Sets the port number to

Enables debugging.

.Ar port .

.It Fl g

.It Fl t

Disables file name globbing.

Enables packet tracing.

.It Fl r Ar number

.It Fl v

Retry to connect if failed, pausing for

Enable verbose mode.

.Ar number

This is the default if input is from a terminal.

of seconds.

Forces

.Nm

to show all responses from the remote server, as well

as report on data transfer statistics.

.It Fl V

Disable verbose mode, overriding the default of enabled when input

is from a terminal.

.El

.Pp

The client host with which

.Nm ftp

.Nm

is to communicate may be specified on the command line.

If this is done,

.Nm ftp

.Nm

will immediately attempt to establish a connection to an

.Tn FTP

server on that host; otherwise,

.Nm ftp

.Nm

will enter its command interpreter and await instructions

from the user.

When

.Nm ftp

.Nm

is awaiting commands from the user the prompt

.Ql ftp>

is provided to the user.

Line 178

Line 188

.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

Line 192

Line 202

.It Ic \&cd Ar remote-directory

Change the working directory on the remote machine

.Ar remote-directory .

.It Ic cdup

Change the remote machine working directory to the parent of the

current remote machine working directory.

Line 200

Line 210

Change the permission modes of the file

.Ar file-name

on the remote

sytem to

system to

.Ar mode .

.It Ic close

Terminate the

.Tn FTP

Line 237

Line 247

.Ar debug-value

is specified it is used to set the debugging level.

When debugging is on,

.Nm ftp

.Nm

prints each command sent to the remote machine, preceded

by the string

.Ql \-\->

.It Xo

.It Ic dir Op Ar remote-directory Op Ar local-file

.Ic dir

Print a listing of the contents of a

.Op Ar remote-directory

directory on the remote machine.

.Op Ar local-file

The listing includes any system-dependent information that the server

.Xc

chooses to include; for example, most

Print a listing of the directory contents in the

.Ux

directory,

systems will produce

.Ar remote-directory ,

output from the command

and, optionally, placing the output in

.Ql ls \-l .

.Ar local-file .

(See also

.Ic ls . )

.Ar remote-directory

is left unspecified, the current working directory is used.

If interactive prompting is on,

.Nm ftp

.Nm

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

If no local file is specified, or if

directory on the remote machine is used.

If no local

file is specified, or

.Ar local-file

.Fl ,

.Sq Fl ,

output comes to the terminal.

the output is sent to the terminal.

.It Ic disconnect

A synonym for

.Ar close .

.Ic close .

.It Ic edit

Toggle command line editing, and context sensitive command and file

completion.

This is automatically enabled if input is from a terminal, and

disabled otherwise.

.It Ic exit

A synonym for

.Ic bye .

.It Ic ftp Ar host Op Ar port

A synonym for

.Ic open .

.It Ic form Ar format

Set the file transfer

.Ic form

.Ar format .

The default format is \*(Lqfile\*(Rq.

.It Ic get Ar remote-file Op Ar local-file

Retrieve the

Line 299

Line 321

.Ic mdelete ,

.Ic mget

and

.Ic mput .

If globbing is turned off with

.Ic glob ,

the file name arguments

Line 333

Line 355

Toggle hash-sign (``#'') printing for each data block

transferred.

The size of a data block defaults to 1024 bytes.

This can be changed by specifying a size in bytes.

This can be changed by specifying

.Ar size

in bytes.

.It Ic help Op Ar command

Print an informative message about the meaning of

.Ar command .

If no argument is given,

.Nm ftp

.Nm

prints a list of the known commands.

.It Ic idle Op Ar seconds

Set the inactivity timer on the remote server to

Line 353

Line 377

.Ar directory

is specified, the user's home directory is used.

.It Xo

.It Ic lpwd

.Ic \&ls

Print the working directory on the local machine.

.Op Ar remote-directory

.It Ic \&ls Op Ar remote-directory Op Ar local-file

.Op Ar local-file

Print a list of the files in a

.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 . )

.Ar remote-directory

is left unspecified, the current working directory is used.

If interactive prompting is on,

.Nm ftp

.Nm

will prompt the user to verify that the last argument is indeed the

target local file for receiving

.Ic \&ls

.Ic ls

output.

If no local file is specified, or if

.Ar local-file

.Sq Fl ,

.Fl ,

the output is sent to the terminal.

.It Ic macdef Ar macro-name

Define a macro.

Line 413

Line 427

.Ic dir ,

except multiple remote files may be specified.

If interactive prompting is on,

.Nm ftp

.Nm

will prompt the user to verify that the last argument is indeed the

target local file for receiving

.Ic mdir

Line 443

Line 457

Make a directory on the remote machine.

.It Ic mls Ar remote-files local-file

.Ic nlist ,

.Ic ls ,

except multiple remote files may be specified,

and the

.Ar local-file

must be specified.

If interactive prompting is on,

.Nm ftp

.Nm

will prompt the user to verify that the last argument is indeed the

target local file for receiving

.Ic mls

Line 458

Line 472

Set the file transfer

.Ic mode

.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.

Line 475

Line 489

and

.Ic nmap

settings.

.It Ic msend Ar local-files

A synonym for

.Ic mput .

.It Ic newer Ar 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

.Ic newer .

Otherwise, this command is identical to

.Ar get .

.It Xo

.It Ic nlist Op Ar remote-directory Op Ar local-file

.Ic nlist

A synonym for

.Op Ar remote-directory

.Ic ls .

.Op Ar local-file

.Xc

Print a list of the files in a

directory on the remote machine.

.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

.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.

Line 524

Line 523

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

Line 534

Line 533

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

Line 598

Line 597

Characters in a filename matching a character in

.Ar inchars

are replaced with the corresponding character in

.Ar outchars .

If the character's position in

.Ar inchars

is longer than the length of

Line 611

Line 610

server.

An optional port number may be supplied,

in which case,

.Nm ftp

.Nm

will attempt to contact an

.Tn FTP

server at that port.

If the

.Ic auto-login

option is on (default),

.Nm ftp

.Nm

will also attempt to automatically log the user in to

the

.Tn FTP

Line 638

Line 637

.Dv 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

.Nm ftp

.Nm

through a gateway router or host that controls the directionality of

traffic.

(Note that though ftp servers are required to support the

.Dv PASV

command by RFC 1123, some do not.)

.It Ic preserve

Toggle preservation of modification times on retrieved files.

.It Ic progress

Toggle display of transfer progress bar.

.It Ic prompt

Toggle interactive prompting.

Interactive prompting

Line 656

Line 659

will transfer all files, and any

.Ic mdelete

will delete all files.

.Pp

When prompting is on, the following commands are available at a prompt:

.Bl -tag -width 2n -offset indent

.It Ic n

Do not transfer the file.

.It Ic a

Answer

.Sq yes

to the current file, and automatically answer

.Sq yes

to any remaining files for the current command.

.It Ic p

Answer

.Sq yes

to the current file, and turn off prompt mode

(as is

.Dq prompt off

had been given).

.El

.Pp

Any other reponse will answer

.Sq yes

to the current file.

.It Ic proxy Ar ftp-command

Execute an ftp command on a secondary control connection.

This command allows simultaneous connection to two remote ftp

Line 704

Line 730

.Ic format ,

.Ic mode ,

and

.Ic structure .

.It Ic pwd

Print the name of the current working directory on the remote

machine.

.It Ic quit

A synonym for

.Ic bye .

.It Ic quote Ar arg1 arg2 ...

The arguments specified are sent, verbatim, to the remote

.Tn FTP

server.

.It Ic recv Ar remote-file Op Ar local-file

A synonym for get.

A synonym for

.Ic get .

.It Ic reget Ar remote-file Op Ar local-file

Reget acts like get, except that if

.Ar local-file

Line 739

Line 766

If a

.Ar command-name

is specified it is supplied to the server as well.

.It Ic remotestatus Op Ar file-name

.It Ic rstatus Op Ar file-name

With no arguments, show status of remote machine.

.Ar file-name

is specified, show status of

.Ar file-name

on remote machine.

.It Xo

.It Ic rename Op Ar from Op Ar to

.Ic rename

.Op Ar from

.Op Ar to

.Xc

Rename the file

.Ar from

on the remote machine, to the file

.Ar to .

.It Ic reset

Clear reply queue.

This command re-synchronizes command/reply sequencing with the remote

Line 768

Line 791

.Ic put

at the

indicated

.Ar marker .

.Ux

systems, marker is usually a byte

Line 794

Line 817

(see below).

The default value is off.

.It Ic send Ar local-file Op Ar remote-file

A synonym for put.

A synonym for

.Ic put .

.It Ic sendport

Toggle the use of

.Dv PORT

commands.

By default,

.Nm ftp

.Nm

will attempt to use a

.Dv PORT

command when establishing

Line 812

Line 836

If the

.Dv PORT

command fails,

.Nm ftp

.Nm

will use the default data port.

When the use of

.Dv PORT

Line 837

Line 861

on remote machine.

.It Ic status

Show the current status of

.Nm ftp .

.It Ic struct Op Ar struct-name

Set the file transfer

.Ar structure

Line 865

Line 889

Set the file transfer

.Ic type

.Ar type-name .

If no type is specified, the current type

is printed.

The default type is network

.Tn ASCII .

.It Ic umask Op Ar newmask

Set the default umask on the remote server to

.Ar newmask .

.Ar newmask

is omitted, the current umask is printed.

.It Xo

.Ic user Ar user-name

.Op Ar password

.Op Ar password Op Ar account

.Op Ar account

.Xc

Identify yourself to the remote

.Tn FTP

Line 887

Line 910

If the

.Ar password

is not specified and the server requires it,

.Nm ftp

.Nm

will prompt the user for it (after disabling local echo).

If an

.Ar account

Line 902

Line 925

is completed if the remote server did not require it

for logging in.

Unless

.Nm ftp

.Nm

is invoked with \*(Lqauto-login\*(Rq disabled, this

process is done automatically on initial connection to

the

Line 920

Line 943

By default,

verbose is on.

.It Ic ? Op Ar command

A synonym for help.

A synonym for

.Ic help .

.El

.Pp

Command arguments which have embedded spaces may be quoted with

quote `"' marks.

.Pp

Commands which toggle settings can take an explicit

.Ic on

.Ic off

argument to force the setting appropriately.

.Pp

.Nm

receives a

.Dv SIGINFO

(see the

.Dq status

argument of

.Xr stty 1 )

signal whilst a transfer is in progress, the current transfer rate

statistics will be written to the standard error output, in the

same format as the standard completion message.

.Sh AUTO-FETCHING FILES

In addition to standard commands, this version of

.Nm

supports an auto-fetch feature.

To enable auto-fetch, simply pass the list of hostnames/files

on the command line.

.Pp

The following formats are valid syntax for an auto-fetch element:

.Bl -tag -width "http://host[:port]/file"

.It host:/file

.Dq Classic

ftp format

.It ftp://host[:port]/file

FTP URL, using the ftp protocol.

.It http://host[:port]/file

HTTP URL, using the http protocol.

.Ev http_proxy

is defined, it is used as a URL to an HTTP proxy server.

.El

.Pp

If a classic format or a ftp URL format has a trailing

.Sq / ,

then

.Nm

will connect to the site and

.Ic cd

to the directory given as the path, and leave the user in interactive

mode ready for further input.

.Pp

If successive auto-fetch ftp elements refer to the same host, then

the connection is maintained between transfers, reducing overhead on

connection creation and deletion.

.Sh ABORTING A FILE TRANSFER

To abort a file transfer, use the terminal interrupt key

(usually Ctrl-C).

Line 944

Line 1019

sending the requested file.

.Pp

The terminal interrupt key sequence will be ignored when

.Nm ftp

.Nm

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

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

.Nm ftp

.Nm

program must be killed by hand.

.Sh FILE NAMING CONVENTIONS

Files specified as arguments to

.Nm ftp

.Nm

commands are processed according to the following rules.

.Bl -enum

.It

Line 971

Line 1046

.Sq \&| ,

the

remainder of the argument is interpreted as a shell command.

.Nm Ftp

.Nm

then forks a shell, using

.Xr popen 3

with the argument supplied, and reads (writes) from the stdout

Line 980

Line 1055

must be quoted; e.g.

\*(Lq" ls -lt"\*(Rq.

A particularly

useful example of this mechanism is: \*(Lqdir more\*(Rq.

useful example of this mechanism is: \*(Lqdir \&|more\*(Rq.

.It

Failing the above checks, if ``globbing'' is enabled,

local file names are expanded

Line 990

Line 1065

.Ic glob

command.

If the

.Nm ftp

.Nm

command expects a single local file (.e.g.

.Ic put ) ,

only the first filename generated by the "globbing" operation is used.

Line 1035

Line 1110

and

.Tn PDP Ns -20's

mostly).

.Nm Ftp

.Nm

supports the ascii and image types of file transfer,

plus local byte size 8 for

.Ic tenex

mode transfers.

.Pp

.Nm Ftp

.Nm

supports only the default values for the remaining

file transfer parameters:

.Ic mode ,

.Ic form ,

and

.Ic struct .

.Sh THE .netrc FILE

The

.Pa .netrc

Line 1065

Line 1140

file for a

.Ic machine

token that matches the remote machine specified on the

.Nm ftp

.Nm

command line or as an

.Ic open

command argument.

Line 1117

Line 1192

file for any user other

than

.Ar anonymous ,

.Nm ftp

.Nm

will abort the auto-login process if the

.Pa .netrc

is readable by

Line 1132

Line 1207

.It Ic macdef Ar name

Define a macro.

This token functions like the

.Nm ftp

.Nm

.Ic macdef

command functions.

A macro is defined with the specified name; its contents begin with the

Line 1145

Line 1220

is defined, it is automatically executed as the last step in the

auto-login process.

.El

.Sh COMMAND LINE EDITING

.Nm

supports interactive command line editing, via the

.Xr editline 3

library.

It is enabled with the

.Ic edit

command, and is enabled by default.

Previous lines can be recalled and edited with the arrow keys,

and other GNU Emacs-style editing keys may be used as well.

.Pp

The

.Xr editline 3

library is configured with a

.Pa .editrc

file - refer to

.Xr editrc 5

for more information.

.Pp

An extra key binding is available to

.Nm

to provide context sensitive command and filename completion

(including remote file completion).

To use this, bind a key to the

.Xr editline 3

command

.Ic ftp-complete .

By default, this is bound to the TAB key.

.Sh ENVIRONMENT

.Nm Ftp

.Nm

utilizes the following environment variables.

.Bl -tag -width Fl

.Bl -tag -width "http_proxy"

.It Ev HOME

For default location of a

.Pa .netrc

file, if one exists.

.It Ev SHELL

For default shell.

.It Ev http_proxy

URL of HTTP proxy to use when making HTTP requests.

.El

.Sh SEE ALSO

.Xr editrc 5 ,

.Xr ftpd 8

.Sh HISTORY

The

.Nm ftp

.Nm

command appeared in

.Bx 4.2 .

.Pp

Various features such as command line editing, context sensitive

command and file completion, dynamic progress bar, automatic

fetching of files, ftp and http URLs, and modification time

preservation were implemented in

.Nx 1.2b

by Luke Mewburn, with assistance from Jason Thorpe.

.Sh BUGS

Correct execution of many commands depends upon proper behavior

by the remote server.