[BACK]Return to ftp.1 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / usr.bin / ftp

Annotation of src/usr.bin/ftp/ftp.1, Revision 1.93

1.93    ! lukem       1: .\"    $NetBSD: ftp.1,v 1.92 2003/02/25 10:35:42 wiz Exp $
1.52      lukem       2: .\"
1.93    ! lukem       3: .\" Copyright (c) 1996-2003 The NetBSD Foundation, Inc.
1.52      lukem       4: .\" All rights reserved.
                      5: .\"
                      6: .\" This code is derived from software contributed to The NetBSD Foundation
                      7: .\" by Luke Mewburn.
                      8: .\"
                      9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\" 3. All advertising materials mentioning features or use of this software
                     18: .\"    must display the following acknowledgement:
                     19: .\"    This product includes software developed by the NetBSD
                     20: .\"    Foundation, Inc. and its contributors.
                     21: .\" 4. Neither the name of The NetBSD Foundation nor the names of its
                     22: .\"    contributors may be used to endorse or promote products derived
                     23: .\"    from this software without specific prior written permission.
                     24: .\"
                     25: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     26: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     27: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
                     28: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
                     29: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
                     30: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     31: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     32: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     33: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     34: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     35: .\" POSSIBILITY OF SUCH DAMAGE.
                     36: .\"
1.11      tls        37: .\"
1.6       cgd        38: .\" Copyright (c) 1985, 1989, 1990, 1993
                     39: .\"    The Regents of the University of California.  All rights reserved.
1.1       cgd        40: .\"
                     41: .\" Redistribution and use in source and binary forms, with or without
                     42: .\" modification, are permitted provided that the following conditions
                     43: .\" are met:
                     44: .\" 1. Redistributions of source code must retain the above copyright
                     45: .\"    notice, this list of conditions and the following disclaimer.
                     46: .\" 2. Redistributions in binary form must reproduce the above copyright
                     47: .\"    notice, this list of conditions and the following disclaimer in the
                     48: .\"    documentation and/or other materials provided with the distribution.
                     49: .\" 3. All advertising materials mentioning features or use of this software
                     50: .\"    must display the following acknowledgement:
                     51: .\"    This product includes software developed by the University of
                     52: .\"    California, Berkeley and its contributors.
                     53: .\" 4. Neither the name of the University nor the names of its contributors
                     54: .\"    may be used to endorse or promote products derived from this software
                     55: .\"    without specific prior written permission.
                     56: .\"
                     57: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
                     58: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     59: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     60: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
                     61: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     62: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     63: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     64: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     65: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     66: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     67: .\" SUCH DAMAGE.
                     68: .\"
1.11      tls        69: .\"    @(#)ftp.1       8.3 (Berkeley) 10/9/94
1.1       cgd        70: .\"
1.90      wiz        71: .Dd January 20, 2003
1.1       cgd        72: .Dt FTP 1
1.35      garbled    73: .Os
1.1       cgd        74: .Sh NAME
                     75: .Nm ftp
                     76: .Nd
1.55      lukem      77: Internet file transfer program
1.1       cgd        78: .Sh SYNOPSIS
1.92      wiz        79: .Nm
1.79      lukem      80: .Op Fl 46AadefginpRtvV
1.60      lukem      81: .Bk -words
1.74      lukem      82: .Op Fl N Ar netrc
                     83: .Ek
                     84: .Bk -words
1.60      lukem      85: .Op Fl o Ar output
                     86: .Ek
1.33      mycroft    87: .Bk -words
1.12      lukem      88: .Op Fl P Ar port
1.33      mycroft    89: .Ek
                     90: .Bk -words
1.86      christos   91: .Op Fl q Ar quittime
                     92: .Ek
                     93: .Bk -words
1.60      lukem      94: .Op Fl r Ar retry
1.33      mycroft    95: .Ek
1.42      lukem      96: .Bk -words
1.85      lukem      97: .\" [-T dir,max[,inc]]
1.42      lukem      98: .Oo
1.85      lukem      99: .Fl T Xo
1.42      lukem     100: .Sm off
1.60      lukem     101: .Ar dir ,
                    102: .Ar max
                    103: .Op , Ar inc
1.85      lukem     104: .Sm on
1.42      lukem     105: .Xc
                    106: .Oc
                    107: .Ek
1.33      mycroft   108: .Bk -words
1.85      lukem     109: .\" [[user@]host [port]]
1.60      lukem     110: .Oo
1.85      lukem     111: .Oo Ar user Ns Li \&@ Oc Ns Ar host
1.60      lukem     112: .Op Ar port
                    113: .Oc
1.33      mycroft   114: .Ek
                    115: .Bk -words
1.85      lukem     116: .\" [[user@]host:[path][/]]
                    117: .Sm off
                    118: .Oo
                    119: .Op Ar user Li \&@
                    120: .Ar host Li \&:
                    121: .Op Ar path
                    122: .Op Li /
                    123: .Oc
                    124: .Sm on
1.33      mycroft   125: .Ek
                    126: .Bk -words
1.85      lukem     127: .\" [file:///path]
                    128: .Sm off
                    129: .Oo
                    130: .Li file:/// Ar path
                    131: .Oc
                    132: .Sm on
1.33      mycroft   133: .Ek
                    134: .Bk -words
1.85      lukem     135: .\" [ftp://[user[:password]@]host[:port]/path[/]]
                    136: .Sm off
                    137: .Oo
                    138: .Li ftp://
                    139: .Oo Ar user
                    140: .Op Li \&: Ar password
                    141: .Li \&@ Oc
                    142: .Ar host Oo Li \&: Ar port Oc
                    143: .Li / Ar path
                    144: .Op Li /
                    145: .Op Li ;type= Ar X
                    146: .Oc
                    147: .Sm on
1.33      mycroft   148: .Ek
                    149: .Bk -words
1.85      lukem     150: .\" [http://[user[:password]@]host[:port]/path]
                    151: .Sm off
                    152: .Oo
                    153: .Li http://
                    154: .Oo Ar user
                    155: .Op Li \&: Ar password
                    156: .Li \&@ Oc
                    157: .Ar host Oo Li \&: Ar port Oc
                    158: .Li / Ar path
                    159: .Oc
                    160: .Sm on
1.33      mycroft   161: .Ek
1.60      lukem     162: .Op Ar \&.\&.\&.
1.92      wiz       163: .Nm
1.67      lukem     164: .Bk -words
1.85      lukem     165: .Fl u Ar url Ar file
1.67      lukem     166: .Ek
                    167: .Op Ar \&.\&.\&.
1.1       cgd       168: .Sh DESCRIPTION
1.12      lukem     169: .Nm
1.55      lukem     170: is the user interface to the Internet standard File Transfer Protocol.
1.1       cgd       171: The program allows a user to transfer files to and from a
                    172: remote network site.
                    173: .Pp
1.60      lukem     174: The last five arguments will fetch a file using the
                    175: .Tn FTP
                    176: or
1.56      lukem     177: .Tn HTTP
                    178: protocols, or by direct copying, into the current directory.
1.18      lukem     179: This is ideal for scripts.
                    180: Refer to
                    181: .Sx AUTO-FETCHING FILES
                    182: below for more information.
                    183: .Pp
1.1       cgd       184: Options may be specified at the command line, or to the
                    185: command interpreter.
1.25      lukem     186: .Bl -tag -width "port   "
1.79      lukem     187: .It Fl 4
                    188: Forces
                    189: .Nm
                    190: to only use IPv4 addresses.
                    191: .It Fl 6
                    192: Forces
                    193: .Nm
                    194: to only use IPv6 addresses.
1.25      lukem     195: .It Fl A
                    196: Force active mode ftp.
                    197: By default,
                    198: .Nm
                    199: will try to use passive mode ftp and fall back to active mode
                    200: if passive is not supported by the server.
                    201: This option causes
                    202: .Nm
                    203: to always use an active connection.
                    204: It is only useful for connecting to very old servers that do not
                    205: implement passive mode properly.
1.12      lukem     206: .It Fl a
                    207: Causes
                    208: .Nm
                    209: to bypass normal login procedure, and use an anonymous login instead.
                    210: .It Fl d
                    211: Enables debugging.
1.18      lukem     212: .It Fl e
                    213: Disables command line editing.
1.25      lukem     214: This is useful for Emacs ange-ftp mode.
1.31      lukem     215: .It Fl f
                    216: Forces a cache reload for transfers that go through the
1.56      lukem     217: .Tn FTP
1.34      lukem     218: or
1.56      lukem     219: .Tn HTTP
                    220: proxies.
1.12      lukem     221: .It Fl g
                    222: Disables file name globbing.
                    223: .It Fl i
                    224: Turns off interactive prompting during
                    225: multiple file transfers.
1.1       cgd       226: .It Fl n
                    227: Restrains
1.12      lukem     228: .Nm
1.16      lukem     229: from attempting
                    230: .Dq auto-login
                    231: upon initial connection.
1.1       cgd       232: If auto-login is enabled,
1.12      lukem     233: .Nm
1.1       cgd       234: will check the
                    235: .Pa .netrc
                    236: (see below) file in the user's home directory for an entry describing
                    237: an account on the remote machine.
                    238: If no entry exists,
1.12      lukem     239: .Nm
1.1       cgd       240: will prompt for the remote machine login name (default is the user
                    241: identity on the local machine), and, if necessary, prompt for a password
                    242: and an account with which to login.
1.74      lukem     243: .It Fl N Ar netrc
                    244: Use
                    245: .Ar netrc
                    246: instead of
                    247: .Pa ~/.netrc .
                    248: Refer to
                    249: .Sx THE .netrc FILE
                    250: for more information.
1.25      lukem     251: .It Fl o Ar output
                    252: When auto-fetching files, save the contents in
                    253: .Ar output .
                    254: .Ar output
                    255: is parsed according to the
                    256: .Sx FILE NAMING CONVENTIONS
                    257: below.
                    258: If
                    259: .Ar output
                    260: is not
                    261: .Sq -
                    262: or doesn't start with
                    263: .Sq \&| ,
                    264: then only the first file specified will be retrieved into
                    265: .Ar output ;
1.27      lukem     266: all other files will be retrieved into the basename of their
1.25      lukem     267: remote name.
1.12      lukem     268: .It Fl p
                    269: Enable passive mode operation for use behind connection filtering firewalls.
1.25      lukem     270: This option has been deprecated as
                    271: .Nm
                    272: now tries to use passive mode by default, falling back to active mode
                    273: if the server does not support passive connections.
1.12      lukem     274: .It Fl P Ar port
                    275: Sets the port number to
                    276: .Ar port .
1.25      lukem     277: .It Fl r Ar wait
                    278: Retry the connection attempt if it failed, pausing for
                    279: .Ar wait
1.86      christos  280: seconds.
                    281: .It Fl q Ar quittime
                    282: Quit if the connection has stalled for
                    283: .Ar quittime
1.25      lukem     284: seconds.
1.36      lukem     285: .It Fl R
1.57      lukem     286: Restart all non-proxied auto-fetches.
1.12      lukem     287: .It Fl t
                    288: Enables packet tracing.
1.42      lukem     289: .It Xo
                    290: .Fl T
                    291: .Sm off
                    292: .Ar direction ,
                    293: .Ar maximum
                    294: .Op , Ar increment
                    295: .Sm on
                    296: .Xc
                    297: Set the maximum transfer rate for
                    298: .Ar direction
                    299: to
