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