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