1.56      lukem     300: .Ar maximum
1.49      lukem     301: bytes/second,
1.42      lukem     302: and if specified, the increment to
1.56      lukem     303: .Ar increment
1.49      lukem     304: bytes/second.
1.42      lukem     305: Refer to
                    306: .Ic rate
                    307: for more information.
1.67      lukem     308: .It Fl u Ar url file Op \&.\&.\&.
                    309: Upload files on the command line to
                    310: .Ar url
                    311: where
                    312: .Ar url
                    313: is one of the ftp URL types as supported by auto-fetch
                    314: (with an optional target filename for single file uploads), and
                    315: .Ar file
                    316: is one or more local files to be uploaded.
1.12      lukem     317: .It Fl v
1.32      lukem     318: Enable
                    319: .Ic verbose
                    320: and
                    321: .Ic progress .
                    322: This is the default if output is to a terminal (and in the case of
                    323: .Ic progress ,
                    324: .Nm
                    325: is the foreground process).
1.17      lukem     326: Forces
1.12      lukem     327: .Nm
                    328: to show all responses from the remote server, as well
                    329: as report on data transfer statistics.
1.17      lukem     330: .It Fl V
1.32      lukem     331: Disable
                    332: .Ic verbose
                    333: and
                    334: .Ic progress ,
                    335: overriding the default of enabled when output is to a terminal.
1.1       cgd       336: .El
                    337: .Pp
                    338: The client host with which
1.12      lukem     339: .Nm
1.1       cgd       340: is to communicate may be specified on the command line.
                    341: If this is done,
1.12      lukem     342: .Nm
1.1       cgd       343: will immediately attempt to establish a connection to an
                    344: .Tn FTP
                    345: server on that host; otherwise,
1.12      lukem     346: .Nm
1.1       cgd       347: will enter its command interpreter and await instructions
                    348: from the user.
                    349: When
1.12      lukem     350: .Nm
1.1       cgd       351: is awaiting commands from the user the prompt
1.81      ross      352: .Ql ftp\*[Gt]
1.1       cgd       353: is provided to the user.
                    354: The following commands are recognized
                    355: by
                    356: .Nm ftp  :
                    357: .Bl -tag -width Fl
                    358: .It Ic \&! Op Ar command Op Ar args
                    359: Invoke an interactive shell on the local machine.
                    360: If there are arguments, the first is taken to be a command to execute
                    361: directly, with the rest of the arguments as its arguments.
                    362: .It Ic \&$ Ar macro-name Op Ar args
                    363: Execute the macro
                    364: .Ar macro-name
                    365: that was defined with the
                    366: .Ic macdef
                    367: command.
                    368: Arguments are passed to the macro unglobbed.
                    369: .It Ic account Op Ar passwd
                    370: Supply a supplemental password required by a remote system for access
                    371: to resources once a login has been successfully completed.
                    372: If no argument is included, the user will be prompted for an account
                    373: password in a non-echoing input mode.
                    374: .It Ic append Ar local-file Op Ar remote-file
                    375: Append a local file to a file on the remote machine.
                    376: If
                    377: .Ar remote-file
                    378: is left unspecified, the local file name is used in naming the
                    379: remote file after being altered by any
                    380: .Ic ntrans
                    381: or
                    382: .Ic nmap
                    383: setting.
                    384: File transfer uses the current settings for
                    385: .Ic type  ,
                    386: .Ic format ,
                    387: .Ic mode  ,
                    388: and
                    389: .Ic structure .
                    390: .It Ic ascii
                    391: Set the file transfer
                    392: .Ic type
                    393: to network
                    394: .Tn ASCII .
                    395: This is the default type.
                    396: .It Ic bell
                    397: Arrange that a bell be sounded after each file transfer
                    398: command is completed.
                    399: .It Ic binary
                    400: Set the file transfer
                    401: .Ic type
                    402: to support binary image transfer.
                    403: .It Ic bye
                    404: Terminate the
                    405: .Tn FTP
                    406: session with the remote server
                    407: and exit
1.13      lukem     408: .Nm ftp .
1.1       cgd       409: An end of file will also terminate the session and exit.
                    410: .It Ic case
                    411: Toggle remote computer file name case mapping during
1.74      lukem     412: .Ic get ,
1.1       cgd       413: .Ic mget
1.74      lukem     414: and
                    415: .Ic mput
1.1       cgd       416: commands.
                    417: When
                    418: .Ic case
                    419: is on (default is off), remote computer file names with all letters in
                    420: upper case are written in the local directory with the letters mapped
                    421: to lower case.
                    422: .It Ic \&cd Ar remote-directory
                    423: Change the working directory on the remote machine
                    424: to
1.13      lukem     425: .Ar remote-directory .
1.1       cgd       426: .It Ic cdup
                    427: Change the remote machine working directory to the parent of the
                    428: current remote machine working directory.
1.56      lukem     429: .It Ic chmod Ar mode remote-file
1.1       cgd       430: Change the permission modes of the file
1.56      lukem     431: .Ar remote-file
1.1       cgd       432: on the remote
1.12      lukem     433: system to
1.13      lukem     434: .Ar mode .
1.1       cgd       435: .It Ic close
                    436: Terminate the
                    437: .Tn FTP
                    438: session with the remote server, and
                    439: return to the command interpreter.
                    440: Any defined macros are erased.
                    441: .It Ic \&cr
                    442: Toggle carriage return stripping during
                    443: ascii type file retrieval.
                    444: Records are denoted by a carriage return/linefeed sequence
                    445: during ascii type file transfer.
                    446: When
                    447: .Ic \&cr
                    448: is on (the default), carriage returns are stripped from this
                    449: sequence to conform with the
                    450: .Ux
                    451: single linefeed record
                    452: delimiter.
                    453: Records on
                    454: .Pf non\- Ns Ux
                    455: remote systems may contain single linefeeds;
                    456: when an ascii type transfer is made, these linefeeds may be
                    457: distinguished from a record delimiter only when
                    458: .Ic \&cr
                    459: is off.
                    460: .It Ic debug Op Ar debug-value
                    461: Toggle debugging mode.
                    462: If an optional
                    463: .Ar debug-value
                    464: is specified it is used to set the debugging level.
                    465: When debugging is on,
1.12      lukem     466: .Nm
1.1       cgd       467: prints each command sent to the remote machine, preceded
                    468: by the string
1.81      ross      469: .Ql \-\-\*[Gt]
1.56      lukem     470: .It Ic delete Ar remote-file
                    471: Delete the file
                    472: .Ar remote-file
                    473: on the remote machine.
1.70      lukem     474: .It Ic dir Op Ar remote-path Op Ar local-file
1.15      lukem     475: Print a listing of the contents of a
                    476: directory on the remote machine.
                    477: The listing includes any system-dependent information that the server
                    478: chooses to include; for example, most
                    479: .Ux
                    480: systems will produce
                    481: output from the command
                    482: .Ql ls \-l .
                    483: If
1.70      lukem     484: .Ar remote-path
1.15      lukem     485: is left unspecified, the current working directory is used.
1.1       cgd       486: If interactive prompting is on,
1.12      lukem     487: .Nm
1.1       cgd       488: will prompt the user to verify that the last argument is indeed the
                    489: target local file for receiving
                    490: .Ic dir
                    491: output.
1.15      lukem     492: If no local file is specified, or if
1.1       cgd       493: .Ar local-file
                    494: is
1.15      lukem     495: .Sq Fl ,
                    496: the output is sent to the terminal.
1.1       cgd       497: .It Ic disconnect
                    498: A synonym for
1.13      lukem     499: .Ic close .
1.16      lukem     500: .It Ic edit
                    501: Toggle command line editing, and context sensitive command and file
                    502: completion.
1.17      lukem     503: This is automatically enabled if input is from a terminal, and
1.16      lukem     504: disabled otherwise.
1.45      itojun    505: .It Ic epsv4
1.50      lukem     506: Toggle the use of the extended
1.46      lukem     507: .Dv EPSV
                    508: and
                    509: .Dv EPRT
1.50      lukem     510: commands on IPv4 connections; first try
1.46      lukem     511: .Dv EPSV /
                    512: .Dv EPRT ,
                    513: and then
                    514: .Dv PASV /
1.50      lukem     515: .Dv PORT .
                    516: This is enabled by default.
                    517: If an extended command fails then this option will be temporarily
                    518: disabled for the duration of the current connection, or until
                    519: .Ic epsv4
                    520: is executed again.
1.13      lukem     521: .It Ic exit
                    522: A synonym for
                    523: .Ic bye .
1.70      lukem     524: .It Ic features
                    525: Display what features the remote server supports (using the
                    526: .Dv FEAT
                    527: command).
1.62      lukem     528: .It Ic fget Ar localfile
                    529: Retrieve the files listed in
                    530: .Ar localfile ,
                    531: which has one line per filename.
1.1       cgd       532: .It Ic form Ar format
                    533: Set the file transfer
                    534: .Ic form
                    535: to
1.13      lukem     536: .Ar format .
1.82      lukem     537: The default (and only supported)
                    538: format is
                    539: .Dq non-print .
1.56      lukem     540: .It Ic ftp Ar host Op Ar port
                    541: A synonym for
                    542: .Ic open .
                    543: .It Ic gate Op Ar host Op Ar port
                    544: Toggle gate-ftp mode, which used to connect through the
                    545: TIS FWTK and Gauntlet ftp proxies.
                    546: This will not be permitted if the gate-ftp server hasn't been set
                    547: (either explicitly by the user, or from the
                    548: .Ev FTPSERVER
                    549: environment variable).
                    550: If
                    551: .Ar host
                    552: is given,
                    553: then gate-ftp mode will be enabled, and the gate-ftp server will be set to
                    554: .Ar host .
                    555: If
                    556: .Ar port
                    557: is also given, that will be used as the port to connect to on the
                    558: gate-ftp server.
1.1       cgd       559: .It Ic get Ar remote-file Op Ar local-file
                    560: Retrieve the
                    561: .Ar remote-file
                    562: and store it on the local machine.
                    563: If the local
                    564: file name is not specified, it is given the same
                    565: name it has on the remote machine, subject to
                    566: alteration by the current
                    567: .Ic case  ,
                    568: .Ic ntrans ,
                    569: and
                    570: .Ic nmap
                    571: settings.
                    572: The current settings for
                    573: .Ic type  ,
                    574: .Ic form ,
                    575: .Ic mode  ,
                    576: and
                    577: .Ic structure
                    578: are used while transferring the file.
                    579: .It Ic glob
                    580: Toggle filename expansion for
                    581: .Ic mdelete  ,
1.74      lukem     582: .Ic mget ,
                    583: .Ic mput ,
1.1       cgd       584: and
1.74      lukem     585: .Ic mreget .
1.1       cgd       586: If globbing is turned off with
                    587: .Ic glob  ,
                    588: the file name arguments
                    589: are taken literally and not expanded.
                    590: Globbing for
                    591: .Ic mput
                    592: is done as in
                    593: .Xr csh 1 .
                    594: For
1.74      lukem     595: .Ic mdelete ,
                    596: .Ic mget ,
