Annotation of src/usr.bin/ftp/ftp.1, Revision 1.13
1.13 ! millert 1: .\" $OpenBSD: ftp.1,v 1.12 1997/04/23 20:33:09 deraadt Exp $
! 2: .\" $NetBSD: ftp.1,v 1.21 1997/06/10 21:59:58 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.9 millert 37: .Dd February 23, 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.
334: .It Ic glob
335: Toggle filename expansion for
336: .Ic mdelete ,
337: .Ic mget
338: and
1.6 millert 339: .Ic mput .
1.1 deraadt 340: If globbing is turned off with
341: .Ic glob ,
342: the file name arguments
343: are taken literally and not expanded.
344: Globbing for
345: .Ic mput
346: is done as in
347: .Xr csh 1 .
348: For
349: .Ic mdelete
350: and
351: .Ic mget ,
352: each remote file name is expanded
353: separately on the remote machine and the lists are not merged.
354: Expansion of a directory name is likely to be
355: different from expansion of the name of an ordinary file:
356: the exact result depends on the foreign operating system and ftp server,
357: and can be previewed by doing
358: .Ql mls remote-files \-
359: Note:
360: .Ic mget
361: and
362: .Ic mput
363: are not meant to transfer
364: entire directory subtrees of files.
365: That can be done by
366: transferring a
367: .Xr tar 1
368: archive of the subtree (in binary mode).
1.5 kstailey 369: .It Ic hash Op Ar size
1.1 deraadt 370: Toggle hash-sign (``#'') printing for each data block
371: transferred.
1.5 kstailey 372: The size of a data block defaults to 1024 bytes.
1.6 millert 373: This can be changed by specifying
374: .Ar size
375: in bytes.
1.1 deraadt 376: .It Ic help Op Ar command
377: Print an informative message about the meaning of
1.6 millert 378: .Ar command .
1.1 deraadt 379: If no argument is given,
1.6 millert 380: .Nm
1.1 deraadt 381: prints a list of the known commands.
382: .It Ic idle Op Ar seconds
383: Set the inactivity timer on the remote server to
384: .Ar seconds
385: seconds.
386: If
387: .Ar seconds
388: is omitted, the current inactivity timer is printed.
389: .It Ic lcd Op Ar directory
390: Change the working directory on the local machine.
391: If
392: no
393: .Ar directory
394: is specified, the user's home directory is used.
1.10 millert 395: .It Ic less Ar file
396: A synonym for
397: .Ic page .
1.6 millert 398: .It Ic lpwd
399: Print the working directory on the local machine.
400: .It Ic \&ls Op Ar remote-directory Op Ar local-file
401: Print a list of the files in a
1.1 deraadt 402: directory on the remote machine.
403: If
404: .Ar remote-directory
405: is left unspecified, the current working directory is used.
406: If interactive prompting is on,
1.6 millert 407: .Nm
1.1 deraadt 408: will prompt the user to verify that the last argument is indeed the
409: target local file for receiving
1.6 millert 410: .Ic ls
1.1 deraadt 411: output.
412: If no local file is specified, or if
413: .Ar local-file
414: is
1.6 millert 415: .Fl ,
1.1 deraadt 416: the output is sent to the terminal.
417: .It Ic macdef Ar macro-name
418: Define a macro.
419: Subsequent lines are stored as the macro
420: .Ar macro-name ;
421: a null line (consecutive newline characters
422: in a file or
423: carriage returns from the terminal) terminates macro input mode.
424: There is a limit of 16 macros and 4096 total characters in all
425: defined macros.
426: Macros remain defined until a
427: .Ic close
428: command is executed.
429: The macro processor interprets `$' and `\e' as special characters.
430: A `$' followed by a number (or numbers) is replaced by the
431: corresponding argument on the macro invocation command line.
432: A `$' followed by an `i' signals that macro processor that the
433: executing macro is to be looped.
434: On the first pass `$i' is
435: replaced by the first argument on the macro invocation command line,
436: on the second pass it is replaced by the second argument, and so on.
437: A `\e' followed by any character is replaced by that character.
438: Use the `\e' to prevent special treatment of the `$'.
439: .It Ic mdelete Op Ar remote-files
440: Delete the
441: .Ar remote-files
442: on the remote machine.
443: .It Ic mdir Ar remote-files local-file
444: Like
445: .Ic dir ,
446: except multiple remote files may be specified.
447: If interactive prompting is on,
1.6 millert 448: .Nm
1.1 deraadt 449: will prompt the user to verify that the last argument is indeed the
450: target local file for receiving
451: .Ic mdir
452: output.
453: .It Ic mget Ar remote-files
454: Expand the
455: .Ar remote-files
456: on the remote machine
457: and do a
458: .Ic get
459: for each file name thus produced.
460: See
461: .Ic glob
462: for details on the filename expansion.
463: Resulting file names will then be processed according to
464: .Ic case ,
465: .Ic ntrans ,
466: and
467: .Ic nmap
468: settings.
469: Files are transferred into the local working directory,
470: which can be changed with
471: .Ql lcd directory ;
472: new local directories can be created with
473: .Ql "\&! mkdir directory" .
474: .It Ic mkdir Ar directory-name
475: Make a directory on the remote machine.
476: .It Ic mls Ar remote-files local-file
477: Like
1.6 millert 478: .Ic ls ,
1.1 deraadt 479: except multiple remote files may be specified,
480: and the
481: .Ar local-file
482: must be specified.
483: If interactive prompting is on,
1.6 millert 484: .Nm
1.1 deraadt 485: will prompt the user to verify that the last argument is indeed the
486: target local file for receiving
487: .Ic mls
488: output.
489: .It Ic mode Op Ar mode-name
490: Set the file transfer
491: .Ic mode
492: to
1.6 millert 493: .Ar mode-name .
1.1 deraadt 494: The default mode is \*(Lqstream\*(Rq mode.
495: .It Ic modtime Ar file-name
496: Show the last modification time of the file on the remote machine.
1.10 millert 497: .It Ic more Ar file
498: A synonym for
499: .Ic page .
1.1 deraadt 500: .It Ic mput Ar local-files
501: Expand wild cards in the list of local files given as arguments
502: and do a
503: .Ic put
504: for each file in the resulting list.
505: See
506: .Ic glob
507: for details of filename expansion.
508: Resulting file names will then be processed according to
509: .Ic ntrans
510: and
511: .Ic nmap
512: settings.
1.6 millert 513: .It Ic msend Ar local-files
514: A synonym for
515: .Ic mput .
1.1 deraadt 516: .It Ic newer Ar file-name
517: Get the file only if the modification time of the remote file is more
518: recent that the file on the current system.
519: If the file does not
520: exist on the current system, the remote file is considered
1.6 millert 521: .Ic newer .
1.1 deraadt 522: Otherwise, this command is identical to
1.6 millert 523: .Ar get .
524: .It Ic nlist Op Ar remote-directory Op Ar local-file
525: A synonym for
526: .Ic ls .
1.1 deraadt 527: .It Ic nmap Op Ar inpattern outpattern
528: Set or unset the filename mapping mechanism.
529: If no arguments are specified, the filename mapping mechanism is unset.
530: If arguments are specified, remote filenames are mapped during
531: .Ic mput
532: commands and
533: .Ic put
534: commands issued without a specified remote target filename.
535: If arguments are specified, local filenames are mapped during
536: .Ic mget
537: commands and
538: .Ic get
539: commands issued without a specified local target filename.
540: This command is useful when connecting to a
541: .No non\- Ns Ux
542: remote computer
543: with different file naming conventions or practices.
544: The mapping follows the pattern set by
545: .Ar inpattern
546: and
1.6 millert 547: .Ar outpattern .
1.1 deraadt 548: .Op Ar Inpattern
549: is a template for incoming filenames (which may have already been
550: processed according to the
551: .Ic ntrans
552: and
553: .Ic case
554: settings).
555: Variable templating is accomplished by including the
556: sequences `$1', `$2', ..., `$9' in
1.6 millert 557: .Ar inpattern .
1.1 deraadt 558: Use `\\' to prevent this special treatment of the `$' character.
559: All other characters are treated literally, and are used to determine the
560: .Ic nmap
561: .Op Ar inpattern
562: variable values.
563: For example, given
564: .Ar inpattern
565: $1.$2 and the remote file name "mydata.data", $1 would have the value
566: "mydata", and $2 would have the value "data".
567: The
568: .Ar outpattern
569: determines the resulting mapped filename.
570: The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
571: from the
572: .Ar inpattern
573: template.
574: The sequence `$0' is replace by the original filename.
575: Additionally, the sequence
576: .Ql Op Ar seq1 , Ar seq2
577: is replaced by
578: .Op Ar seq1
579: if
580: .Ar seq1
581: is not a null string; otherwise it is replaced by
582: .Ar seq2 .
583: For example, the command
584: .Pp
585: .Bd -literal -offset indent -compact
586: nmap $1.$2.$3 [$1,$2].[$2,file]
587: .Ed
588: .Pp
589: would yield
590: the output filename "myfile.data" for input filenames "myfile.data" and
591: "myfile.data.old", "myfile.file" for the input filename "myfile", and
592: "myfile.myfile" for the input filename ".myfile".
593: Spaces may be included in
594: .Ar outpattern ,
595: as in the example: `nmap $1 sed "s/ *$//" > $1' .
596: Use the `\e' character to prevent special treatment
597: of the `$','[','[', and `,' characters.
598: .It Ic ntrans Op Ar inchars Op Ar outchars
599: Set or unset the filename character translation mechanism.
600: If no arguments are specified, the filename character
601: translation mechanism is unset.
602: If arguments are specified, characters in
603: remote filenames are translated during
604: .Ic mput
605: commands and
606: .Ic put
607: commands issued without a specified remote target filename.
608: If arguments are specified, characters in
609: local filenames are translated during
610: .Ic mget
611: commands and
612: .Ic get
613: commands issued without a specified local target filename.
614: This command is useful when connecting to a
615: .No non\- Ns Ux
616: remote computer
617: with different file naming conventions or practices.
618: Characters in a filename matching a character in
619: .Ar inchars
620: are replaced with the corresponding character in
1.6 millert 621: .Ar outchars .
1.1 deraadt 622: If the character's position in
623: .Ar inchars
624: is longer than the length of
625: .Ar outchars ,
626: the character is deleted from the file name.
627: .It Ic open Ar host Op Ar port
628: Establish a connection to the specified
629: .Ar host
630: .Tn FTP
631: server.
632: An optional port number may be supplied,
633: in which case,
1.6 millert 634: .Nm
1.1 deraadt 635: will attempt to contact an
636: .Tn FTP
637: server at that port.
638: If the
639: .Ic auto-login
640: option is on (default),
1.6 millert 641: .Nm
1.1 deraadt 642: will also attempt to automatically log the user in to
643: the
644: .Tn FTP
645: server (see below).
1.9 millert 646: .It Ic page Ar file
647: Retrieve
648: .Ic file
649: and display with the program defined in
650: .Ev PAGER
651: (which defaults to
652: .Xr more 1 ).
1.1 deraadt 653: .It Ic passive
654: Toggle passive mode. If passive mode is turned on
655: (default is off), the ftp client will
656: send a
657: .Dv PASV
658: command for all data connections instead of the usual
659: .Dv PORT
660: command. The
661: .Dv PASV
662: command requests that the remote server open a port for the data connection
663: and return the address of that port. The remote server listens on that
664: port and the client connects to it. When using the more traditional
665: .Dv PORT
666: command, the client listens on a port and sends that address to the remote
667: server, who connects back to it. Passive mode is useful when using
1.6 millert 668: .Nm
1.1 deraadt 669: through a gateway router or host that controls the directionality of
670: traffic.
671: (Note that though ftp servers are required to support the
672: .Dv PASV
673: command by RFC 1123, some do not.)
1.6 millert 674: .It Ic preserve
675: Toggle preservation of modification times on retrieved files.
676: .It Ic progress
677: Toggle display of transfer progress bar.
1.9 millert 678: The progress bar will be disabled for a transfer that has
679: .Ar local-file
680: as
681: .Sq Fl
682: or a command that starts with
683: .Sq \&| .
684: Refer to
685: .Sx FILE NAMING CONVENTIONS
686: for more information.
1.1 deraadt 687: .It Ic prompt
688: Toggle interactive prompting.
689: Interactive prompting
690: occurs during multiple file transfers to allow the
691: user to selectively retrieve or store files.
692: If prompting is turned off (default is on), any
693: .Ic mget
694: or
695: .Ic mput
696: will transfer all files, and any
697: .Ic mdelete
698: will delete all files.
1.6 millert 699: .Pp
700: When prompting is on, the following commands are available at a prompt:
701: .Bl -tag -width 2n -offset indent
702: .It Ic n
703: Do not transfer the file.
704: .It Ic a
705: Answer
706: .Sq yes
707: to the current file, and automatically answer
708: .Sq yes
709: to any remaining files for the current command.
710: .It Ic p
711: Answer
712: .Sq yes
713: to the current file, and turn off prompt mode
714: (as is
715: .Dq prompt off
716: had been given).
717: .El
718: .Pp
719: Any other reponse will answer
720: .Sq yes
721: to the current file.
1.1 deraadt 722: .It Ic proxy Ar ftp-command
723: Execute an ftp command on a secondary control connection.
724: This command allows simultaneous connection to two remote ftp
725: servers for transferring files between the two servers.
726: The first
727: .Ic proxy
728: command should be an
729: .Ic open ,
730: to establish the secondary control connection.
731: Enter the command "proxy ?" to see other ftp commands executable on the
732: secondary connection.
733: The following commands behave differently when prefaced by
734: .Ic proxy :
735: .Ic open
736: will not define new macros during the auto-login process,
737: .Ic close
738: will not erase existing macro definitions,
739: .Ic get
740: and
741: .Ic mget
742: transfer files from the host on the primary control connection
743: to the host on the secondary control connection, and
744: .Ic put ,
745: .Ic mput ,
746: and
747: .Ic append
748: transfer files from the host on the secondary control connection
749: to the host on the primary control connection.
750: Third party file transfers depend upon support of the ftp protocol
751: .Dv PASV
752: command by the server on the secondary control connection.
753: .It Ic put Ar local-file Op Ar remote-file
754: Store a local file on the remote machine.
755: If
756: .Ar remote-file
757: is left unspecified, the local file name is used
758: after processing according to any
759: .Ic ntrans
760: or
761: .Ic nmap
762: settings
763: in naming the remote file.
764: File transfer uses the
765: current settings for
766: .Ic type ,
767: .Ic format ,
768: .Ic mode ,
769: and
1.6 millert 770: .Ic structure .
1.1 deraadt 771: .It Ic pwd
772: Print the name of the current working directory on the remote
773: machine.
774: .It Ic quit
775: A synonym for
1.6 millert 776: .Ic bye .
1.1 deraadt 777: .It Ic quote Ar arg1 arg2 ...
778: The arguments specified are sent, verbatim, to the remote
779: .Tn FTP
780: server.
781: .It Ic recv Ar remote-file Op Ar local-file
1.6 millert 782: A synonym for
783: .Ic get .
1.1 deraadt 784: .It Ic reget Ar remote-file Op Ar local-file
785: Reget acts like get, except that if
786: .Ar local-file
787: exists and is
788: smaller than
789: .Ar remote-file ,
790: .Ar local-file
791: is presumed to be
792: a partially transferred copy of
793: .Ar remote-file
794: and the transfer
795: is continued from the apparent point of failure.
796: This command
797: is useful when transferring very large files over networks that
798: are prone to dropping connections.
799: .It Ic remotehelp Op Ar command-name
800: Request help from the remote
801: .Tn FTP
802: server.
803: If a
804: .Ar command-name
805: is specified it is supplied to the server as well.
1.6 millert 806: .It Ic rstatus Op Ar file-name
1.1 deraadt 807: With no arguments, show status of remote machine.
808: If
809: .Ar file-name
810: is specified, show status of
811: .Ar file-name
812: on remote machine.
1.6 millert 813: .It Ic rename Op Ar from Op Ar to
1.1 deraadt 814: Rename the file
815: .Ar from
816: on the remote machine, to the file
1.6 millert 817: .Ar to .
1.1 deraadt 818: .It Ic reset
819: Clear reply queue.
820: This command re-synchronizes command/reply sequencing with the remote
821: ftp server.
822: Resynchronization may be necessary following a violation of the ftp protocol
823: by the remote server.
824: .It Ic restart Ar marker
825: Restart the immediately following
826: .Ic get
827: or
828: .Ic put
829: at the
830: indicated
1.6 millert 831: .Ar marker .
1.1 deraadt 832: On
833: .Ux
834: systems, marker is usually a byte
835: offset into the file.
836: .It Ic rmdir Ar directory-name
837: Delete a directory on the remote machine.
838: .It Ic runique
839: Toggle storing of files on the local system with unique filenames.
840: If a file already exists with a name equal to the target
841: local filename for a
842: .Ic get
843: or
844: .Ic mget
845: command, a ".1" is appended to the name.
846: If the resulting name matches another existing file,
847: a ".2" is appended to the original name.
848: If this process continues up to ".99", an error
849: message is printed, and the transfer does not take place.
850: The generated unique filename will be reported.
851: Note that
852: .Ic runique
853: will not affect local files generated from a shell command
854: (see below).
855: The default value is off.
856: .It Ic send Ar local-file Op Ar remote-file
1.6 millert 857: A synonym for
858: .Ic put .
1.1 deraadt 859: .It Ic sendport
860: Toggle the use of
861: .Dv PORT
862: commands.
863: By default,
1.6 millert 864: .Nm
1.1 deraadt 865: will attempt to use a
866: .Dv PORT
867: command when establishing
868: a connection for each data transfer.
869: The use of
870: .Dv PORT
871: commands can prevent delays
872: when performing multiple file transfers.
873: If the
874: .Dv PORT
875: command fails,
1.6 millert 876: .Nm
1.1 deraadt 877: will use the default data port.
878: When the use of
879: .Dv PORT
880: commands is disabled, no attempt will be made to use
881: .Dv PORT
882: commands for each data transfer.
883: This is useful
884: for certain
885: .Tn FTP
886: implementations which do ignore
887: .Dv PORT
888: commands but, incorrectly, indicate they've been accepted.
889: .It Ic site Ar arg1 arg2 ...
890: The arguments specified are sent, verbatim, to the remote
891: .Tn FTP
892: server as a
893: .Dv SITE
894: command.
895: .It Ic size Ar file-name
896: Return size of
897: .Ar file-name
898: on remote machine.
899: .It Ic status
900: Show the current status of
1.6 millert 901: .Nm ftp .
1.1 deraadt 902: .It Ic struct Op Ar struct-name
903: Set the file transfer
904: .Ar structure
905: to
906: .Ar struct-name .
907: By default \*(Lqstream\*(Rq structure is used.
908: .It Ic sunique
909: Toggle storing of files on remote machine under unique file names.
910: Remote ftp server must support ftp protocol
911: .Dv STOU
912: command for
913: successful completion.
914: The remote server will report unique name.
915: Default value is off.
916: .It Ic system
917: Show the type of operating system running on the remote machine.
918: .It Ic tenex
919: Set the file transfer type to that needed to
920: talk to
921: .Tn TENEX
922: machines.
923: .It Ic trace
924: Toggle packet tracing.
925: .It Ic type Op Ar type-name
926: Set the file transfer
927: .Ic type
928: to
1.6 millert 929: .Ar type-name .
1.1 deraadt 930: If no type is specified, the current type
931: is printed.
932: The default type is network
933: .Tn ASCII .
934: .It Ic umask Op Ar newmask
935: Set the default umask on the remote server to
1.6 millert 936: .Ar newmask .
1.1 deraadt 937: If
938: .Ar newmask
939: is omitted, the current umask is printed.
940: .It Xo
941: .Ic user Ar user-name
1.6 millert 942: .Op Ar password Op Ar account
1.1 deraadt 943: .Xc
944: Identify yourself to the remote
945: .Tn FTP
946: server.
947: If the
948: .Ar password
949: is not specified and the server requires it,
1.6 millert 950: .Nm
1.1 deraadt 951: will prompt the user for it (after disabling local echo).
952: If an
953: .Ar account
954: field is not specified, and the
955: .Tn FTP
956: server
957: requires it, the user will be prompted for it.
958: If an
959: .Ar account
960: field is specified, an account command will
961: be relayed to the remote server after the login sequence
962: is completed if the remote server did not require it
963: for logging in.
964: Unless
1.6 millert 965: .Nm
1.1 deraadt 966: is invoked with \*(Lqauto-login\*(Rq disabled, this
967: process is done automatically on initial connection to
968: the
969: .Tn FTP
970: server.
971: .It Ic verbose
972: Toggle verbose mode.
973: In verbose mode, all responses from
974: the
975: .Tn FTP
976: server are displayed to the user.
977: In addition,
978: if verbose is on, when a file transfer completes, statistics
979: regarding the efficiency of the transfer are reported.
980: By default,
981: verbose is on.
982: .It Ic ? Op Ar command
1.6 millert 983: A synonym for
984: .Ic help .
1.1 deraadt 985: .El
986: .Pp
987: Command arguments which have embedded spaces may be quoted with
988: quote `"' marks.
1.6 millert 989: .Pp
990: Commands which toggle settings can take an explicit
991: .Ic on
992: or
993: .Ic off
994: argument to force the setting appropriately.
995: .Pp
996: If
997: .Nm
998: receives a
999: .Dv SIGINFO
1000: (see the
1001: .Dq status
1002: argument of
1003: .Xr stty 1 )
1004: signal whilst a transfer is in progress, the current transfer rate
1005: statistics will be written to the standard error output, in the
1006: same format as the standard completion message.
1007: .Sh AUTO-FETCHING FILES
1008: In addition to standard commands, this version of
1009: .Nm
1010: supports an auto-fetch feature.
1011: To enable auto-fetch, simply pass the list of hostnames/files
1012: on the command line.
1013: .Pp
1014: The following formats are valid syntax for an auto-fetch element:
1.11 millert 1015: .Bl -tag -width "ftp://[user:password@]host[:port]/file"
1.6 millert 1016: .It host:/file
1017: .Dq Classic
1018: ftp format
1.11 millert 1019: .It ftp://[user:password@]host[:port]/file
1020: An ftp URL, retrieved using the ftp protocol if
1.10 millert 1021: .Ev ftp_proxy
1022: isn't defined.
1023: Otherwise, transfer using http via the proxy defined in
1024: .Ev ftp_proxy .
1.11 millert 1025: If
1026: .Ar user:password@
1027: is given and
1028: .Ev ftp_proxy
1029: isn't defined, login as
1030: .Ar user
1031: with a password of
1032: .Ar password .
1.6 millert 1033: .It http://host[:port]/file
1.11 millert 1034: An http URL, retrieved using the http protocol.
1.6 millert 1035: If
1036: .Ev http_proxy
1037: is defined, it is used as a URL to an HTTP proxy server.
1038: .El
1039: .Pp
1040: If a classic format or a ftp URL format has a trailing
1041: .Sq / ,
1042: then
1043: .Nm
1044: will connect to the site and
1045: .Ic cd
1046: to the directory given as the path, and leave the user in interactive
1047: mode ready for further input.
1048: .Pp
1049: If successive auto-fetch ftp elements refer to the same host, then
1050: the connection is maintained between transfers, reducing overhead on
1051: connection creation and deletion.
1.9 millert 1052: .Pp
1053: If
1054: .Ic file
1055: contains a glob character and globbing is enabled,
1056: (see
1.13 ! millert 1057: .Ic glob ) ,
1.9 millert 1058: then the equivalent of
1059: .Ic "mget file"
1060: is performed.
1061: .Pp
1.12 deraadt 1062: If standard output is redirected to a non-tty device, ftp will write
1063: the data file out to standard output. This can be used to pipe data
1064: directly to another process.
1065: Otherwise if the directory component of
1.9 millert 1066: .Ic file
1067: contains no globbing characters,
1068: it is stored in the current directory as the
1069: .Xr basename 1
1070: of
1071: .Ic file .
1072: Otherwise, the remote name is used as the local name.
1.1 deraadt 1073: .Sh ABORTING A FILE TRANSFER
1074: To abort a file transfer, use the terminal interrupt key
1075: (usually Ctrl-C).
1076: Sending transfers will be immediately halted.
1077: Receiving transfers will be halted by sending a ftp protocol
1078: .Dv ABOR
1079: command to the remote server, and discarding any further data received.
1080: The speed at which this is accomplished depends upon the remote
1081: server's support for
1082: .Dv ABOR
1083: processing.
1084: If the remote server does not support the
1085: .Dv ABOR
1086: command, an
1087: .Ql ftp>
1088: prompt will not appear until the remote server has completed
1089: sending the requested file.
1090: .Pp
1091: The terminal interrupt key sequence will be ignored when
1.6 millert 1092: .Nm
1.1 deraadt 1093: has completed any local processing and is awaiting a reply
1094: from the remote server.
1095: A long delay in this mode may result from the ABOR processing described
1096: above, or from unexpected behavior by the remote server, including
1097: violations of the ftp protocol.
1098: If the delay results from unexpected remote server behavior, the local
1.6 millert 1099: .Nm
1.1 deraadt 1100: program must be killed by hand.
1101: .Sh FILE NAMING CONVENTIONS
1102: Files specified as arguments to
1.6 millert 1103: .Nm
1.1 deraadt 1104: commands are processed according to the following rules.
1105: .Bl -enum
1106: .It
1107: If the file name
1108: .Sq Fl
1109: is specified, the
1110: .Ar stdin
1111: (for reading) or
1112: .Ar stdout
1113: (for writing) is used.
1114: .It
1115: If the first character of the file name is
1116: .Sq \&| ,
1117: the
1118: remainder of the argument is interpreted as a shell command.
1.6 millert 1119: .Nm
1.1 deraadt 1120: then forks a shell, using
1121: .Xr popen 3
1122: with the argument supplied, and reads (writes) from the stdout
1123: (stdin).
1124: If the shell command includes spaces, the argument
1125: must be quoted; e.g.
1126: \*(Lq" ls -lt"\*(Rq.
1127: A particularly
1.6 millert 1128: useful example of this mechanism is: \*(Lqdir \&|more\*(Rq.
1.1 deraadt 1129: .It
1130: Failing the above checks, if ``globbing'' is enabled,
1131: local file names are expanded
1132: according to the rules used in the
1133: .Xr csh 1 ;
1134: c.f. the
1135: .Ic glob
1136: command.
1137: If the
1.6 millert 1138: .Nm
1.1 deraadt 1139: command expects a single local file (.e.g.
1140: .Ic put ) ,
1141: only the first filename generated by the "globbing" operation is used.
1142: .It
1143: For
1144: .Ic mget
1145: commands and
1146: .Ic get
1147: commands with unspecified local file names, the local filename is
1148: the remote filename, which may be altered by a
1149: .Ic case ,
1150: .Ic ntrans ,
1151: or
1152: .Ic nmap
1153: setting.
1154: The resulting filename may then be altered if
1155: .Ic runique
1156: is on.
1157: .It
1158: For
1159: .Ic mput
1160: commands and
1161: .Ic put
1162: commands with unspecified remote file names, the remote filename is
1163: the local filename, which may be altered by a
1164: .Ic ntrans
1165: or
1166: .Ic nmap
1167: setting.
1168: The resulting filename may then be altered by the remote server if
1169: .Ic sunique
1170: is on.
1171: .El
1172: .Sh FILE TRANSFER PARAMETERS
1173: The FTP specification specifies many parameters which may
1174: affect a file transfer.
1175: The
1176: .Ic type
1177: may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary),
1178: \*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for
1179: .Tn PDP Ns -10's
1180: and
1181: .Tn PDP Ns -20's
1182: mostly).
1.6 millert 1183: .Nm
1.1 deraadt 1184: supports the ascii and image types of file transfer,
1185: plus local byte size 8 for
1186: .Ic tenex
1187: mode transfers.
1188: .Pp
1.6 millert 1189: .Nm
1.1 deraadt 1190: supports only the default values for the remaining
1191: file transfer parameters:
1192: .Ic mode ,
1193: .Ic form ,
1194: and
1.6 millert 1195: .Ic struct .
1.1 deraadt 1196: .Sh THE .netrc FILE
1197: The
1198: .Pa .netrc
1199: file contains login and initialization information
1200: used by the auto-login process.
1201: It resides in the user's home directory.
1202: The following tokens are recognized; they may be separated by spaces,
1203: tabs, or new-lines:
1204: .Bl -tag -width password
1205: .It Ic machine Ar name
1206: Identify a remote machine
1207: .Ar name .
1208: The auto-login process searches the
1209: .Pa .netrc
1210: file for a
1211: .Ic machine
1212: token that matches the remote machine specified on the
1.6 millert 1213: .Nm
1.1 deraadt 1214: command line or as an
1215: .Ic open
1216: command argument.
1217: Once a match is made, the subsequent
1218: .Pa .netrc
1219: tokens are processed,
1220: stopping when the end of file is reached or another
1221: .Ic machine
1222: or a
1223: .Ic default
1224: token is encountered.
1225: .It Ic default
1226: This is the same as
1227: .Ic machine
1228: .Ar name
1229: except that
1230: .Ic default
1231: matches any name.
1232: There can be only one
1233: .Ic default
1234: token, and it must be after all
1235: .Ic machine
1236: tokens.
1237: This is normally used as:
1238: .Pp
1239: .Dl default login anonymous password user@site
1240: .Pp
1241: thereby giving the user
1242: .Ar automatic
1243: anonymous ftp login to
1244: machines not specified in
1245: .Pa .netrc .
1246: This can be overridden
1247: by using the
1248: .Fl n
1249: flag to disable auto-login.
1250: .It Ic login Ar name
1251: Identify a user on the remote machine.
1252: If this token is present, the auto-login process will initiate
1253: a login using the specified
1254: .Ar name .
1255: .It Ic password Ar string
1256: Supply a password.
1257: If this token is present, the auto-login process will supply the
1258: specified string if the remote server requires a password as part
1259: of the login process.
1260: Note that if this token is present in the
1261: .Pa .netrc
1262: file for any user other
1263: than
1264: .Ar anonymous ,
1.6 millert 1265: .Nm
1.1 deraadt 1266: will abort the auto-login process if the
1267: .Pa .netrc
1268: is readable by
1269: anyone besides the user.
1270: .It Ic account Ar string
1271: Supply an additional account password.
1272: If this token is present, the auto-login process will supply the
1273: specified string if the remote server requires an additional
1274: account password, or the auto-login process will initiate an
1275: .Dv ACCT
1276: command if it does not.
1277: .It Ic macdef Ar name
1278: Define a macro.
1279: This token functions like the
1.6 millert 1280: .Nm
1.1 deraadt 1281: .Ic macdef
1282: command functions.
1283: A macro is defined with the specified name; its contents begin with the
1284: next
1285: .Pa .netrc
1286: line and continue until a null line (consecutive new-line
1287: characters) is encountered.
1288: If a macro named
1289: .Ic init
1290: is defined, it is automatically executed as the last step in the
1291: auto-login process.
1292: .El
1.6 millert 1293: .Sh COMMAND LINE EDITING
1294: .Nm
1295: supports interactive command line editing, via the
1296: .Xr editline 3
1297: library.
1298: It is enabled with the
1299: .Ic edit
1.9 millert 1300: command, and is enabled by default if input is from a tty.
1.6 millert 1301: Previous lines can be recalled and edited with the arrow keys,
1302: and other GNU Emacs-style editing keys may be used as well.
1303: .Pp
1304: The
1305: .Xr editline 3
1306: library is configured with a
1307: .Pa .editrc
1308: file - refer to
1309: .Xr editrc 5
1310: for more information.
1311: .Pp
1312: An extra key binding is available to
1313: .Nm
1314: to provide context sensitive command and filename completion
1315: (including remote file completion).
1316: To use this, bind a key to the
1317: .Xr editline 3
1318: command
1319: .Ic ftp-complete .
1320: By default, this is bound to the TAB key.
1.1 deraadt 1321: .Sh ENVIRONMENT
1.6 millert 1322: .Nm
1.1 deraadt 1323: utilizes the following environment variables.
1.6 millert 1324: .Bl -tag -width "http_proxy"
1.1 deraadt 1325: .It Ev HOME
1326: For default location of a
1327: .Pa .netrc
1328: file, if one exists.
1.9 millert 1329: .It Ev PAGER
1330: Used by
1331: .Ic page
1332: to display files.
1.1 deraadt 1333: .It Ev SHELL
1334: For default shell.
1.10 millert 1335: .It Ev ftp_proxy
1336: URL of FTP proxy to use when making FTP URL requests
1337: (if not defined, use the standard ftp protocol).
1.6 millert 1338: .It Ev http_proxy
1.10 millert 1339: URL of HTTP proxy to use when making HTTP URL requests.
1.1 deraadt 1340: .El
1341: .Sh SEE ALSO
1.6 millert 1342: .Xr editrc 5 ,
1.1 deraadt 1343: .Xr ftpd 8
1344: .Sh HISTORY
1345: The
1.6 millert 1346: .Nm
1.1 deraadt 1347: command appeared in
1348: .Bx 4.2 .
1349: .Sh BUGS
1350: Correct execution of many commands depends upon proper behavior
1351: by the remote server.
1352: .Pp
1353: An error in the treatment of carriage returns
1354: in the
1355: .Bx 4.2
1356: ascii-mode transfer code
1357: has been corrected.
1358: This correction may result in incorrect transfers of binary files
1359: to and from
1360: .Bx 4.2
1361: servers using the ascii type.
1362: 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