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