Annotation of src/usr.bin/ftp/ftp.1, Revision 1.14
1.14 ! millert 1: .\" $OpenBSD: ftp.1,v 1.13 1997/07/25 21:56:20 millert Exp $
! 2: .\" $NetBSD: ftp.1,v 1.22 1997/08/18 10:20:22 lukem Exp $
1.1 deraadt 3: .\"
4: .\" Copyright (c) 1985, 1989, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
15: .\" 3. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by the University of
18: .\" California, Berkeley and its contributors.
19: .\" 4. Neither the name of the University nor the names of its contributors
20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
35: .\" @(#)ftp.1 8.3 (Berkeley) 10/9/94
36: .\"
1.14 ! millert 37: .Dd August 18, 1997
1.1 deraadt 38: .Dt FTP 1
39: .Os BSD 4.2
40: .Sh NAME
41: .Nm ftp
42: .Nd
43: .Tn ARPANET
44: file transfer program
45: .Sh SYNOPSIS
1.6 millert 46: .Nm
47: .Op Fl a
1.1 deraadt 48: .Op Fl d
1.8 kstailey 49: .Op Fl e
1.6 millert 50: .Op Fl g
1.1 deraadt 51: .Op Fl i
52: .Op Fl n
1.6 millert 53: .Op Fl p
54: .Op Fl P Ar port
1.7 millert 55: .Op Fl r Ar seconds
1.6 millert 56: .Op Fl t
57: .Op Fl v
58: .Op Fl V
59: .Op Ar host Op Ar port
1.3 deraadt 60: .Nm ftp
1.11 millert 61: ftp://[\fIuser\fR:\fIpassword\fR@]\fIhost\fR[:\fIport\fR]/\fIfile\fR[/]
1.3 deraadt 62: .Nm ftp
1.6 millert 63: http://\fIhost\fR[:\fIport\fR]/\fIfile\fR
1.3 deraadt 64: .Nm ftp
1.9 millert 65: \fIhost\fR:[/\fIpath\fR/]\fIfile\fR[/]
1.1 deraadt 66: .Sh DESCRIPTION
1.7 millert 67: .Nm Ftp
1.1 deraadt 68: is the user interface to the
69: .Tn ARPANET
70: standard File Transfer Protocol.
71: The program allows a user to transfer files to and from a
72: remote network site.
1.3 deraadt 73: .Pp
1.7 millert 74: The latter three usage formats will fetch a file using either the
75: HTTP or FTP protocols into the current directory.
1.9 millert 76: This is ideal for scripts. Refer to
77: .Sx AUTO-FETCHING FILES
78: below for more information.
1.7 millert 79: .Pp
1.1 deraadt 80: Options may be specified at the command line, or to the
81: command interpreter.
1.6 millert 82: .Bl -tag -width "port "
83: .It Fl a
84: Causes
85: .Nm
86: to bypass normal login procedure, and use an anonymous login instead.
87: .It Fl d
88: Enables debugging.
1.8 kstailey 89: .It Fl e
1.9 millert 90: Disables command line editing. Useful for Emacs ange-ftp.
1.6 millert 91: .It Fl g
92: Disables file name globbing.
93: .It Fl i
94: Turns off interactive prompting during
95: multiple file transfers.
1.1 deraadt 96: .It Fl n
97: Restrains
1.6 millert 98: .Nm
99: from attempting
100: .Dq auto-login
101: upon initial connection.
1.1 deraadt 102: If auto-login is enabled,
1.6 millert 103: .Nm
1.1 deraadt 104: will check the
105: .Pa .netrc
106: (see below) file in the user's home directory for an entry describing
107: an account on the remote machine.
108: If no entry exists,
1.6 millert 109: .Nm
1.1 deraadt 110: will prompt for the remote machine login name (default is the user
111: identity on the local machine), and, if necessary, prompt for a password
112: and an account with which to login.
1.6 millert 113: .It Fl p
114: Enable passive mode operation for use behind connection filtering firewalls.
115: .It Fl P Ar port
116: Sets the port number to
117: .Ar port .
1.7 millert 118: .It Fl r Ar number
119: Retry to connect if failed, pausing for
120: .Ar number
121: of seconds.
1.6 millert 122: .It Fl t
123: Enables packet tracing.
124: .It Fl v
125: Enable verbose mode.
126: This is the default if input is from a terminal.
127: Forces
128: .Nm
129: to show all responses from the remote server, as well
130: as report on data transfer statistics.
131: .It Fl V
132: Disable verbose mode, overriding the default of enabled when input
133: is from a terminal.
1.1 deraadt 134: .El
135: .Pp
136: The client host with which
1.6 millert 137: .Nm
1.1 deraadt 138: is to communicate may be specified on the command line.
139: If this is done,
1.6 millert 140: .Nm
1.1 deraadt 141: will immediately attempt to establish a connection to an
142: .Tn FTP
143: server on that host; otherwise,
1.6 millert 144: .Nm
1.1 deraadt 145: will enter its command interpreter and await instructions
146: from the user.
147: When
1.6 millert 148: .Nm
1.1 deraadt 149: is awaiting commands from the user the prompt
150: .Ql ftp>
151: is provided to the user.
152: The following commands are recognized
153: by
154: .Nm ftp :
155: .Bl -tag -width Fl
156: .It Ic \&! Op Ar command Op Ar args
157: Invoke an interactive shell on the local machine.
158: If there are arguments, the first is taken to be a command to execute
159: directly, with the rest of the arguments as its arguments.
160: .It Ic \&$ Ar macro-name Op Ar args
161: Execute the macro
162: .Ar macro-name
163: that was defined with the
164: .Ic macdef
165: command.
166: Arguments are passed to the macro unglobbed.
167: .It Ic account Op Ar passwd
168: Supply a supplemental password required by a remote system for access
169: to resources once a login has been successfully completed.
170: If no argument is included, the user will be prompted for an account
171: password in a non-echoing input mode.
172: .It Ic append Ar local-file Op Ar remote-file
173: Append a local file to a file on the remote machine.
174: If
175: .Ar remote-file
176: is left unspecified, the local file name is used in naming the
177: remote file after being altered by any
178: .Ic ntrans
179: or
180: .Ic nmap
181: setting.
182: File transfer uses the current settings for
183: .Ic type ,
184: .Ic format ,
185: .Ic mode ,
186: and
187: .Ic structure .
188: .It Ic ascii
189: Set the file transfer
190: .Ic type
191: to network
192: .Tn ASCII .
193: This is the default type.
194: .It Ic bell
195: Arrange that a bell be sounded after each file transfer
196: command is completed.
197: .It Ic binary
198: Set the file transfer
199: .Ic type
200: to support binary image transfer.
201: .It Ic bye
202: Terminate the
203: .Tn FTP
204: session with the remote server
205: and exit
1.6 millert 206: .Nm ftp .
1.1 deraadt 207: An end of file will also terminate the session and exit.
208: .It Ic case
209: Toggle remote computer file name case mapping during
210: .Ic mget
211: commands.
212: When
213: .Ic case
214: is on (default is off), remote computer file names with all letters in
215: upper case are written in the local directory with the letters mapped
216: to lower case.
217: .It Ic \&cd Ar remote-directory
218: Change the working directory on the remote machine
219: to
1.6 millert 220: .Ar remote-directory .
1.1 deraadt 221: .It Ic cdup
222: Change the remote machine working directory to the parent of the
223: current remote machine working directory.
224: .It Ic chmod Ar mode file-name
225: Change the permission modes of the file
226: .Ar file-name
227: on the remote
1.6 millert 228: system to
229: .Ar mode .
1.1 deraadt 230: .It Ic close
231: Terminate the
232: .Tn FTP
233: session with the remote server, and
234: return to the command interpreter.
235: Any defined macros are erased.
236: .It Ic \&cr
237: Toggle carriage return stripping during
238: ascii type file retrieval.
239: Records are denoted by a carriage return/linefeed sequence
240: during ascii type file transfer.
241: When
242: .Ic \&cr
243: is on (the default), carriage returns are stripped from this
244: sequence to conform with the
245: .Ux
246: single linefeed record
247: delimiter.
248: Records on
249: .Pf non\- Ns Ux
250: remote systems may contain single linefeeds;
251: when an ascii type transfer is made, these linefeeds may be
252: distinguished from a record delimiter only when
253: .Ic \&cr
254: is off.
255: .It Ic delete Ar remote-file
256: Delete the file
257: .Ar remote-file
258: on the remote machine.
259: .It Ic debug Op Ar debug-value
260: Toggle debugging mode.
261: If an optional
262: .Ar debug-value
263: is specified it is used to set the debugging level.
264: When debugging is on,
1.6 millert 265: .Nm
1.7 millert 266: prints each command sent to the remote machine,
267: preceded by the string
1.1 deraadt 268: .Ql \-\->
1.6 millert 269: .It Ic dir Op Ar remote-directory Op Ar local-file
270: Print a listing of the contents of a
271: directory on the remote machine.
272: The listing includes any system-dependent information that the server
273: chooses to include; for example, most
274: .Ux
275: systems will produce
276: output from the command
277: .Ql ls \-l .
278: (See also
279: .Ic ls . )
280: If
281: .Ar remote-directory
282: is left unspecified, the current working directory is used.
1.1 deraadt 283: If interactive prompting is on,
1.6 millert 284: .Nm
1.1 deraadt 285: will prompt the user to verify that the last argument is indeed the
286: target local file for receiving
287: .Ic dir
288: output.
1.6 millert 289: If no local file is specified, or if
1.1 deraadt 290: .Ar local-file
291: is
1.6 millert 292: .Sq Fl ,
293: the output is sent to the terminal.
1.1 deraadt 294: .It Ic disconnect
295: A synonym for
1.6 millert 296: .Ic close .
297: .It Ic edit
298: Toggle command line editing, and context sensitive command and file
299: completion.
300: This is automatically enabled if input is from a terminal, and
301: disabled otherwise.
302: .It Ic exit
303: A synonym for
304: .Ic bye .
305: .It Ic ftp Ar host Op Ar port
306: A synonym for
307: .Ic open .
1.1 deraadt 308: .It Ic form Ar format
309: Set the file transfer
310: .Ic form
311: to
1.6 millert 312: .Ar format .
1.1 deraadt 313: The default format is \*(Lqfile\*(Rq.
314: .It Ic get Ar remote-file Op Ar local-file
315: Retrieve the
316: .Ar remote-file
317: and store it on the local machine.
318: If the local
319: file name is not specified, it is given the same
320: name it has on the remote machine, subject to
321: alteration by the current
322: .Ic case ,
323: .Ic ntrans ,
324: and
325: .Ic nmap
326: settings.
327: The current settings for
328: .Ic type ,
329: .Ic form ,
330: .Ic mode ,
331: and
332: .Ic structure
333: are used while transferring the file.
1.14 ! millert 334: .It Ic gate Op Ar host Op Ar port
! 335: Toggle gate-ftp mode.
! 336: This will not be permitted if the gate-ftp server hasn't been set
! 337: (either explicitly by the user, or from the
! 338: .Ev FTPSERVER
! 339: environment variable).
! 340: If
! 341: .Ar host
! 342: is given,
! 343: then gate-ftp mode will be enabled, and the gate-ftp server will be set to
! 344: .Ar host .
! 345: If
! 346: .Ar port
! 347: is also given, that will be used as the port to connect to on the
! 348: gate-ftp server.
1.1 deraadt 349: .It Ic glob
350: Toggle filename expansion for
351: .Ic mdelete ,
352: .Ic mget
353: and
1.6 millert 354: .Ic mput .
1.1 deraadt 355: If globbing is turned off with
356: .Ic glob ,
357: the file name arguments
358: are taken literally and not expanded.
359: Globbing for
360: .Ic mput
361: is done as in
362: .Xr csh 1 .
363: For
364: .Ic mdelete
365: and
366: .Ic mget ,
367: each remote file name is expanded
368: separately on the remote machine and the lists are not merged.
369: Expansion of a directory name is likely to be
370: different from expansion of the name of an ordinary file:
371: the exact result depends on the foreign operating system and ftp server,
372: and can be previewed by doing
373: .Ql mls remote-files \-
374: Note:
375: .Ic mget
376: and
377: .Ic mput
378: are not meant to transfer
379: entire directory subtrees of files.
380: That can be done by
381: transferring a
382: .Xr tar 1
383: archive of the subtree (in binary mode).
1.5 kstailey 384: .It Ic hash Op Ar size
1.1 deraadt 385: Toggle hash-sign (``#'') printing for each data block
386: transferred.
1.5 kstailey 387: The size of a data block defaults to 1024 bytes.
1.6 millert 388: This can be changed by specifying
389: .Ar size
390: in bytes.
1.1 deraadt 391: .It Ic help Op Ar command
392: Print an informative message about the meaning of
1.6 millert 393: .Ar command .
1.1 deraadt 394: If no argument is given,
1.6 millert 395: .Nm
1.1 deraadt 396: prints a list of the known commands.
397: .It Ic idle Op Ar seconds
398: Set the inactivity timer on the remote server to
399: .Ar seconds
400: seconds.
401: If
402: .Ar seconds
403: is omitted, the current inactivity timer is printed.
404: .It Ic lcd Op Ar directory
405: Change the working directory on the local machine.
406: If
407: no
408: .Ar directory
409: is specified, the user's home directory is used.
1.10 millert 410: .It Ic less Ar file
411: A synonym for
412: .Ic page .
1.6 millert 413: .It Ic lpwd
414: Print the working directory on the local machine.
415: .It Ic \&ls Op Ar remote-directory Op Ar local-file
416: Print a list of the files in a
1.1 deraadt 417: directory on the remote machine.
418: If
419: .Ar remote-directory
420: is left unspecified, the current working directory is used.
421: If interactive prompting is on,
1.6 millert 422: .Nm
1.1 deraadt 423: will prompt the user to verify that the last argument is indeed the
424: target local file for receiving
1.6 millert 425: .Ic ls
1.1 deraadt 426: output.
427: If no local file is specified, or if
428: .Ar local-file
429: is
1.6 millert 430: .Fl ,
1.1 deraadt 431: the output is sent to the terminal.
432: .It Ic macdef Ar macro-name
433: Define a macro.
434: Subsequent lines are stored as the macro
435: .Ar macro-name ;
436: a null line (consecutive newline characters
437: in a file or
438: carriage returns from the terminal) terminates macro input mode.
439: There is a limit of 16 macros and 4096 total characters in all
440: defined macros.
441: Macros remain defined until a
442: .Ic close
443: command is executed.
444: The macro processor interprets `$' and `\e' as special characters.
445: A `$' followed by a number (or numbers) is replaced by the
446: corresponding argument on the macro invocation command line.
447: A `$' followed by an `i' signals that macro processor that the
448: executing macro is to be looped.
449: On the first pass `$i' is
450: replaced by the first argument on the macro invocation command line,
451: on the second pass it is replaced by the second argument, and so on.
452: A `\e' followed by any character is replaced by that character.
453: Use the `\e' to prevent special treatment of the `$'.
454: .It Ic mdelete Op Ar remote-files
455: Delete the
456: .Ar remote-files
457: on the remote machine.
458: .It Ic mdir Ar remote-files local-file
459: Like
460: .Ic dir ,
461: except multiple remote files may be specified.
462: If interactive prompting is on,
1.6 millert 463: .Nm
1.1 deraadt 464: will prompt the user to verify that the last argument is indeed the
465: target local file for receiving
466: .Ic mdir
467: output.
468: .It Ic mget Ar remote-files
469: Expand the
470: .Ar remote-files
471: on the remote machine
472: and do a
473: .Ic get
474: for each file name thus produced.
475: See
476: .Ic glob
477: for details on the filename expansion.
478: Resulting file names will then be processed according to
479: .Ic case ,
480: .Ic ntrans ,
481: and
482: .Ic nmap
483: settings.
484: Files are transferred into the local working directory,
485: which can be changed with
486: .Ql lcd directory ;
487: new local directories can be created with
488: .Ql "\&! mkdir directory" .
489: .It Ic mkdir Ar directory-name
490: Make a directory on the remote machine.
491: .It Ic mls Ar remote-files local-file
492: Like
1.6 millert 493: .Ic ls ,
1.1 deraadt 494: except multiple remote files may be specified,
495: and the
496: .Ar local-file
497: must be specified.
498: If interactive prompting is on,
1.6 millert 499: .Nm
1.1 deraadt 500: will prompt the user to verify that the last argument is indeed the
501: target local file for receiving
502: .Ic mls
503: output.
504: .It Ic mode Op Ar mode-name
505: Set the file transfer
506: .Ic mode
507: to
1.6 millert 508: .Ar mode-name .
1.1 deraadt 509: The default mode is \*(Lqstream\*(Rq mode.
510: .It Ic modtime Ar file-name
511: Show the last modification time of the file on the remote machine.
1.10 millert 512: .It Ic more Ar file
513: A synonym for
514: .Ic page .
1.1 deraadt 515: .It Ic mput Ar local-files
516: Expand wild cards in the list of local files given as arguments
517: and do a
518: .Ic put
519: for each file in the resulting list.
520: See
521: .Ic glob
522: for details of filename expansion.
523: Resulting file names will then be processed according to
524: .Ic ntrans
525: and
526: .Ic nmap
527: settings.
1.6 millert 528: .It Ic msend Ar local-files
529: A synonym for
530: .Ic mput .
1.1 deraadt 531: .It Ic newer Ar file-name
532: Get the file only if the modification time of the remote file is more
533: recent that the file on the current system.
534: If the file does not
535: exist on the current system, the remote file is considered
1.6 millert 536: .Ic newer .
1.1 deraadt 537: Otherwise, this command is identical to
1.6 millert 538: .Ar get .
539: .It Ic nlist Op Ar remote-directory Op Ar local-file
540: A synonym for
541: .Ic ls .
1.1 deraadt 542: .It Ic nmap Op Ar inpattern outpattern
543: Set or unset the filename mapping mechanism.
544: If no arguments are specified, the filename mapping mechanism is unset.
545: If arguments are specified, remote filenames are mapped during
546: .Ic mput
547: commands and
548: .Ic put
549: commands issued without a specified remote target filename.
550: If arguments are specified, local filenames are mapped during
551: .Ic mget
552: commands and
553: .Ic get
554: commands issued without a specified local target filename.
555: This command is useful when connecting to a
556: .No non\- Ns Ux
557: remote computer
558: with different file naming conventions or practices.
559: The mapping follows the pattern set by
560: .Ar inpattern
561: and
1.6 millert 562: .Ar outpattern .
1.1 deraadt 563: .Op Ar Inpattern
564: is a template for incoming filenames (which may have already been
565: processed according to the
566: .Ic ntrans
567: and
568: .Ic case
569: settings).
570: Variable templating is accomplished by including the
571: sequences `$1', `$2', ..., `$9' in
1.6 millert 572: .Ar inpattern .
1.1 deraadt 573: Use `\\' to prevent this special treatment of the `$' character.
574: All other characters are treated literally, and are used to determine the
575: .Ic nmap
576: .Op Ar inpattern
577: variable values.
578: For example, given
579: .Ar inpattern
580: $1.$2 and the remote file name "mydata.data", $1 would have the value
581: "mydata", and $2 would have the value "data".
582: The
583: .Ar outpattern
584: determines the resulting mapped filename.
585: The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
586: from the
587: .Ar inpattern
588: template.
589: The sequence `$0' is replace by the original filename.
590: Additionally, the sequence
591: .Ql Op Ar seq1 , Ar seq2
592: is replaced by
593: .Op Ar seq1
594: if
595: .Ar seq1
596: is not a null string; otherwise it is replaced by
597: .Ar seq2 .
598: For example, the command
599: .Pp
600: .Bd -literal -offset indent -compact
601: nmap $1.$2.$3 [$1,$2].[$2,file]
602: .Ed
603: .Pp
604: would yield
605: the output filename "myfile.data" for input filenames "myfile.data" and
606: "myfile.data.old", "myfile.file" for the input filename "myfile", and
607: "myfile.myfile" for the input filename ".myfile".
608: Spaces may be included in
609: .Ar outpattern ,
610: as in the example: `nmap $1 sed "s/ *$//" > $1' .
611: Use the `\e' character to prevent special treatment
612: of the `$','[','[', and `,' characters.
613: .It Ic ntrans Op Ar inchars Op Ar outchars
614: Set or unset the filename character translation mechanism.
615: If no arguments are specified, the filename character
616: translation mechanism is unset.
617: If arguments are specified, characters in
618: remote filenames are translated during
619: .Ic mput
620: commands and
621: .Ic put
622: commands issued without a specified remote target filename.
623: If arguments are specified, characters in
624: local filenames are translated during
625: .Ic mget
626: commands and
627: .Ic get
628: commands issued without a specified local target filename.
629: This command is useful when connecting to a
630: .No non\- Ns Ux
631: remote computer
632: with different file naming conventions or practices.
633: Characters in a filename matching a character in
634: .Ar inchars
635: are replaced with the corresponding character in
1.6 millert 636: .Ar outchars .
1.1 deraadt 637: If the character's position in
638: .Ar inchars
639: is longer than the length of
640: .Ar outchars ,
641: the character is deleted from the file name.
642: .It Ic open Ar host Op Ar port
643: Establish a connection to the specified
644: .Ar host
645: .Tn FTP
646: server.
647: An optional port number may be supplied,
648: in which case,
1.6 millert 649: .Nm
1.1 deraadt 650: will attempt to contact an
651: .Tn FTP
652: server at that port.
653: If the
654: .Ic auto-login
655: option is on (default),
1.6 millert 656: .Nm
1.1 deraadt 657: will also attempt to automatically log the user in to
658: the
659: .Tn FTP
660: server (see below).
1.9 millert 661: .It Ic page Ar file
662: Retrieve
663: .Ic file
664: and display with the program defined in
665: .Ev PAGER
666: (which defaults to
667: .Xr more 1 ).
1.1 deraadt 668: .It Ic passive
669: Toggle passive mode. If passive mode is turned on
670: (default is off), the ftp client will
671: send a
672: .Dv PASV
673: command for all data connections instead of the usual
674: .Dv PORT
675: command. The
676: .Dv PASV
677: command requests that the remote server open a port for the data connection
678: and return the address of that port. The remote server listens on that
679: port and the client connects to it. When using the more traditional
680: .Dv PORT
681: command, the client listens on a port and sends that address to the remote
682: server, who connects back to it. Passive mode is useful when using
1.6 millert 683: .Nm
1.1 deraadt 684: through a gateway router or host that controls the directionality of
685: traffic.
686: (Note that though ftp servers are required to support the
687: .Dv PASV
688: command by RFC 1123, some do not.)
1.6 millert 689: .It Ic preserve
690: Toggle preservation of modification times on retrieved files.
691: .It Ic progress
692: Toggle display of transfer progress bar.
1.9 millert 693: The progress bar will be disabled for a transfer that has
694: .Ar local-file
695: as
696: .Sq Fl
697: or a command that starts with
698: .Sq \&| .
699: Refer to
700: .Sx FILE NAMING CONVENTIONS
701: for more information.
1.1 deraadt 702: .It Ic prompt
703: Toggle interactive prompting.
704: Interactive prompting
705: occurs during multiple file transfers to allow the
706: user to selectively retrieve or store files.
707: If prompting is turned off (default is on), any
708: .Ic mget
709: or
710: .Ic mput
711: will transfer all files, and any
712: .Ic mdelete
713: will delete all files.
1.6 millert 714: .Pp
715: When prompting is on, the following commands are available at a prompt:
716: .Bl -tag -width 2n -offset indent
717: .It Ic n
718: Do not transfer the file.
719: .It Ic a
720: Answer
721: .Sq yes
722: to the current file, and automatically answer
723: .Sq yes
724: to any remaining files for the current command.
725: .It Ic p
726: Answer
727: .Sq yes
728: to the current file, and turn off prompt mode
729: (as is
730: .Dq prompt off
731: had been given).
732: .El
733: .Pp
734: Any other reponse will answer
735: .Sq yes
736: to the current file.
1.1 deraadt 737: .It Ic proxy Ar ftp-command
738: Execute an ftp command on a secondary control connection.
739: This command allows simultaneous connection to two remote ftp
740: servers for transferring files between the two servers.
741: The first
742: .Ic proxy
743: command should be an
744: .Ic open ,
745: to establish the secondary control connection.
746: Enter the command "proxy ?" to see other ftp commands executable on the
747: secondary connection.
748: The following commands behave differently when prefaced by
749: .Ic proxy :
750: .Ic open
751: will not define new macros during the auto-login process,
752: .Ic close
753: will not erase existing macro definitions,
754: .Ic get
755: and
756: .Ic mget
757: transfer files from the host on the primary control connection
758: to the host on the secondary control connection, and
759: .Ic put ,
760: .Ic mput ,
761: and
762: .Ic append
763: transfer files from the host on the secondary control connection
764: to the host on the primary control connection.
765: Third party file transfers depend upon support of the ftp protocol
766: .Dv PASV
767: command by the server on the secondary control connection.
768: .It Ic put Ar local-file Op Ar remote-file
769: Store a local file on the remote machine.
770: If
771: .Ar remote-file
772: is left unspecified, the local file name is used
773: after processing according to any
774: .Ic ntrans
775: or
776: .Ic nmap
777: settings
778: in naming the remote file.
779: File transfer uses the
780: current settings for
781: .Ic type ,
782: .Ic format ,
783: .Ic mode ,
784: and
1.6 millert 785: .Ic structure .
1.1 deraadt 786: .It Ic pwd
787: Print the name of the current working directory on the remote
788: machine.
789: .It Ic quit
790: A synonym for
1.6 millert 791: .Ic bye .
1.1 deraadt 792: .It Ic quote Ar arg1 arg2 ...
793: The arguments specified are sent, verbatim, to the remote
794: .Tn FTP
795: server.
796: .It Ic recv Ar remote-file Op Ar local-file
1.6 millert 797: A synonym for
798: .Ic get .
1.1 deraadt 799: .It Ic reget Ar remote-file Op Ar local-file
800: Reget acts like get, except that if
801: .Ar local-file
802: exists and is
803: smaller than
804: .Ar remote-file ,
805: .Ar local-file
806: is presumed to be
807: a partially transferred copy of
808: .Ar remote-file
809: and the transfer
810: is continued from the apparent point of failure.
811: This command
812: is useful when transferring very large files over networks that
813: are prone to dropping connections.
814: .It Ic remotehelp Op Ar command-name
815: Request help from the remote
816: .Tn FTP
817: server.
818: If a
819: .Ar command-name
820: is specified it is supplied to the server as well.
1.6 millert 821: .It Ic rstatus Op Ar file-name
1.1 deraadt 822: With no arguments, show status of remote machine.
823: If
824: .Ar file-name
825: is specified, show status of
826: .Ar file-name
827: on remote machine.
1.6 millert 828: .It Ic rename Op Ar from Op Ar to
1.1 deraadt 829: Rename the file
830: .Ar from
831: on the remote machine, to the file
1.6 millert 832: .Ar to .
1.1 deraadt 833: .It Ic reset
834: Clear reply queue.
835: This command re-synchronizes command/reply sequencing with the remote
836: ftp server.
837: Resynchronization may be necessary following a violation of the ftp protocol
838: by the remote server.
839: .It Ic restart Ar marker
840: Restart the immediately following
841: .Ic get
842: or
843: .Ic put
844: at the
845: indicated
1.6 millert 846: .Ar marker .
1.1 deraadt 847: On
848: .Ux
849: systems, marker is usually a byte
850: offset into the file.
851: .It Ic rmdir Ar directory-name
852: Delete a directory on the remote machine.
853: .It Ic runique
854: Toggle storing of files on the local system with unique filenames.
855: If a file already exists with a name equal to the target
856: local filename for a
857: .Ic get
858: or
859: .Ic mget
860: command, a ".1" is appended to the name.
861: If the resulting name matches another existing file,
862: a ".2" is appended to the original name.
863: If this process continues up to ".99", an error
864: message is printed, and the transfer does not take place.
865: The generated unique filename will be reported.
866: Note that
867: .Ic runique
868: will not affect local files generated from a shell command
869: (see below).
870: The default value is off.
871: .It Ic send Ar local-file Op Ar remote-file
1.6 millert 872: A synonym for
873: .Ic put .
1.1 deraadt 874: .It Ic sendport
875: Toggle the use of
876: .Dv PORT
877: commands.
878: By default,
1.6 millert 879: .Nm
1.1 deraadt 880: will attempt to use a
881: .Dv PORT
882: command when establishing
883: a connection for each data transfer.
884: The use of
885: .Dv PORT
886: commands can prevent delays
887: when performing multiple file transfers.
888: If the
889: .Dv PORT
890: command fails,
1.6 millert 891: .Nm
1.1 deraadt 892: will use the default data port.
893: When the use of
894: .Dv PORT
895: commands is disabled, no attempt will be made to use
896: .Dv PORT
897: commands for each data transfer.
898: This is useful
899: for certain
900: .Tn FTP
901: implementations which do ignore
902: .Dv PORT
903: commands but, incorrectly, indicate they've been accepted.
904: .It Ic site Ar arg1 arg2 ...
905: The arguments specified are sent, verbatim, to the remote
906: .Tn FTP
907: server as a
908: .Dv SITE
909: command.
910: .It Ic size Ar file-name
911: Return size of
912: .Ar file-name
913: on remote machine.
914: .It Ic status
915: Show the current status of
1.6 millert 916: .Nm ftp .
1.1 deraadt 917: .It Ic struct Op Ar struct-name
918: Set the file transfer
919: .Ar structure
920: to
921: .Ar struct-name .
922: By default \*(Lqstream\*(Rq structure is used.
923: .It Ic sunique
924: Toggle storing of files on remote machine under unique file names.
925: Remote ftp server must support ftp protocol
926: .Dv STOU
927: command for
928: successful completion.
929: The remote server will report unique name.
930: Default value is off.
931: .It Ic system
932: Show the type of operating system running on the remote machine.
933: .It Ic tenex
934: Set the file transfer type to that needed to
935: talk to
936: .Tn TENEX
937: machines.
938: .It Ic trace
939: Toggle packet tracing.
940: .It Ic type Op Ar type-name
941: Set the file transfer
942: .Ic type
943: to
1.6 millert 944: .Ar type-name .
1.1 deraadt 945: If no type is specified, the current type
946: is printed.
947: The default type is network
948: .Tn ASCII .
949: .It Ic umask Op Ar newmask
950: Set the default umask on the remote server to
1.6 millert 951: .Ar newmask .
1.1 deraadt 952: If
953: .Ar newmask
954: is omitted, the current umask is printed.
955: .It Xo
956: .Ic user Ar user-name
1.6 millert 957: .Op Ar password Op Ar account
1.1 deraadt 958: .Xc
959: Identify yourself to the remote
960: .Tn FTP
961: server.
962: If the
963: .Ar password
964: is not specified and the server requires it,
1.6 millert 965: .Nm
1.1 deraadt 966: will prompt the user for it (after disabling local echo).
967: If an
968: .Ar account
969: field is not specified, and the
970: .Tn FTP
971: server
972: requires it, the user will be prompted for it.
973: If an
974: .Ar account
975: field is specified, an account command will
976: be relayed to the remote server after the login sequence
977: is completed if the remote server did not require it
978: for logging in.
979: Unless
1.6 millert 980: .Nm
1.1 deraadt 981: is invoked with \*(Lqauto-login\*(Rq disabled, this
982: process is done automatically on initial connection to
983: the
984: .Tn FTP
985: server.
986: .It Ic verbose
987: Toggle verbose mode.
988: In verbose mode, all responses from
989: the
990: .Tn FTP
991: server are displayed to the user.
992: In addition,
993: if verbose is on, when a file transfer completes, statistics
994: regarding the efficiency of the transfer are reported.
995: By default,
996: verbose is on.
997: .It Ic ? Op Ar command
1.6 millert 998: A synonym for
999: .Ic help .
1.1 deraadt 1000: .El
1001: .Pp
1002: Command arguments which have embedded spaces may be quoted with
1003: quote `"' marks.
1.6 millert 1004: .Pp
1005: Commands which toggle settings can take an explicit
1006: .Ic on
1007: or
1008: .Ic off
1009: argument to force the setting appropriately.
1010: .Pp
1011: If
1012: .Nm
1013: receives a
1014: .Dv SIGINFO
1015: (see the
1016: .Dq status
1017: argument of
1018: .Xr stty 1 )
1019: signal whilst a transfer is in progress, the current transfer rate
1020: statistics will be written to the standard error output, in the
1021: same format as the standard completion message.
1022: .Sh AUTO-FETCHING FILES
1023: In addition to standard commands, this version of
1024: .Nm
1025: supports an auto-fetch feature.
1026: To enable auto-fetch, simply pass the list of hostnames/files
1027: on the command line.
1028: .Pp
1029: The following formats are valid syntax for an auto-fetch element:
1.11 millert 1030: .Bl -tag -width "ftp://[user:password@]host[:port]/file"
1.6 millert 1031: .It host:/file
1032: .Dq Classic
1033: ftp format
1.11 millert 1034: .It ftp://[user:password@]host[:port]/file
1035: An ftp URL, retrieved using the ftp protocol if
1.10 millert 1036: .Ev ftp_proxy
1037: isn't defined.
1038: Otherwise, transfer using http via the proxy defined in
1039: .Ev ftp_proxy .
1.11 millert 1040: If
1041: .Ar user:password@
1042: is given and
1043: .Ev ftp_proxy
1044: isn't defined, login as
1045: .Ar user
1046: with a password of
1047: .Ar password .
1.6 millert 1048: .It http://host[:port]/file
1.11 millert 1049: An http URL, retrieved using the http protocol.
1.6 millert 1050: If
1051: .Ev http_proxy
1052: is defined, it is used as a URL to an HTTP proxy server.
1053: .El
1054: .Pp
1055: If a classic format or a ftp URL format has a trailing
1056: .Sq / ,
1057: then
1058: .Nm
1059: will connect to the site and
1060: .Ic cd
1061: to the directory given as the path, and leave the user in interactive
1062: mode ready for further input.
1063: .Pp
1064: If successive auto-fetch ftp elements refer to the same host, then
1065: the connection is maintained between transfers, reducing overhead on
1066: connection creation and deletion.
1.9 millert 1067: .Pp
1068: If
1069: .Ic file
1070: contains a glob character and globbing is enabled,
1071: (see
1.13 millert 1072: .Ic glob ) ,
1.9 millert 1073: then the equivalent of
1074: .Ic "mget file"
1075: is performed.
1076: .Pp
1.12 deraadt 1077: If standard output is redirected to a non-tty device, ftp will write
1078: the data file out to standard output. This can be used to pipe data
1079: directly to another process.
1080: Otherwise if the directory component of
1.9 millert 1081: .Ic file
1082: contains no globbing characters,
1083: it is stored in the current directory as the
1084: .Xr basename 1
1085: of
1086: .Ic file .
1087: Otherwise, the remote name is used as the local name.
1.1 deraadt 1088: .Sh ABORTING A FILE TRANSFER
1089: To abort a file transfer, use the terminal interrupt key
1090: (usually Ctrl-C).
1091: Sending transfers will be immediately halted.
1092: Receiving transfers will be halted by sending a ftp protocol
1093: .Dv ABOR
1094: command to the remote server, and discarding any further data received.
1095: The speed at which this is accomplished depends upon the remote
1096: server's support for
1097: .Dv ABOR
1098: processing.
1099: If the remote server does not support the
1100: .Dv ABOR
1101: command, an
1102: .Ql ftp>
1103: prompt will not appear until the remote server has completed
1104: sending the requested file.
1105: .Pp
1106: The terminal interrupt key sequence will be ignored when
1.6 millert 1107: .Nm
1.1 deraadt 1108: has completed any local processing and is awaiting a reply
1109: from the remote server.
1110: A long delay in this mode may result from the ABOR processing described
1111: above, or from unexpected behavior by the remote server, including
1112: violations of the ftp protocol.
1113: If the delay results from unexpected remote server behavior, the local
1.6 millert 1114: .Nm
1.1 deraadt 1115: program must be killed by hand.
1116: .Sh FILE NAMING CONVENTIONS
1117: Files specified as arguments to
1.6 millert 1118: .Nm
1.1 deraadt 1119: commands are processed according to the following rules.
1120: .Bl -enum
1121: .It
1122: If the file name
1123: .Sq Fl
1124: is specified, the
1125: .Ar stdin
1126: (for reading) or
1127: .Ar stdout
1128: (for writing) is used.
1129: .It
1130: If the first character of the file name is
1131: .Sq \&| ,
1132: the
1133: remainder of the argument is interpreted as a shell command.
1.6 millert 1134: .Nm
1.1 deraadt 1135: then forks a shell, using
1136: .Xr popen 3
1137: with the argument supplied, and reads (writes) from the stdout
1138: (stdin).
1139: If the shell command includes spaces, the argument
1140: must be quoted; e.g.
1141: \*(Lq" ls -lt"\*(Rq.
1142: A particularly
1.6 millert 1143: useful example of this mechanism is: \*(Lqdir \&|more\*(Rq.
1.1 deraadt 1144: .It
1145: Failing the above checks, if ``globbing'' is enabled,
1146: local file names are expanded
1147: according to the rules used in the
1148: .Xr csh 1 ;
1149: c.f. the
1150: .Ic glob
1151: command.
1152: If the
1.6 millert 1153: .Nm
1.1 deraadt 1154: command expects a single local file (.e.g.
1155: .Ic put ) ,
1156: only the first filename generated by the "globbing" operation is used.
1157: .It
1158: For
1159: .Ic mget
1160: commands and
1161: .Ic get
1162: commands with unspecified local file names, the local filename is
1163: the remote filename, which may be altered by a
1164: .Ic case ,
1165: .Ic ntrans ,
1166: or
1167: .Ic nmap
1168: setting.
1169: The resulting filename may then be altered if
1170: .Ic runique
1171: is on.
1172: .It
1173: For
1174: .Ic mput
1175: commands and
1176: .Ic put
1177: commands with unspecified remote file names, the remote filename is
1178: the local filename, which may be altered by a
1179: .Ic ntrans
1180: or
1181: .Ic nmap
1182: setting.
1183: The resulting filename may then be altered by the remote server if
1184: .Ic sunique
1185: is on.
1186: .El
1187: .Sh FILE TRANSFER PARAMETERS
1188: The FTP specification specifies many parameters which may
1189: affect a file transfer.
1190: The
1191: .Ic type
1192: may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary),
1193: \*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for
1194: .Tn PDP Ns -10's
1195: and
1196: .Tn PDP Ns -20's
1197: mostly).
1.6 millert 1198: .Nm
1.1 deraadt 1199: supports the ascii and image types of file transfer,
1200: plus local byte size 8 for
1201: .Ic tenex
1202: mode transfers.
1203: .Pp
1.6 millert 1204: .Nm
1.1 deraadt 1205: supports only the default values for the remaining
1206: file transfer parameters:
1207: .Ic mode ,
1208: .Ic form ,
1209: and
1.6 millert 1210: .Ic struct .
1.1 deraadt 1211: .Sh THE .netrc FILE
1212: The
1213: .Pa .netrc
1214: file contains login and initialization information
1215: used by the auto-login process.
1216: It resides in the user's home directory.
1217: The following tokens are recognized; they may be separated by spaces,
1218: tabs, or new-lines:
1219: .Bl -tag -width password
1220: .It Ic machine Ar name
1221: Identify a remote machine
1222: .Ar name .
1223: The auto-login process searches the
1224: .Pa .netrc
1225: file for a
1226: .Ic machine
1227: token that matches the remote machine specified on the
1.6 millert 1228: .Nm
1.1 deraadt 1229: command line or as an
1230: .Ic open
1231: command argument.
1232: Once a match is made, the subsequent
1233: .Pa .netrc
1234: tokens are processed,
1235: stopping when the end of file is reached or another
1236: .Ic machine
1237: or a
1238: .Ic default
1239: token is encountered.
1240: .It Ic default
1241: This is the same as
1242: .Ic machine
1243: .Ar name
1244: except that
1245: .Ic default
1246: matches any name.
1247: There can be only one
1248: .Ic default
1249: token, and it must be after all
1250: .Ic machine
1251: tokens.
1252: This is normally used as:
1253: .Pp
1254: .Dl default login anonymous password user@site
1255: .Pp
1256: thereby giving the user
1257: .Ar automatic
1258: anonymous ftp login to
1259: machines not specified in
1260: .Pa .netrc .
1261: This can be overridden
1262: by using the
1263: .Fl n
1264: flag to disable auto-login.
1265: .It Ic login Ar name
1266: Identify a user on the remote machine.
1267: If this token is present, the auto-login process will initiate
1268: a login using the specified
1269: .Ar name .
1270: .It Ic password Ar string
1271: Supply a password.
1272: If this token is present, the auto-login process will supply the
1273: specified string if the remote server requires a password as part
1274: of the login process.
1275: Note that if this token is present in the
1276: .Pa .netrc
1277: file for any user other
1278: than
1279: .Ar anonymous ,
1.6 millert 1280: .Nm
1.1 deraadt 1281: will abort the auto-login process if the
1282: .Pa .netrc
1283: is readable by
1284: anyone besides the user.
1285: .It Ic account Ar string
1286: Supply an additional account password.
1287: If this token is present, the auto-login process will supply the
1288: specified string if the remote server requires an additional
1289: account password, or the auto-login process will initiate an
1290: .Dv ACCT
1291: command if it does not.
1292: .It Ic macdef Ar name
1293: Define a macro.
1294: This token functions like the
1.6 millert 1295: .Nm
1.1 deraadt 1296: .Ic macdef
1297: command functions.
1298: A macro is defined with the specified name; its contents begin with the
1299: next
1300: .Pa .netrc
1301: line and continue until a null line (consecutive new-line
1302: characters) is encountered.
1303: If a macro named
1304: .Ic init
1305: is defined, it is automatically executed as the last step in the
1306: auto-login process.
1307: .El
1.6 millert 1308: .Sh COMMAND LINE EDITING
1309: .Nm
1310: supports interactive command line editing, via the
1311: .Xr editline 3
1312: library.
1313: It is enabled with the
1314: .Ic edit
1.9 millert 1315: command, and is enabled by default if input is from a tty.
1.6 millert 1316: Previous lines can be recalled and edited with the arrow keys,
1317: and other GNU Emacs-style editing keys may be used as well.
1318: .Pp
1319: The
1320: .Xr editline 3
1321: library is configured with a
1322: .Pa .editrc
1323: file - refer to
1324: .Xr editrc 5
1325: for more information.
1326: .Pp
1327: An extra key binding is available to
1328: .Nm
1329: to provide context sensitive command and filename completion
1330: (including remote file completion).
1331: To use this, bind a key to the
1332: .Xr editline 3
1333: command
1334: .Ic ftp-complete .
1335: By default, this is bound to the TAB key.
1.1 deraadt 1336: .Sh ENVIRONMENT
1.6 millert 1337: .Nm
1.1 deraadt 1338: utilizes the following environment variables.
1.6 millert 1339: .Bl -tag -width "http_proxy"
1.14 ! millert 1340: .It Ev FTPSERVER
! 1341: Host to use as gate-ftp server when
! 1342: .Ic gate
! 1343: is enabled.
! 1344: .It Ev FTPSERVERPORT
! 1345: Port to use when connecting to gate-ftp server when
! 1346: .Ic gate
! 1347: is enabled.
! 1348: Default is port returned by a
! 1349: .Fn getservbyname
! 1350: lookup of
! 1351: .Dq ftpgate/tcp .
1.1 deraadt 1352: .It Ev HOME
1353: For default location of a
1354: .Pa .netrc
1355: file, if one exists.
1.9 millert 1356: .It Ev PAGER
1357: Used by
1358: .Ic page
1359: to display files.
1.1 deraadt 1360: .It Ev SHELL
1361: For default shell.
1.10 millert 1362: .It Ev ftp_proxy
1363: URL of FTP proxy to use when making FTP URL requests
1364: (if not defined, use the standard ftp protocol).
1.6 millert 1365: .It Ev http_proxy
1.10 millert 1366: URL of HTTP proxy to use when making HTTP URL requests.
1.1 deraadt 1367: .El
1368: .Sh SEE ALSO
1.14 ! millert 1369: .Xr getservbyname 3 ,
1.6 millert 1370: .Xr editrc 5 ,
1.14 ! millert 1371: .Xr services 5 ,
1.1 deraadt 1372: .Xr ftpd 8
1373: .Sh HISTORY
1374: The
1.6 millert 1375: .Nm
1.1 deraadt 1376: command appeared in
1377: .Bx 4.2 .
1378: .Sh BUGS
1379: Correct execution of many commands depends upon proper behavior
1380: by the remote server.
1381: .Pp
1382: An error in the treatment of carriage returns
1383: in the
1384: .Bx 4.2
1385: ascii-mode transfer code
1386: has been corrected.
1387: This correction may result in incorrect transfers of binary files
1388: to and from
1389: .Bx 4.2
1390: servers using the ascii type.
1391: Avoid this problem by using the binary image type.
![[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 [local] / src / usr.bin / ftp