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