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>