1.1       cgd       597: and
1.74      lukem     598: .Ic mreget ,
1.1       cgd       599: each remote file name is expanded
                    600: separately on the remote machine and the lists are not merged.
                    601: Expansion of a directory name is likely to be
                    602: different from expansion of the name of an ordinary file:
                    603: the exact result depends on the foreign operating system and ftp server,
                    604: and can be previewed by doing
                    605: .Ql mls remote-files \-
                    606: Note:
1.74      lukem     607: .Ic mget ,
                    608: .Ic mput
1.1       cgd       609: and
1.74      lukem     610: .Ic mreget
1.1       cgd       611: are not meant to transfer
                    612: entire directory subtrees of files.
                    613: That can be done by
                    614: transferring a
                    615: .Xr tar 1
                    616: archive of the subtree (in binary mode).
1.12      lukem     617: .It Ic hash Op Ar size
1.1       cgd       618: Toggle hash-sign (``#'') printing for each data block
                    619: transferred.
1.12      lukem     620: The size of a data block defaults to 1024 bytes.
                    621: This can be changed by specifying
                    622: .Ar size
                    623: in bytes.
1.30      lukem     624: Enabling
                    625: .Ic hash
                    626: disables
                    627: .Ic progress .
1.1       cgd       628: .It Ic help Op Ar command
                    629: Print an informative message about the meaning of
1.13      lukem     630: .Ar command .
1.1       cgd       631: If no argument is given,
1.12      lukem     632: .Nm
1.1       cgd       633: prints a list of the known commands.
                    634: .It Ic idle Op Ar seconds
                    635: Set the inactivity timer on the remote server to
                    636: .Ar seconds
                    637: seconds.
                    638: If
                    639: .Ar seconds
1.4       jtc       640: is omitted, the current inactivity timer is printed.
1.56      lukem     641: .It Ic image
                    642: A synonym for
                    643: .Ic binary .
1.1       cgd       644: .It Ic lcd Op Ar directory
                    645: Change the working directory on the local machine.
                    646: If
                    647: no
                    648: .Ar directory
                    649: is specified, the user's home directory is used.
1.19      lukem     650: .It Ic less Ar file
                    651: A synonym for
                    652: .Ic page .
1.56      lukem     653: .It Ic lpage Ar local-file
                    654: Display
                    655: .Ar local-file
                    656: with the program specified by the
                    657: .Ic "set pager"
                    658: option.
1.13      lukem     659: .It Ic lpwd
                    660: Print the working directory on the local machine.
1.70      lukem     661: .It Ic \&ls Op Ar remote-path Op Ar local-file
1.64      lukem     662: A synonym for
                    663: .Ic dir .
1.7       cgd       664: .It Ic macdef Ar macro-name
1.1       cgd       665: Define a macro.
                    666: Subsequent lines are stored as the macro
                    667: .Ar macro-name  ;
                    668: a null line (consecutive newline characters
                    669: in a file or
                    670: carriage returns from the terminal) terminates macro input mode.
                    671: There is a limit of 16 macros and 4096 total characters in all
                    672: defined macros.
                    673: Macros remain defined until a
                    674: .Ic close
                    675: command is executed.
                    676: The macro processor interprets `$' and `\e' as special characters.
                    677: A `$' followed by a number (or numbers) is replaced by the
                    678: corresponding argument on the macro invocation command line.
                    679: A `$' followed by an `i' signals that macro processor that the
                    680: executing macro is to be looped.
                    681: On the first pass `$i' is
                    682: replaced by the first argument on the macro invocation command line,
                    683: on the second pass it is replaced by the second argument, and so on.
                    684: A `\e' followed by any character is replaced by that character.
                    685: Use the `\e' to prevent special treatment of the `$'.
                    686: .It Ic mdelete Op Ar remote-files
                    687: Delete the
                    688: .Ar remote-files
                    689: on the remote machine.
                    690: .It Ic mdir Ar remote-files local-file
                    691: Like
                    692: .Ic dir  ,
                    693: except multiple remote files may be specified.
                    694: If interactive prompting is on,
1.12      lukem     695: .Nm
1.1       cgd       696: will prompt the user to verify that the last argument is indeed the
                    697: target local file for receiving
                    698: .Ic mdir
                    699: output.
                    700: .It Ic mget Ar remote-files
                    701: Expand the
                    702: .Ar remote-files
                    703: on the remote machine
                    704: and do a
                    705: .Ic get
                    706: for each file name thus produced.
                    707: See
                    708: .Ic glob
                    709: for details on the filename expansion.
                    710: Resulting file names will then be processed according to
                    711: .Ic case  ,
                    712: .Ic ntrans ,
                    713: and
                    714: .Ic nmap
                    715: settings.
                    716: Files are transferred into the local working directory,
                    717: which can be changed with
                    718: .Ql lcd directory ;
                    719: new local directories can be created with
                    720: .Ql "\&! mkdir directory" .
                    721: .It Ic mkdir Ar directory-name
                    722: Make a directory on the remote machine.
                    723: .It Ic mls Ar remote-files local-file
                    724: Like
1.15      lukem     725: .Ic ls  ,
1.1       cgd       726: except multiple remote files may be specified,
                    727: and the
                    728: .Ar local-file
                    729: must be specified.
                    730: If interactive prompting is on,
1.12      lukem     731: .Nm
1.1       cgd       732: will prompt the user to verify that the last argument is indeed the
                    733: target local file for receiving
                    734: .Ic mls
                    735: output.
1.70      lukem     736: .It Ic mlsd Op Ar remote-path
                    737: Display the contents of
                    738: .Ar remote-path
                    739: (which should default to the current directory if not given)
                    740: in a machine-parsable form, using
                    741: .Dv MLSD .
                    742: The format of display can be changed with
1.72      lukem     743: .Sq "remopts mlst ..." .
1.70      lukem     744: .It Ic mlst Op Ar remote-path
                    745: Display the details about
                    746: .Ar remote-path
                    747: (which should default to the current directory if not given)
                    748: in a machine-parsable form, using
                    749: .Dv MLST .
                    750: The format of display can be changed with
1.72      lukem     751: .Sq "remopts mlst ..." .
1.56      lukem     752: .It Ic mode Ar mode-name
1.1       cgd       753: Set the file transfer
                    754: .Ic mode
                    755: to
1.13      lukem     756: .Ar mode-name .
1.82      lukem     757: The default (and only supported)
                    758: mode is
                    759: .Dq stream .
1.56      lukem     760: .It Ic modtime Ar remote-file
1.1       cgd       761: Show the last modification time of the file on the remote machine.
1.19      lukem     762: .It Ic more Ar file
                    763: A synonym for
                    764: .Ic page .
1.1       cgd       765: .It Ic mput Ar local-files
                    766: Expand wild cards in the list of local files given as arguments
                    767: and do a
                    768: .Ic put
                    769: for each file in the resulting list.
                    770: See
                    771: .Ic glob
                    772: for details of filename expansion.
                    773: Resulting file names will then be processed according to
                    774: .Ic ntrans
                    775: and
                    776: .Ic nmap
                    777: settings.
1.74      lukem     778: .It Ic mreget Ar remote-files
                    779: As per
                    780: .Ic mget ,
                    781: but performs a
                    782: .Ic reget
                    783: instead of
                    784: .Ic get .
1.13      lukem     785: .It Ic msend Ar local-files
                    786: A synonym for
                    787: .Ic mput .
1.56      lukem     788: .It Ic newer Ar remote-file Op Ar local-file
1.1       cgd       789: Get the file only if the modification time of the remote file is more
                    790: recent that the file on the current system.
                    791: If the file does not
                    792: exist on the current system, the remote file is considered
1.13      lukem     793: .Ic newer .
1.1       cgd       794: Otherwise, this command is identical to
1.13      lukem     795: .Ar get .
1.70      lukem     796: .It Ic nlist Op Ar remote-path Op Ar local-file
1.15      lukem     797: A synonym for
                    798: .Ic ls .
1.1       cgd       799: .It Ic nmap Op Ar inpattern outpattern
                    800: Set or unset the filename mapping mechanism.
                    801: If no arguments are specified, the filename mapping mechanism is unset.
                    802: If arguments are specified, remote filenames are mapped during
                    803: .Ic mput
                    804: commands and
                    805: .Ic put
                    806: commands issued without a specified remote target filename.
                    807: If arguments are specified, local filenames are mapped during
                    808: .Ic mget
                    809: commands and
                    810: .Ic get
                    811: commands issued without a specified local target filename.
                    812: This command is useful when connecting to a
                    813: .No non\- Ns Ux
                    814: remote computer
                    815: with different file naming conventions or practices.
                    816: The mapping follows the pattern set by
                    817: .Ar inpattern
                    818: and
1.13      lukem     819: .Ar outpattern .
1.1       cgd       820: .Op Ar Inpattern
                    821: is a template for incoming filenames (which may have already been
                    822: processed according to the
                    823: .Ic ntrans
                    824: and
                    825: .Ic case
                    826: settings).
                    827: Variable templating is accomplished by including the
                    828: sequences `$1', `$2', ..., `$9' in
1.13      lukem     829: .Ar inpattern .
1.1       cgd       830: Use `\\' to prevent this special treatment of the `$' character.
                    831: All other characters are treated literally, and are used to determine the
                    832: .Ic nmap
                    833: .Op Ar inpattern
                    834: variable values.
                    835: For example, given
                    836: .Ar inpattern
                    837: $1.$2 and the remote file name "mydata.data", $1 would have the value
                    838: "mydata", and $2 would have the value "data".
                    839: The
                    840: .Ar outpattern
                    841: determines the resulting mapped filename.
                    842: The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
                    843: from the
                    844: .Ar inpattern
                    845: template.
                    846: The sequence `$0' is replace by the original filename.
                    847: Additionally, the sequence
                    848: .Ql Op Ar seq1 , Ar seq2
                    849: is replaced by
                    850: .Op Ar seq1
                    851: if
                    852: .Ar seq1
                    853: is not a null string; otherwise it is replaced by
                    854: .Ar seq2 .
                    855: For example, the command
                    856: .Pp
                    857: .Bd -literal -offset indent -compact
                    858: nmap $1.$2.$3 [$1,$2].[$2,file]
                    859: .Ed
                    860: .Pp
                    861: would yield
                    862: the output filename "myfile.data" for input filenames "myfile.data" and
                    863: "myfile.data.old", "myfile.file" for the input filename "myfile", and
                    864: "myfile.myfile" for the input filename ".myfile".
                    865: Spaces may be included in
                    866: .Ar outpattern  ,
1.81      ross      867: as in the example: `nmap $1 sed "s/  *$//" \*[Gt] $1' .
1.1       cgd       868: Use the `\e' character to prevent special treatment
1.24      msaitoh   869: of the `$','[',']', and `,' characters.
1.1       cgd       870: .It Ic ntrans Op Ar inchars Op Ar outchars
                    871: Set or unset the filename character translation mechanism.
                    872: If no arguments are specified, the filename character
                    873: translation mechanism is unset.
                    874: If arguments are specified, characters in
                    875: remote filenames are translated during
                    876: .Ic mput
                    877: commands and
                    878: .Ic put
                    879: commands issued without a specified remote target filename.
                    880: If arguments are specified, characters in
                    881: local filenames are translated during
                    882: .Ic mget
                    883: commands and
                    884: .Ic get
                    885: commands issued without a specified local target filename.
                    886: This command is useful when connecting to a
                    887: .No non\- Ns Ux
                    888: remote computer
                    889: with different file naming conventions or practices.
                    890: Characters in a filename matching a character in
                    891: .Ar inchars
                    892: are replaced with the corresponding character in
1.13      lukem     893: .Ar outchars .
1.1       cgd       894: If the character's position in
                    895: .Ar inchars
                    896: is longer than the length of
                    897: .Ar outchars  ,
                    898: the character is deleted from the file name.
                    899: .It Ic open Ar host Op Ar port
                    900: Establish a connection to the specified
                    901: .Ar host
                    902: .Tn FTP
                    903: server.
                    904: An optional port number may be supplied,
                    905: in which case,
1.12      lukem     906: .Nm
1.1       cgd       907: will attempt to contact an
                    908: .Tn FTP
                    909: server at that port.
                    910: If the
1.85      lukem     911: .Ic "set auto-login"
1.1       cgd       912: option is on (default),
1.12      lukem     913: .Nm
1.1       cgd       914: will also attempt to automatically log the user in to
                    915: the
                    916: .Tn FTP
                    917: server (see below).
1.18      lukem     918: .It Ic page Ar file
                    919: Retrieve
                    920: .Ic file
1.56      lukem     921: and display with the program specified by the
                    922: .Ic "set pager"
                    923: option.
1.85      lukem     924: .It Ic passive Op Cm auto
1.56      lukem     925: Toggle passive mode (if no arguments are given).
                    926: If
1.85      lukem     927: .Cm auto
1.56      lukem     928: is given, act as if
                    929: .Ev FTPMODE
                    930: is set to
                    931: .Sq auto .
                    932: If passive mode is turned on (default),
                    933: .Nm
                    934: will send a
1.8       cgd       935: .Dv PASV
1.56      lukem     936: command for all data connections instead of a
1.8       cgd       937: .Dv PORT
1.87      grant     938: command.
                    939: The
1.8       cgd       940: .Dv PASV
                    941: command requests that the remote server open a port for the data connection
1.87      grant     942: and return the address of that port.
                    943: The remote server listens on that port and the client connects to it.
                    944: When using the more traditional
1.8       cgd       945: .Dv PORT
                    946: command, the client listens on a port and sends that address to the remote
1.87      grant     947: server, who connects back to it.
                    948: Passive mode is useful when using
1.12      lukem     949: .Nm
1.8       cgd       950: through a gateway router or host that controls the directionality of
                    951: traffic.
1.56      lukem     952: (Note that though
                    953: .Tn FTP
                    954: servers are required to support the
1.8       cgd       955: .Dv PASV
                    956: command by RFC 1123, some do not.)
1.70      lukem     957: .It Ic pdir Op Ar remote-path
1.48      lukem     958: Perform
                    959: .Ic dir
1.70      lukem     960: .Op Ar remote-path ,
1.64      lukem     961: and display the result with the program specified by the
1.56      lukem     962: .Ic "set pager"
                    963: option.
1.70      lukem     964: .It Ic pls Op Ar remote-path
1.48      lukem     965: Perform
                    966: .Ic ls
1.70      lukem     967: .Op Ar remote-path ,
                    968: and display the result with the program specified by the
                    969: .Ic "set pager"
                    970: option.
                    971: .It Ic pmlsd Op Ar remote-path
                    972: Perform
                    973: .Ic mlsd
                    974: .Op Ar remote-path ,
1.64      lukem     975: and display the result with the program specified by the
1.56      lukem     976: .Ic "set pager"
                    977: option.
1.13      lukem     978: .It Ic preserve
1.14      lukem     979: Toggle preservation of modification times on retrieved files.
                    980: .It Ic progress
                    981: Toggle display of transfer progress bar.
1.18      lukem     982: The progress bar will be disabled for a transfer that has
                    983: .Ar local-file
                    984: as
                    985: .Sq Fl
                    986: or a command that starts with
                    987: .Sq \&| .
                    988: Refer to
                    989: .Sx FILE NAMING CONVENTIONS
                    990: for more information.
1.30      lukem     991: Enabling
                    992: .Ic progress
                    993: disables
                    994: .Ic hash .
1.1       cgd       995: .It Ic prompt
                    996: Toggle interactive prompting.
                    997: Interactive prompting
                    998: occurs during multiple file transfers to allow the
                    999: user to selectively retrieve or store files.
                   1000: If prompting is turned off (default is on), any
                   1001: .Ic mget
                   1002: or
                   1003: .Ic mput
                   1004: will transfer all files, and any
                   1005: .Ic mdelete
                   1006: will delete all files.
1.13      lukem    1007: .Pp
                   1008: When prompting is on, the following commands are available at a prompt:
1.16      lukem    1009: .Bl -tag -width 2n -offset indent
1.85      lukem    1010: .It Cm a
1.13      lukem    1011: Answer
                   1012: .Sq yes
                   1013: to the current file, and automatically answer
                   1014: .Sq yes
                   1015: to any remaining files for the current command.
1.85      lukem    1016: .It Cm n
1.54      lukem    1017: Answer
                   1018: .Sq no ,
                   1019: and do not transfer the file.
1.85      lukem    1020: .It Cm p
1.13      lukem    1021: Answer
1.14      lukem    1022: .Sq yes
1.13      lukem    1023: to the current file, and turn off prompt mode
                   1024: (as is
                   1025: .Dq prompt off
                   1026: had been given).
1.85      lukem    1027: .It Cm q
1.54      lukem    1028: Terminate the current operation.
1.85      lukem    1029: .It Cm y
1.54      lukem    1030: Answer
                   1031: .Sq yes ,
                   1032: and transfer the file.
1.85      lukem    1033: .It Cm ?
1.54      lukem    1034: Display a help message.
1.13      lukem    1035: .El
                   1036: .Pp
1.88      wiz      1037: Any other response will answer
1.13      lukem    1038: .Sq yes
                   1039: to the current file.
1.1       cgd      1040: .It Ic proxy Ar ftp-command
                   1041: Execute an ftp command on a secondary control connection.
1.56      lukem    1042: This command allows simultaneous connection to two remote
                   1043: .Tn FTP
1.1       cgd      1044: servers for transferring files between the two servers.
                   1045: The first
                   1046: .Ic proxy
                   1047: command should be an
                   1048: .Ic open  ,
                   1049: to establish the secondary control connection.
1.56      lukem    1050: Enter the command "proxy ?" to see other
                   1051: .Tn FTP
                   1052: commands executable on the secondary connection.
1.1       cgd      1053: The following commands behave differently when prefaced by
                   1054: .Ic proxy  :
                   1055: .Ic open
                   1056: will not define new macros during the auto-login process,
                   1057: .Ic close
                   1058: will not erase existing macro definitions,
                   1059: .Ic get
                   1060: and
                   1061: .Ic mget
                   1062: transfer files from the host on the primary control connection
                   1063: to the host on the secondary control connection, and
                   1064: .Ic put  ,
                   1065: .Ic mput ,
                   1066: and
                   1067: .Ic append
                   1068: transfer files from the host on the secondary control connection
                   1069: to the host on the primary control connection.
1.56      lukem    1070: Third party file transfers depend upon support of the
                   1071: .Tn FTP
                   1072: protocol
1.1       cgd      1073: .Dv PASV
                   1074: command by the server on the secondary control connection.
                   1075: .It Ic put Ar local-file Op Ar remote-file
                   1076: Store a local file on the remote machine.
                   1077: If
                   1078: .Ar remote-file
                   1079: is left unspecified, the local file name is used
                   1080: after processing according to any
                   1081: .Ic ntrans
                   1082: or
                   1083: .Ic nmap
                   1084: settings
                   1085: in naming the remote file.
                   1086: File transfer uses the
                   1087: current settings for
                   1088: .Ic type  ,
                   1089: .Ic format ,
                   1090: .Ic mode  ,
                   1091: and
1.13      lukem    1092: .Ic structure .
1.1       cgd      1093: .It Ic pwd
                   1094: Print the name of the current working directory on the remote
                   1095: machine.
                   1096: .It Ic quit
                   1097: A synonym for
1.13      lukem    1098: .Ic bye .
1.1       cgd      1099: .It Ic quote Ar arg1 arg2 ...
                   1100: The arguments specified are sent, verbatim, to the remote
                   1101: .Tn FTP
                   1102: server.
1.42      lukem    1103: .It Xo
                   1104: .Ic rate Ar direction
                   1105: .Op Ar maximum Op Ar increment
                   1106: .Xc
                   1107: Throttle the maximum transfer rate to
                   1108: .Ar maximum
                   1109: bytes/second.
                   1110: If
                   1111: .Ar maximum
                   1112: is 0, disable the throttle.
                   1113: .Pp
                   1114: .Ar direction
                   1115: may be one of:
                   1116: .Bl -tag -width "all" -offset indent -compact
1.85      lukem    1117: .It Cm all
1.42      lukem    1118: Both directions.
1.85      lukem    1119: .It Cm get
1.42      lukem    1120: Incoming transfers.
1.85      lukem    1121: .It Cm put
1.42      lukem    1122: Outgoing transfers.
                   1123: .El
                   1124: .Pp
                   1125: .Ar maximum
                   1126: can by modified on the fly by
                   1127: .Ar increment
                   1128: bytes (default: 1024) each time a given signal is received:
                   1129: .B
                   1130: .Bl -tag -width "SIGUSR1" -offset indent
                   1131: .It Dv SIGUSR1
                   1132: Increment
                   1133: .Ar maximum
                   1134: by
                   1135: .Ar increment
                   1136: bytes.
                   1137: .It Dv SIGUSR2
                   1138: Decrement
                   1139: .Ar maximum
                   1140: by
                   1141: .Ar increment
                   1142: bytes.
                   1143: The result must be a positive number.
                   1144: .El
                   1145: .Pp
                   1146: If
                   1147: .Ar maximum
                   1148: is not supplied, the current throttle rates are displayed.
                   1149: .Pp
                   1150: Note:
                   1151: .Ic rate
                   1152: is not yet implemented for ascii mode transfers.
1.47      lukem    1153: .It Ic rcvbuf Ar size
                   1154: Set the size of the socket receive buffer to
                   1155: .Ar size .
1.1       cgd      1156: .It Ic recv Ar remote-file Op Ar local-file
1.13      lukem    1157: A synonym for
                   1158: .Ic get .
1.1       cgd      1159: .It Ic reget Ar remote-file Op Ar local-file
1.42      lukem    1160: .Ic reget
                   1161: acts like
                   1162: .Ic get ,
                   1163: except that if
1.1       cgd      1164: .Ar local-file
                   1165: exists and is
                   1166: smaller than
                   1167: .Ar remote-file  ,
                   1168: .Ar local-file
                   1169: is presumed to be
                   1170: a partially transferred copy of
                   1171: .Ar remote-file
                   1172: and the transfer
                   1173: is continued from the apparent point of failure.
                   1174: This command
                   1175: is useful when transferring very large files over networks that
                   1176: are prone to dropping connections.
1.72      lukem    1177: .It Ic remopts Ar command Op Ar command-options
                   1178: Set options on the remote
                   1179: .Tn FTP
                   1180: server for
                   1181: .Ar command
                   1182: to
                   1183: .Ar command-options
                   1184: (whose absence is handled on a command-specific basis).
                   1185: Remote
                   1186: .Tn FTP
                   1187: commands known to support options include:
                   1188: .Sq MLST
                   1189: (used for
                   1190: .Dv MLSD
1.77      wiz      1191: and
1.72      lukem    1192: .Dv MLST ) .
1.15      lukem    1193: .It Ic rename Op Ar from Op Ar to
1.1       cgd      1194: Rename the file
                   1195: .Ar from
                   1196: on the remote machine, to the file
1.13      lukem    1197: .Ar to .
1.1       cgd      1198: .It Ic reset
                   1199: Clear reply queue.
                   1200: This command re-synchronizes command/reply sequencing with the remote
1.56      lukem    1201: .Tn FTP
                   1202: server.
                   1203: Resynchronization may be necessary following a violation of the
                   1204: .Tn FTP
                   1205: protocol by the remote server.
1.1       cgd      1206: .It Ic restart Ar marker
                   1207: Restart the immediately following
                   1208: .Ic get
                   1209: or
                   1210: .Ic put
                   1211: at the
                   1212: indicated
1.13      lukem    1213: .Ar marker .
1.1       cgd      1214: On
                   1215: .Ux
                   1216: systems, marker is usually a byte
                   1217: offset into the file.
1.56      lukem    1218: .It Ic rhelp Op Ar command-name
                   1219: Request help from the remote
                   1220: .Tn FTP
                   1221: server.
                   1222: If a
                   1223: .Ar command-name
                   1224: is specified it is supplied to the server as well.
1.1       cgd      1225: .It Ic rmdir Ar directory-name
                   1226: Delete a directory on the remote machine.
1.56      lukem    1227: .It Ic rstatus Op Ar remote-file
                   1228: With no arguments, show status of remote machine.
                   1229: If
                   1230: .Ar remote-file
                   1231: is specified, show status of
                   1232: .Ar remote-file
                   1233: on remote machine.
1.1       cgd      1234: .It Ic runique
                   1235: Toggle storing of files on the local system with unique filenames.
                   1236: If a file already exists with a name equal to the target
                   1237: local filename for a
                   1238: .Ic get
                   1239: or
                   1240: .Ic mget
                   1241: command, a ".1" is appended to the name.
                   1242: If the resulting name matches another existing file,
                   1243: a ".2" is appended to the original name.
                   1244: If this process continues up to ".99", an error
                   1245: message is printed, and the transfer does not take place.
                   1246: The generated unique filename will be reported.
                   1247: Note that
                   1248: .Ic runique
                   1249: will not affect local files generated from a shell command
                   1250: (see below).
                   1251: The default value is off.
                   1252: .It Ic send Ar local-file Op Ar remote-file
1.13      lukem    1253: A synonym for
                   1254: .Ic put .
1.1       cgd      1255: .It Ic sendport
                   1256: Toggle the use of
                   1257: .Dv PORT
                   1258: commands.
                   1259: By default,
1.12      lukem    1260: .Nm
1.1       cgd      1261: will attempt to use a
                   1262: .Dv PORT
                   1263: command when establishing
                   1264: a connection for each data transfer.
                   1265: The use of
                   1266: .Dv PORT
                   1267: commands can prevent delays
                   1268: when performing multiple file transfers.
                   1269: If the
                   1270: .Dv PORT
                   1271: command fails,
1.12      lukem    1272: .Nm
1.1       cgd      1273: will use the default data port.
                   1274: When the use of
                   1275: .Dv PORT
                   1276: commands is disabled, no attempt will be made to use
                   1277: .Dv PORT
                   1278: commands for each data transfer.
                   1279: This is useful
                   1280: for certain
                   1281: .Tn FTP
                   1282: implementations which do ignore
                   1283: .Dv PORT
                   1284: commands but, incorrectly, indicate they've been accepted.
1.85      lukem    1285: .It Ic set Op Ar option Ar value
1.56      lukem    1286: Set
                   1287: .Ar option
                   1288: to
                   1289: .Ar value .
                   1290: If
                   1291: .Ar option
                   1292: and
                   1293: .Ar value
                   1294: are not given, display all of the options and their values.
                   1295: The currently supported options are:
                   1296: .Bl -tag -width "http_proxy" -offset indent
1.85      lukem    1297: .It Cm anonpass
1.56      lukem    1298: Defaults to
                   1299: .Ev $FTPANONPASS
1.85      lukem    1300: .It Cm ftp_proxy
1.56      lukem    1301: Defaults to
                   1302: .Ev $ftp_proxy .
1.85      lukem    1303: .It Cm http_proxy
1.56      lukem    1304: Defaults to
                   1305: .Ev $http_proxy .
1.85      lukem    1306: .It Cm no_proxy
1.56      lukem    1307: Defaults to
                   1308: .Ev $no_proxy .
1.85      lukem    1309: .It Cm pager
1.56      lukem    1310: Defaults to
                   1311: .Ev $PAGER .
1.85      lukem    1312: .It Cm prompt
1.58      lukem    1313: Defaults to
1.59      lukem    1314: .Ev $FTPPROMPT .
1.85      lukem    1315: .It Cm rprompt
1.59      lukem    1316: Defaults to
                   1317: .Ev $FTPRPROMPT .
1.56      lukem    1318: .El
1.76      lukem    1319: .It Ic site Ar arg1 arg2 ...
                   1320: The arguments specified are sent, verbatim, to the remote
                   1321: .Tn FTP
                   1322: server as a
                   1323: .Dv SITE
                   1324: command.
1.56      lukem    1325: .It Ic size Ar remote-file
                   1326: Return size of
                   1327: .Ar remote-file
                   1328: on remote machine.
1.47      lukem    1329: .It Ic sndbuf Ar size
                   1330: Set the size of the socket send buffer to
                   1331: .Ar size .
1.1       cgd      1332: .It Ic status
                   1333: Show the current status of
1.13      lukem    1334: .Nm ftp .
1.56      lukem    1335: .It Ic struct Ar struct-name
1.1       cgd      1336: Set the file transfer
                   1337: .Ar structure
                   1338: to
                   1339: .Ar struct-name .
1.82      lukem    1340: The default (and only supported)
                   1341: structure is
                   1342: .Dq file .
1.1       cgd      1343: .It Ic sunique
                   1344: Toggle storing of files on remote machine under unique file names.
1.56      lukem    1345: The remote
                   1346: .Tn FTP
                   1347: server must support
                   1348: .Tn FTP
                   1349: protocol
1.1       cgd      1350: .Dv STOU
                   1351: command for
                   1352: successful completion.
                   1353: The remote server will report unique name.
                   1354: Default value is off.
                   1355: .It Ic system
                   1356: Show the type of operating system running on the remote machine.
                   1357: .It Ic tenex
                   1358: Set the file transfer type to that needed to
                   1359: talk to
                   1360: .Tn TENEX
                   1361: machines.
1.42      lukem    1362: .It Ic throttle
                   1363: A synonym for
                   1364: .Ic rate .
1.1       cgd      1365: .It Ic trace
                   1366: Toggle packet tracing.
                   1367: .It Ic type Op Ar type-name
                   1368: Set the file transfer
                   1369: .Ic type
                   1370: to
1.13      lukem    1371: .Ar type-name .
1.1       cgd      1372: If no type is specified, the current type
                   1373: is printed.
                   1374: The default type is network
                   1375: .Tn ASCII .
                   1376: .It Ic umask Op Ar newmask
                   1377: Set the default umask on the remote server to
1.13      lukem    1378: .Ar newmask .
1.1       cgd      1379: If
                   1380: .Ar newmask
1.6       cgd      1381: is omitted, the current umask is printed.
1.56      lukem    1382: .It Ic unset Ar option
                   1383: Unset
                   1384: .Ar option .
1.59      lukem    1385: Refer to
                   1386: .Ic set
                   1387: for more information.
1.56      lukem    1388: .It Ic usage Ar command
                   1389: Print the usage message for
                   1390: .Ar command .
1.1       cgd      1391: .It Xo
                   1392: .Ic user Ar user-name
1.15      lukem    1393: .Op Ar password Op Ar account
1.1       cgd      1394: .Xc
                   1395: Identify yourself to the remote
                   1396: .Tn FTP
                   1397: server.
                   1398: If the
                   1399: .Ar password
                   1400: is not specified and the server requires it,
1.12      lukem    1401: .Nm
1.1       cgd      1402: will prompt the user for it (after disabling local echo).
                   1403: If an
                   1404: .Ar account
                   1405: field is not specified, and the
                   1406: .Tn FTP
                   1407: server
                   1408: requires it, the user will be prompted for it.
                   1409: If an
                   1410: .Ar account
                   1411: field is specified, an account command will
                   1412: be relayed to the remote server after the login sequence
                   1413: is completed if the remote server did not require it
                   1414: for logging in.
                   1415: Unless
1.12      lukem    1416: .Nm
1.37      lukem    1417: is invoked with
                   1418: .Dq auto-login
                   1419: disabled, this process is done automatically on initial connection to the
1.1       cgd      1420: .Tn FTP
                   1421: server.
                   1422: .It Ic verbose
                   1423: Toggle verbose mode.
                   1424: In verbose mode, all responses from
                   1425: the
                   1426: .Tn FTP
                   1427: server are displayed to the user.
                   1428: In addition,
                   1429: if verbose is on, when a file transfer completes, statistics
                   1430: regarding the efficiency of the transfer are reported.
                   1431: By default,
                   1432: verbose is on.
1.47      lukem    1433: .It Ic xferbuf Ar size
                   1434: Set the size of the socket send and receive buffers to
                   1435: .Ar size .
1.1       cgd      1436: .It Ic ? Op Ar command
1.13      lukem    1437: A synonym for
                   1438: .Ic help .
1.1       cgd      1439: .El
                   1440: .Pp
                   1441: Command arguments which have embedded spaces may be quoted with
                   1442: quote `"' marks.
1.12      lukem    1443: .Pp
1.13      lukem    1444: Commands which toggle settings can take an explicit
                   1445: .Ic on
                   1446: or
                   1447: .Ic off
                   1448: argument to force the setting appropriately.
                   1449: .Pp
1.42      lukem    1450: Commands which take a byte count as an argument
                   1451: (e.g.,
1.47      lukem    1452: .Ic hash ,
                   1453: .Ic rate ,
1.42      lukem    1454: and
1.47      lukem    1455: .Ic xferbuf )
1.42      lukem    1456: support an optional suffix on the argument which changes the
                   1457: interpretation of the argument.
                   1458: Supported suffixes are:
                   1459: .Bl -tag -width 3n -offset indent -compact
1.85      lukem    1460: .It Li b
1.87      grant    1461: Causes no modification.
                   1462: (Optional)
1.85      lukem    1463: .It Li k
1.42      lukem    1464: Kilo; multiply the argument by 1024
1.85      lukem    1465: .It Li m
1.42      lukem    1466: Mega; multiply the argument by 1048576
1.85      lukem    1467: .It Li g
1.42      lukem    1468: Giga; multiply the argument by 1073741824
                   1469: .El
                   1470: .Pp
1.12      lukem    1471: If
                   1472: .Nm
                   1473: receives a
                   1474: .Dv SIGINFO
                   1475: (see the
                   1476: .Dq status
1.16      lukem    1477: argument of
1.12      lukem    1478: .Xr stty 1 )
1.53      lukem    1479: or
                   1480: .Dv SIGQUIT
1.12      lukem    1481: signal whilst a transfer is in progress, the current transfer rate
                   1482: statistics will be written to the standard error output, in the
                   1483: same format as the standard completion message.
1.16      lukem    1484: .Sh AUTO-FETCHING FILES
                   1485: In addition to standard commands, this version of
                   1486: .Nm
                   1487: supports an auto-fetch feature.
                   1488: To enable auto-fetch, simply pass the list of hostnames/files
                   1489: on the command line.
                   1490: .Pp
                   1491: The following formats are valid syntax for an auto-fetch element:
1.34      lukem    1492: .Bl -tag -width "FOO "
1.85      lukem    1493: .\" [user@]host:[path][/]
                   1494: .It Xo
                   1495: .Sm off
                   1496: .Op Ar user Li \&@
                   1497: .Ar host Li \&:
                   1498: .Op Ar path
                   1499: .Op Li /
                   1500: .Sm on
                   1501: .Xc
1.16      lukem    1502: .Dq Classic
1.56      lukem    1503: .Tn FTP
                   1504: format.
1.37      lukem    1505: .Pp
                   1506: If
1.56      lukem    1507: .Ar path
1.37      lukem    1508: contains a glob character and globbing is enabled,
                   1509: (see
                   1510: .Ic glob ) ,
                   1511: then the equivalent of
1.56      lukem    1512: .Ql mget path
1.37      lukem    1513: is performed.
                   1514: .Pp
                   1515: If the directory component of
1.56      lukem    1516: .Ar path
1.37      lukem    1517: contains no globbing characters,
1.51      lukem    1518: it is stored locally with the name basename (see
                   1519: .Xr basename 1 )
1.37      lukem    1520: of
1.56      lukem    1521: .Ic path ,
1.51      lukem    1522: in the current directory.
                   1523: Otherwise, the full remote name is used as the local name,
                   1524: relative to the local root directory.
1.85      lukem    1525: .\" ftp://[user[:password]@]host[:port]/path[/][;type=X]
                   1526: .It Xo
                   1527: .Sm off
                   1528: .Li ftp://
                   1529: .Oo Ar user
                   1530: .Op Li \&: Ar password
                   1531: .Li \&@ Oc
                   1532: .Ar host Oo Li \&: Ar port Oc
                   1533: .Li / Ar path
                   1534: .Op Li /
                   1535: .Op Li ;type= Ar X
                   1536: .Sm on
                   1537: .Xc
1.56      lukem    1538: An
                   1539: .Tn FTP
                   1540: URL, retrieved using the
                   1541: .Tn FTP
                   1542: protocol if
                   1543: .Ic "set ftp_proxy"
1.19      lukem    1544: isn't defined.
1.73      lukem    1545: Otherwise, transfer the URL using
1.56      lukem    1546: .Tn HTTP
                   1547: via the proxy defined in
                   1548: .Ic "set ftp_proxy" .
1.20      lukem    1549: If
1.56      lukem    1550: .Ic "set ftp_proxy"
1.34      lukem    1551: isn't defined and
1.20      lukem    1552: .Ar user
1.34      lukem    1553: is given, login as
                   1554: .Ar user .
                   1555: In this case, use
                   1556: .Ar password
                   1557: if supplied, otherwise prompt the user for one.
                   1558: .Pp
1.85      lukem    1559: If a suffix of
                   1560: .Sq ;type=A
                   1561: or
                   1562: .Sq ;type=I
                   1563: is supplied, then the transfer type will take place as
                   1564: ascii or binary (respectively).
                   1565: The default transfer type is binary.
                   1566: .Pp
1.34      lukem    1567: In order to be compliant with
                   1568: .Cm RFC 1738 ,
                   1569: .Nm
1.85      lukem    1570: interprets the
                   1571: .Ar path
                   1572: part of an
1.84      lukem    1573: .Dq ftp://
1.85      lukem    1574: auto-fetch URL as follows:
1.84      lukem    1575: .Bl -bullet
                   1576: .It
1.85      lukem    1577: The
                   1578: .Sq Li /
                   1579: immediately after the
                   1580: .Ar host Ns Oo Li \&: Ns Ar port Oc
                   1581: is interpreted as a separator before the
                   1582: .Ar path ,
                   1583: and not as part of the
                   1584: .Ar path
                   1585: itself.
                   1586: .It
                   1587: The
                   1588: .Ar path
                   1589: is interpreted as a
                   1590: .So Li / Sc Ns -separated
                   1591: list of name components.
                   1592: For all but the last such component,
                   1593: .Nm
                   1594: performs the equivalent of a
                   1595: .Ic cd
                   1596: command.
                   1597: For the last path component,
                   1598: .Nm
                   1599: performs the equivalent of a
                   1600: .Ic get
                   1601: command.
                   1602: .It
                   1603: Empty name components,
                   1604: which result from
                   1605: .Sq Li //
                   1606: within the
                   1607: .Ar path ,
                   1608: or from an extra
                   1609: .Sq Li /
                   1610: at the beginning of the
1.34      lukem    1611: .Ar path ,
1.85      lukem    1612: will cause the equivalent of a
                   1613: .Ic cd
                   1614: command without a directory name.
                   1615: This is unlikely to be useful.
                   1616: .It
                   1617: Any
                   1618: .Sq Li \&% Ns Ar XX
                   1619: codes within the path components are decoded, with
                   1620: .Ar XX
                   1621: representing a character code in hexadecimal.
                   1622: This decoding takes place after the
                   1623: .Ar path
                   1624: has been split into components,
                   1625: but before each component is used in the equivalent of a
                   1626: .Ic cd
                   1627: or
                   1628: .Ic get
                   1629: command.
                   1630: Some often-used codes are
                   1631: .Sq Li \&%2F
                   1632: (which represents
                   1633: .Sq Li / )
                   1634: and
                   1635: .Sq Li \&%7E
                   1636: (which represents
                   1637: .Sq Li ~ ) .
                   1638: .El
                   1639: .Pp
                   1640: The above interpretation has the following consequences:
                   1641: .Bl -bullet
                   1642: .It
                   1643: The path is interpreted relative to the
                   1644: default login directory of the specified user or of the
                   1645: .Sq anonymous
                   1646: user.
1.34      lukem    1647: If the
                   1648: .Pa /
                   1649: directory is required, use a leading path of
                   1650: .Dq %2F .
                   1651: If a user's home directory is required (and the remote server supports
                   1652: the syntax), use a leading path of
                   1653: .Dq %7Euser/ .
                   1654: For example, to retrieve
                   1655: .Pa /etc/motd
                   1656: from
                   1657: .Sq localhost
                   1658: as the user
                   1659: .Sq myname
                   1660: with the password
                   1661: .Sq mypass ,
                   1662: use
                   1663: .Dq ftp://myname:mypass@localhost/%2fetc/motd
1.84      lukem    1664: .It
1.85      lukem    1665: The exact
                   1666: .Ic cd
                   1667: and
                   1668: .Ic get
                   1669: commands can be controlled by careful choice of
                   1670: where to use
                   1671: .Sq /
                   1672: and where to use
                   1673: .Sq %2F
                   1674: (or
                   1675: .Sq %2f ) .
                   1676: For example, the following URLs correspond to the
                   1677: equivalents of the indicated commands:
                   1678: .Bl -tag -width "ftp://host/%2Fdir1%2Fdir2%2Ffile"
                   1679: .It ftp://host/dir1/dir2/file
                   1680: .Dq "cd dir1" ,
                   1681: .Dq "cd dir2" ,
                   1682: .Dq "get file" .
                   1683: .It ftp://host/%2Fdir1/dir2/file
                   1684: .Dq "cd /dir1" ,
                   1685: .Dq "cd dir2" ,
                   1686: .Dq "get file" .
                   1687: .It ftp://host/dir1%2Fdir2/file
                   1688: .Dq "cd dir1/dir2" ,
                   1689: .Dq "get file" .
                   1690: .It ftp://host/%2Fdir1%2Fdir2/file
                   1691: .Dq "cd /dir1/dir2" ,
                   1692: .Dq "get file" .
                   1693: .It ftp://host/dir1%2Fdir2%2Ffile
                   1694: .Dq "get dir1/dir2/file" .
                   1695: .It ftp://host/%2Fdir1%2Fdir2%2Ffile
                   1696: .Dq "get /dir1/dir2/file" .
                   1697: .El
                   1698: .It
                   1699: You must have appropriate access permission for each of the
                   1700: intermediate directories that is used in the equivalent of a
                   1701: .Ic cd
                   1702: command.
1.84      lukem    1703: .El
1.85      lukem    1704: .\" http://[user[:password]@]host[:port]/path
                   1705: .It Xo
                   1706: .Sm off
                   1707: .Li http://
                   1708: .Oo Ar user
                   1709: .Op Li \&: Ar password
                   1710: .Li \&@ Oc
                   1711: .Ar host Oo Li \&: Ar port Oc
                   1712: .Li / Ar path
                   1713: .Sm on
                   1714: .Xc
1.56      lukem    1715: An
                   1716: .Tn HTTP
                   1717: URL, retrieved using the
                   1718: .Tn HTTP
                   1719: protocol.
                   1720: If
                   1721: .Ic "set http_proxy"
                   1722: is defined, it is used as a URL to an
                   1723: .Tn HTTP
                   1724: proxy server.
1.16      lukem    1725: If
1.56      lukem    1726: .Tn HTTP
1.88      wiz      1727: authorization is required to retrieve
1.56      lukem    1728: .Ar path ,
1.39      lukem    1729: and
                   1730: .Sq user
                   1731: (and optionally
                   1732: .Sq password )
                   1733: is in the URL, use them for the first attempt to authenticate.
1.85      lukem    1734: .\" file:///path
                   1735: .It Xo
                   1736: .Sm off
                   1737: .Li file:/// Ar path
                   1738: .Sm on
                   1739: .Xc
1.56      lukem    1740: A local URL, copied from
1.85      lukem    1741: .Pa / Ns Ar path
                   1742: on the local host.
1.16      lukem    1743: .El
                   1744: .Pp
1.37      lukem    1745: Unless noted otherwise above, and
                   1746: .Fl o Ar output
                   1747: is not given, the file is stored in the current directory as the
                   1748: .Xr basename 1
                   1749: of
1.56      lukem    1750: .Ar path .
1.37      lukem    1751: .Pp
1.73      lukem    1752: If a classic format or an
1.56      lukem    1753: .Tn FTP
                   1754: URL format has a trailing
1.73      lukem    1755: .Sq /
                   1756: or an empty
                   1757: .Ar path
                   1758: component, then
1.16      lukem    1759: .Nm
                   1760: will connect to the site and
                   1761: .Ic cd
                   1762: to the directory given as the path, and leave the user in interactive
                   1763: mode ready for further input.
1.73      lukem    1764: This will not work if
                   1765: .Ic "set ftp_proxy"
                   1766: is being used.
1.16      lukem    1767: .Pp
1.57      lukem    1768: Direct
                   1769: .Tn HTTP
                   1770: transfers use HTTP 1.1.
                   1771: Proxied
                   1772: .Tn FTP
                   1773: and
                   1774: .Tn HTTP
                   1775: transfers use HTTP 1.0.
                   1776: .Pp
1.36      lukem    1777: If
                   1778: .Fl R
1.57      lukem    1779: is given, all auto-fetches that don't go via the
1.56      lukem    1780: .Tn FTP
1.57      lukem    1781: or
                   1782: .Tn HTTP
                   1783: proxies will be restarted.
                   1784: For
                   1785: .Tn FTP ,
                   1786: this is implemented by using
1.36      lukem    1787: .Nm reget
                   1788: instead of
                   1789: .Nm get .
1.57      lukem    1790: For
                   1791: .Tn HTTP ,
                   1792: this is implemented by using the
                   1793: .Sq "Range: bytes="
                   1794: .Tn "HTTP/1.1"
                   1795: directive.
1.39      lukem    1796: .Pp
                   1797: If WWW or proxy WWW authentication is required, you will be prompted
                   1798: to enter a username and password to authenticate with.
1.44      itojun   1799: .Pp
1.46      lukem    1800: When specifying IPv6 numeric addresses in a URL, you need to
                   1801: surround the address in square brackets.
                   1802: E.g.:
                   1803: .Dq ftp://[::1]:21/ .
1.44      itojun   1804: This is because colons are used in IPv6 numeric address as well as
1.46      lukem    1805: being the separator for the port number.
1.1       cgd      1806: .Sh ABORTING A FILE TRANSFER
                   1807: To abort a file transfer, use the terminal interrupt key
                   1808: (usually Ctrl-C).
                   1809: Sending transfers will be immediately halted.
1.56      lukem    1810: Receiving transfers will be halted by sending an
                   1811: .Tn FTP
                   1812: protocol
1.1       cgd      1813: .Dv ABOR
                   1814: command to the remote server, and discarding any further data received.
                   1815: The speed at which this is accomplished depends upon the remote
                   1816: server's support for
                   1817: .Dv ABOR
                   1818: processing.
                   1819: If the remote server does not support the
                   1820: .Dv ABOR
1.59      lukem    1821: command, the prompt will not appear until the remote server has completed
1.1       cgd      1822: sending the requested file.
                   1823: .Pp
1.56      lukem    1824: If the terminal interrupt key sequence is used whilst
1.12      lukem    1825: .Nm
1.56      lukem    1826: is awaiting a reply from the remote server for the ABOR processing,
                   1827: then the connection will be closed.
                   1828: This is different from the traditional behaviour (which ignores the
                   1829: terminal interrupt during this phase), but is considered more useful.
1.1       cgd      1830: .Sh FILE NAMING CONVENTIONS
                   1831: Files specified as arguments to
1.12      lukem    1832: .Nm
1.1       cgd      1833: commands are processed according to the following rules.
                   1834: .Bl -enum
                   1835: .It
                   1836: If the file name
                   1837: .Sq Fl
                   1838: is specified, the
                   1839: .Ar stdin
                   1840: (for reading) or
                   1841: .Ar stdout
                   1842: (for writing) is used.
                   1843: .It
                   1844: If the first character of the file name is
                   1845: .Sq \&| ,
                   1846: the
                   1847: remainder of the argument is interpreted as a shell command.
1.12      lukem    1848: .Nm
1.1       cgd      1849: then forks a shell, using
                   1850: .Xr popen 3
                   1851: with the argument supplied, and reads (writes) from the stdout
                   1852: (stdin).
                   1853: If the shell command includes spaces, the argument
                   1854: must be quoted; e.g.
1.66      lukem    1855: .Dq Qq Li \&| ls\ \-lt .
1.1       cgd      1856: A particularly
1.37      lukem    1857: useful example of this mechanism is:
1.70      lukem    1858: .Dq Li dir \&"\&" \&|more .
1.1       cgd      1859: .It
                   1860: Failing the above checks, if ``globbing'' is enabled,
                   1861: local file names are expanded
                   1862: according to the rules used in the
                   1863: .Xr csh  1  ;
                   1864: c.f. the
                   1865: .Ic glob
                   1866: command.
                   1867: If the
1.12      lukem    1868: .Nm
1.34      lukem    1869: command expects a single local file (e.g.
1.1       cgd      1870: .Ic put  ) ,
                   1871: only the first filename generated by the "globbing" operation is used.
                   1872: .It
                   1873: For
                   1874: .Ic mget
                   1875: commands and
                   1876: .Ic get
                   1877: commands with unspecified local file names, the local filename is
                   1878: the remote filename, which may be altered by a
                   1879: .Ic case  ,
                   1880: .Ic ntrans ,
                   1881: or
                   1882: .Ic nmap
                   1883: setting.
                   1884: The resulting filename may then be altered if
                   1885: .Ic runique
                   1886: is on.
                   1887: .It
                   1888: For
                   1889: .Ic mput
                   1890: commands and
                   1891: .Ic put
                   1892: commands with unspecified remote file names, the remote filename is
                   1893: the local filename, which may be altered by a
                   1894: .Ic ntrans
                   1895: or
                   1896: .Ic nmap
                   1897: setting.
                   1898: The resulting filename may then be altered by the remote server if
                   1899: .Ic sunique
                   1900: is on.
                   1901: .El
                   1902: .Sh FILE TRANSFER PARAMETERS
1.56      lukem    1903: The
                   1904: .Tn FTP
                   1905: specification specifies many parameters which may affect a file transfer.
1.1       cgd      1906: The
                   1907: .Ic type
1.37      lukem    1908: may be one of
                   1909: .Dq ascii ,
                   1910: .Dq image
                   1911: (binary),
                   1912: .Dq ebcdic ,
                   1913: and
                   1914: .Dq local byte size
                   1915: (for
1.1       cgd      1916: .Tn PDP Ns -10's
                   1917: and
                   1918: .Tn PDP Ns -20's
                   1919: mostly).
1.12      lukem    1920: .Nm
1.1       cgd      1921: supports the ascii and image types of file transfer,
                   1922: plus local byte size 8 for
                   1923: .Ic tenex
                   1924: mode transfers.
                   1925: .Pp
1.12      lukem    1926: .Nm
1.1       cgd      1927: supports only the default values for the remaining
                   1928: file transfer parameters:
1.85      lukem    1929: .Ic mode ,
1.1       cgd      1930: .Ic form ,
                   1931: and
1.13      lukem    1932: .Ic struct .
1.1       cgd      1933: .Sh THE .netrc FILE
                   1934: The
                   1935: .Pa .netrc
                   1936: file contains login and initialization information
                   1937: used by the auto-login process.
1.74      lukem    1938: It resides in the user's home directory,
                   1939: unless overridden with the
                   1940: .Fl N Ar netrc
                   1941: option, or specified in the
                   1942: .Ev NETRC
                   1943: environment variable.
1.1       cgd      1944: The following tokens are recognized; they may be separated by spaces,
                   1945: tabs, or new-lines:
                   1946: .Bl -tag -width password
                   1947: .It Ic machine Ar name
                   1948: Identify a remote machine
                   1949: .Ar name .
                   1950: The auto-login process searches the
                   1951: .Pa .netrc
                   1952: file for a
                   1953: .Ic machine
                   1954: token that matches the remote machine specified on the
1.12      lukem    1955: .Nm
1.1       cgd      1956: command line or as an
                   1957: .Ic open
                   1958: command argument.
                   1959: Once a match is made, the subsequent
                   1960: .Pa .netrc
                   1961: tokens are processed,
                   1962: stopping when the end of file is reached or another
                   1963: .Ic machine
                   1964: or a
                   1965: .Ic default
                   1966: token is encountered.
                   1967: .It Ic default
                   1968: This is the same as
                   1969: .Ic machine
                   1970: .Ar name
                   1971: except that
                   1972: .Ic default
                   1973: matches any name.
                   1974: There can be only one
                   1975: .Ic default
                   1976: token, and it must be after all
                   1977: .Ic machine
                   1978: tokens.
                   1979: This is normally used as:
                   1980: .Pp
                   1981: .Dl default login anonymous password user@site
                   1982: .Pp
1.56      lukem    1983: thereby giving the user an automatic anonymous
                   1984: .Tn FTP
                   1985: login to
1.1       cgd      1986: machines not specified in
                   1987: .Pa .netrc .
                   1988: This can be overridden
                   1989: by using the
                   1990: .Fl n
                   1991: flag to disable auto-login.
                   1992: .It Ic login Ar name
                   1993: Identify a user on the remote machine.
                   1994: If this token is present, the auto-login process will initiate
                   1995: a login using the specified
                   1996: .Ar name .
                   1997: .It Ic password Ar string
                   1998: Supply a password.
                   1999: If this token is present, the auto-login process will supply the
                   2000: specified string if the remote server requires a password as part
                   2001: of the login process.
                   2002: Note that if this token is present in the
                   2003: .Pa .netrc
                   2004: file for any user other
                   2005: than
                   2006: .Ar anonymous  ,
1.12      lukem    2007: .Nm
1.1       cgd      2008: will abort the auto-login process if the
                   2009: .Pa .netrc
                   2010: is readable by
                   2011: anyone besides the user.
                   2012: .It Ic account Ar string
                   2013: Supply an additional account password.
                   2014: If this token is present, the auto-login process will supply the
                   2015: specified string if the remote server requires an additional
                   2016: account password, or the auto-login process will initiate an
                   2017: .Dv ACCT
                   2018: command if it does not.
                   2019: .It Ic macdef Ar name
                   2020: Define a macro.
                   2021: This token functions like the
1.12      lukem    2022: .Nm
1.1       cgd      2023: .Ic macdef
                   2024: command functions.
                   2025: A macro is defined with the specified name; its contents begin with the
                   2026: next
                   2027: .Pa .netrc
1.56      lukem    2028: line and continue until a blank line (consecutive new-line
1.1       cgd      2029: characters) is encountered.
                   2030: If a macro named
                   2031: .Ic init
                   2032: is defined, it is automatically executed as the last step in the
                   2033: auto-login process.
1.89      toddpw   2034: For example,
                   2035: .Bd -literal -offset indent
                   2036: default
                   2037: macdef init
                   2038: epsv4 off
                   2039: .Ed
                   2040: .Pp
                   2041: followed by a blank line.
1.1       cgd      2042: .El
1.16      lukem    2043: .Sh COMMAND LINE EDITING
                   2044: .Nm
1.34      lukem    2045: supports interactive command line editing, via the
1.16      lukem    2046: .Xr editline 3
                   2047: library.
                   2048: It is enabled with the
                   2049: .Ic edit
1.18      lukem    2050: command, and is enabled by default if input is from a tty.
1.16      lukem    2051: Previous lines can be recalled and edited with the arrow keys,
                   2052: and other GNU Emacs-style editing keys may be used as well.
                   2053: .Pp
                   2054: The
                   2055: .Xr editline 3
                   2056: library is configured with a
                   2057: .Pa .editrc
                   2058: file - refer to
                   2059: .Xr editrc 5
                   2060: for more information.
                   2061: .Pp
                   2062: An extra key binding is available to
                   2063: .Nm
                   2064: to provide context sensitive command and filename completion
                   2065: (including remote file completion).
                   2066: To use this, bind a key to the
                   2067: .Xr editline 3
                   2068: command
                   2069: .Ic ftp-complete .
                   2070: By default, this is bound to the TAB key.
1.58      lukem    2071: .Sh COMMAND LINE PROMPT
                   2072: By default,
                   2073: .Nm
                   2074: displays a command line prompt of
1.81      ross     2075: .Dq "ftp\*[Gt] "
1.58      lukem    2076: to the user.
                   2077: This can be changed with the
                   2078: .Ic "set prompt"
                   2079: command.
                   2080: .Pp
1.59      lukem    2081: A prompt can be displayed on the right side of the screen (after the
                   2082: command input) with the
                   2083: .Ic "set rprompt"
                   2084: command.
                   2085: .Pp
1.58      lukem    2086: The following formatting sequences are replaced by the given
                   2087: information:
                   2088: .Bl -tag -width "%% " -offset indent
1.85      lukem    2089: .It Li \&%/
1.58      lukem    2090: The current remote working directory.
1.85      lukem    2091: .\" %c[[0]n], %.[[0]n]
                   2092: .It Xo
                   2093: .Sm off
                   2094: .Li \&%c
                   2095: .Op Oo Li 0 Oc Ar n
                   2096: .Sm on
                   2097: .No ,
                   2098: .Sm off
                   2099: .Li \&%.
                   2100: .Op Oo Li 0 Oc Ar n
                   2101: .Sm on
                   2102: .Xc
1.59      lukem    2103: The trailing component of the current remote working directory, or
                   2104: .Em n
                   2105: trailing components if a digit
                   2106: .Em n
                   2107: is given.
                   2108: If
                   2109: .Em n
                   2110: begins with
                   2111: .Sq 0 ,
                   2112: the number of skipped components precede the trailing component(s) in
                   2113: the format
1.85      lukem    2114: .\" ``/<number>trailing''
                   2115: .Do
                   2116: .Sm off
                   2117: .Li / Li \*[Lt] Va number Li \*[Gt]
                   2118: .Va trailing
                   2119: .Sm on
                   2120: .Dc
1.59      lukem    2121: (for
1.85      lukem    2122: .Sq \&%c )
1.59      lukem    2123: or
1.85      lukem    2124: .\" ``...trailing''
                   2125: .Dq Li \&... Ns Va trailing
1.59      lukem    2126: (for
1.85      lukem    2127: .Sq \&%. ) .
                   2128: .It Li \&%M
1.58      lukem    2129: The remote host name.
1.85      lukem    2130: .It Li \&%m
1.58      lukem    2131: The remote host name, up to the first
                   2132: .Sq \&. .
1.85      lukem    2133: .It Li \&%n
1.58      lukem    2134: The remote user name.
1.85      lukem    2135: .It Li \&%%
1.58      lukem    2136: A single
                   2137: .Sq % .
                   2138: .El
1.1       cgd      2139: .Sh ENVIRONMENT
1.12      lukem    2140: .Nm
1.26      perry    2141: uses the following environment variables.
1.23      lukem    2142: .Bl -tag -width "FTPSERVERPORT"
1.28      lukem    2143: .It Ev FTPANONPASS
1.56      lukem    2144: Password to send in an anonymous
                   2145: .Tn FTP
                   2146: transfer.
1.28      lukem    2147: Defaults to
1.56      lukem    2148: .Dq Li `whoami`@ .
1.25      lukem    2149: .It Ev FTPMODE
                   2150: Overrides the default operation mode.
                   2151: Support values are:
                   2152: .Bl -tag -width "passive"
1.85      lukem    2153: .It Cm active
1.56      lukem    2154: active mode
                   2155: .Tn FTP
                   2156: only
1.85      lukem    2157: .It Cm auto
1.25      lukem    2158: automatic determination of passive or active (this is the default)
1.85      lukem    2159: .It Cm gate
1.25      lukem    2160: gate-ftp mode
1.85      lukem    2161: .It Cm passive
1.56      lukem    2162: passive mode
                   2163: .Tn FTP
                   2164: only
1.25      lukem    2165: .El
1.59      lukem    2166: .It Ev FTPPROMPT
                   2167: Command-line prompt to use.
                   2168: Defaults to
1.81      ross     2169: .Dq "ftp\*[Gt] " .
1.59      lukem    2170: Refer to
                   2171: .Sx COMMAND LINE PROMPT
                   2172: for more information.
                   2173: .It Ev FTPRPROMPT
                   2174: Command-line right side prompt to use.
                   2175: Defaults to
                   2176: .Dq "" .
                   2177: Refer to
                   2178: .Sx COMMAND LINE PROMPT
                   2179: for more information.
1.22      lukem    2180: .It Ev FTPSERVER
                   2181: Host to use as gate-ftp server when
                   2182: .Ic gate
                   2183: is enabled.
                   2184: .It Ev FTPSERVERPORT
                   2185: Port to use when connecting to gate-ftp server when
                   2186: .Ic gate
                   2187: is enabled.
                   2188: Default is port returned by a
                   2189: .Fn getservbyname
1.34      lukem    2190: lookup of
1.22      lukem    2191: .Dq ftpgate/tcp .
1.1       cgd      2192: .It Ev HOME
                   2193: For default location of a
                   2194: .Pa .netrc
                   2195: file, if one exists.
1.74      lukem    2196: .It Ev NETRC
                   2197: An alternate location of the
                   2198: .Pa .netrc
                   2199: file.
1.18      lukem    2200: .It Ev PAGER
1.56      lukem    2201: Used by various commands to display files.
                   2202: Defaults to
1.41      kleink   2203: .Xr more 1
1.56      lukem    2204: if empty or not set.
1.1       cgd      2205: .It Ev SHELL
                   2206: For default shell.
1.19      lukem    2207: .It Ev ftp_proxy
1.56      lukem    2208: URL of
                   2209: .Tn FTP
                   2210: proxy to use when making
                   2211: .Tn FTP
                   2212: URL requests
                   2213: (if not defined, use the standard
                   2214: .Tn FTP
                   2215: protocol).
1.75      lukem    2216: .Pp
1.78      wiz      2217: .Em NOTE :
1.75      lukem    2218: this is not used for interactive sessions, only for command-line
                   2219: fetches.
1.16      lukem    2220: .It Ev http_proxy
1.56      lukem    2221: URL of
                   2222: .Tn HTTP
                   2223: proxy to use when making
                   2224: .Tn HTTP
                   2225: URL requests.
1.39      lukem    2226: If proxy authentication is required and there is a username and
                   2227: password in this URL, they will automatically be used in the first
                   2228: attempt to authenticate to the proxy.
                   2229: .Pp
                   2230: Note that the use of a username and password in
1.56      lukem    2231: .Ev ftp_proxy
                   2232: and
1.39      lukem    2233: .Ev http_proxy
                   2234: may be incompatible with other programs that use it
                   2235: (such as
1.78      wiz      2236: .Xr lynx 1 ) .
1.75      lukem    2237: .Pp
1.78      wiz      2238: .Em NOTE :
1.75      lukem    2239: this is not used for interactive sessions, only for command-line
                   2240: fetches.
1.28      lukem    2241: .It Ev no_proxy
                   2242: A space or comma separated list of hosts (or domains) for which
                   2243: proxying is not to be used.
                   2244: Each entry may have an optional trailing ":port", which restricts
                   2245: the matching to connections to that port.
1.1       cgd      2246: .El
1.89      toddpw   2247: .Sh EXTENDED PASSIVE MODE AND FIREWALLS
                   2248: Some firewall configurations do not allow
                   2249: .Nm
                   2250: to use extended passive mode.
                   2251: If you find that even a simple
                   2252: .Ic ls
                   2253: appears to hang after printing a message such as this:
                   2254: .Pp
                   2255: .Dl 229 Entering Extended Passive Mode (|||58551|)
                   2256: .Pp
                   2257: then you will need to disable extended passive mode with
                   2258: .Ic epsv4 off .
                   2259: See the above section
                   2260: .Sx The .netrc File
                   2261: for an example of how to make this automatic.
1.1       cgd      2262: .Sh SEE ALSO
1.22      lukem    2263: .Xr getservbyname 3 ,
1.16      lukem    2264: .Xr editrc 5 ,
1.22      lukem    2265: .Xr services 5 ,
1.1       cgd      2266: .Xr ftpd 8
1.34      lukem    2267: .Sh STANDARDS
                   2268: .Nm
                   2269: attempts to be compliant with
                   2270: .Cm RFC 959 ,
                   2271: .Cm RFC 1123 ,
                   2272: .Cm RFC 1738 ,
1.44      itojun   2273: .Cm RFC 2068 ,
1.71      lukem    2274: .Cm RFC 2389 ,
1.61      lukem    2275: .Cm RFC 2428 ,
1.70      lukem    2276: .Cm RFC 2732 ,
1.34      lukem    2277: and
1.70      lukem    2278: .Cm draft-ietf-ftpext-mlst-11 .
1.1       cgd      2279: .Sh HISTORY
                   2280: The
1.12      lukem    2281: .Nm
1.1       cgd      2282: command appeared in
                   2283: .Bx 4.2 .
1.16      lukem    2284: .Pp
1.34      lukem    2285: Various features such as command line editing, context sensitive
1.16      lukem    2286: command and file completion, dynamic progress bar, automatic
1.42      lukem    2287: fetching of files and URLs, modification time preservation,
1.58      lukem    2288: transfer rate throttling, configurable command line prompt,
                   2289: and other enhancements over the standard
1.49      lukem    2290: .Bx
1.56      lukem    2291: .Nm
1.42      lukem    2292: were implemented in
1.18      lukem    2293: .Nx 1.3
1.58      lukem    2294: and later releases
1.91      grant    2295: by
                   2296: .An Luke Mewburn
                   2297: .Aq lukem@NetBSD.org .
1.43      itojun   2298: .Pp
1.69      lukem    2299: IPv6 support was added by the WIDE/KAME project
                   2300: (but may not be present in all non-NetBSD versions of this program, depending
                   2301: if the operating system supports IPv6 in a similar manner to KAME).
1.1       cgd      2302: .Sh BUGS
                   2303: Correct execution of many commands depends upon proper behavior
                   2304: by the remote server.
                   2305: .Pp
                   2306: An error in the treatment of carriage returns
                   2307: in the
                   2308: .Bx 4.2
                   2309: ascii-mode transfer code
                   2310: has been corrected.
                   2311: This correction may result in incorrect transfers of binary files
                   2312: to and from
                   2313: .Bx 4.2
                   2314: servers using the ascii type.
                   2315: Avoid this problem by using the binary image type.
1.65      itojun   2316: .Pp
                   2317: .Nm
                   2318: assumes that all IPv4 mapped addresses
                   2319: .Po
                   2320: IPv6 addresses with a form like
                   2321: .Li ::ffff:10.1.1.1
                   2322: .Pc
1.70      lukem    2323: indicate IPv4 destinations which can be handled by
1.68      itojun   2324: .Dv AF_INET
                   2325: sockets.
1.70      lukem    2326: However, in certain IPv6 network configurations, this assumption is not true.
                   2327: In such an environment, IPv4 mapped addresses must be passed to
1.68      itojun   2328: .Dv AF_INET6
                   2329: sockets directly.
1.70      lukem    2330: For example, if your site uses a SIIT translator for IPv6-to-IPv4 translation,
1.65      itojun   2331: .Nm
1.68      itojun   2332: is unable to support your configuration.

CVSweb <webmaster@jp.NetBSD.org>