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