Annotation of src/usr.bin/ftp/ftp.1, Revision 1.18
1.18 ! lukem 1: .\" $NetBSD: ftp.1,v 1.17 1997/02/01 10:45:01 lukem Exp $
1.11 tls 2: .\"
1.6 cgd 3: .\" Copyright (c) 1985, 1989, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.1 cgd 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: .\"
1.11 tls 34: .\" @(#)ftp.1 8.3 (Berkeley) 10/9/94
1.1 cgd 35: .\"
1.18 ! lukem 36: .Dd February 23, 1997
1.1 cgd 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.16 lukem 45: .Nm
1.12 lukem 46: .Op Fl a
1.11 tls 47: .Op Fl d
1.18 ! lukem 48: .Op Fl e
1.12 lukem 49: .Op Fl g
1.11 tls 50: .Op Fl i
51: .Op Fl n
1.12 lukem 52: .Op Fl p
53: .Op Fl P Ar port
54: .Op Fl t
55: .Op Fl v
1.17 lukem 56: .Op Fl V
1.12 lukem 57: .Op Ar host Op Ar port
58: .Nm ftp
1.16 lukem 59: ftp://\fIhost\fR[:\fIport\fR]/\fIfile\fR[/]
1.12 lukem 60: .Nm ftp
1.16 lukem 61: http://\fIhost\fR[:\fIport\fR]/\fIfile\fR
1.12 lukem 62: .Nm ftp
1.18 ! lukem 63: \fIhost\fR:[/\fIpath\fR/]\fIfile\fR[/]
1.1 cgd 64: .Sh DESCRIPTION
1.12 lukem 65: .Nm
1.1 cgd 66: is the user interface to the
67: .Tn ARPANET
68: standard File Transfer Protocol.
69: The program allows a user to transfer files to and from a
70: remote network site.
71: .Pp
1.18 ! lukem 72: The latter three usage formats will fetch a file using either the
! 73: HTTP or FTP protocols into the current directory.
! 74: This is ideal for scripts.
! 75: Refer to
! 76: .Sx AUTO-FETCHING FILES
! 77: below for more information.
! 78: .Pp
1.1 cgd 79: Options may be specified at the command line, or to the
80: command interpreter.
1.12 lukem 81: .Bl -tag -width "port "
82: .It Fl a
83: Causes
84: .Nm
85: to bypass normal login procedure, and use an anonymous login instead.
86: .It Fl d
87: Enables debugging.
1.18 ! lukem 88: .It Fl e
! 89: Disables command line editing.
1.12 lukem 90: .It Fl g
91: Disables file name globbing.
92: .It Fl i
93: Turns off interactive prompting during
94: multiple file transfers.
1.1 cgd 95: .It Fl n
96: Restrains
1.12 lukem 97: .Nm
1.16 lukem 98: from attempting
99: .Dq auto-login
100: upon initial connection.
1.1 cgd 101: If auto-login is enabled,
1.12 lukem 102: .Nm
1.1 cgd 103: will check the
104: .Pa .netrc
105: (see below) file in the user's home directory for an entry describing
106: an account on the remote machine.
107: If no entry exists,
1.12 lukem 108: .Nm
1.1 cgd 109: will prompt for the remote machine login name (default is the user
110: identity on the local machine), and, if necessary, prompt for a password
111: and an account with which to login.
1.12 lukem 112: .It Fl p
113: Enable passive mode operation for use behind connection filtering firewalls.
114: .It Fl P Ar port
115: Sets the port number to
116: .Ar port .
117: .It Fl t
118: Enables packet tracing.
119: .It Fl v
1.17 lukem 120: Enable verbose mode.
121: This is the default if input is from a terminal.
122: Forces
1.12 lukem 123: .Nm
124: to show all responses from the remote server, as well
125: as report on data transfer statistics.
1.17 lukem 126: .It Fl V
127: Disable verbose mode, overriding the default of enabled when input
128: is from a terminal.
1.1 cgd 129: .El
130: .Pp
131: The client host with which
1.12 lukem 132: .Nm
1.1 cgd 133: is to communicate may be specified on the command line.
134: If this is done,
1.12 lukem 135: .Nm
1.1 cgd 136: will immediately attempt to establish a connection to an
137: .Tn FTP
138: server on that host; otherwise,
1.12 lukem 139: .Nm
1.1 cgd 140: will enter its command interpreter and await instructions
141: from the user.
142: When
1.12 lukem 143: .Nm
1.1 cgd 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.13 lukem 201: .Nm ftp .
1.1 cgd 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.13 lukem 215: .Ar remote-directory .
1.1 cgd 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.12 lukem 223: system to
1.13 lukem 224: .Ar mode .
1.1 cgd 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.12 lukem 260: .Nm
1.1 cgd 261: prints each command sent to the remote machine, preceded
262: by the string
263: .Ql \-\->
1.15 lukem 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 cgd 278: If interactive prompting is on,
1.12 lukem 279: .Nm
1.1 cgd 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.15 lukem 284: If no local file is specified, or if
1.1 cgd 285: .Ar local-file
286: is
1.15 lukem 287: .Sq Fl ,
288: the output is sent to the terminal.
1.1 cgd 289: .It Ic disconnect
290: A synonym for
1.13 lukem 291: .Ic close .
1.16 lukem 292: .It Ic edit
293: Toggle command line editing, and context sensitive command and file
294: completion.
1.17 lukem 295: This is automatically enabled if input is from a terminal, and
1.16 lukem 296: disabled otherwise.
1.13 lukem 297: .It Ic exit
298: A synonym for
299: .Ic bye .
1.12 lukem 300: .It Ic ftp Ar host Op Ar port
1.13 lukem 301: A synonym for
302: .Ic open .
1.1 cgd 303: .It Ic form Ar format
304: Set the file transfer
305: .Ic form
306: to
1.13 lukem 307: .Ar format .
1.1 cgd 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.13 lukem 334: .Ic mput .
1.1 cgd 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.12 lukem 364: .It Ic hash Op Ar size
1.1 cgd 365: Toggle hash-sign (``#'') printing for each data block
366: transferred.
1.12 lukem 367: The size of a data block defaults to 1024 bytes.
368: This can be changed by specifying
369: .Ar size
370: in bytes.
1.1 cgd 371: .It Ic help Op Ar command
372: Print an informative message about the meaning of
1.13 lukem 373: .Ar command .
1.1 cgd 374: If no argument is given,
1.12 lukem 375: .Nm
1.1 cgd 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
1.4 jtc 383: is omitted, the current inactivity timer is printed.
1.1 cgd 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.13 lukem 390: .It Ic lpwd
391: Print the working directory on the local machine.
1.15 lukem 392: .It Ic \&ls Op Ar remote-directory Op Ar local-file
393: Print a list of the files in a
1.1 cgd 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.12 lukem 399: .Nm
1.1 cgd 400: will prompt the user to verify that the last argument is indeed the
401: target local file for receiving
1.15 lukem 402: .Ic ls
1.1 cgd 403: output.
404: If no local file is specified, or if
405: .Ar local-file
406: is
1.15 lukem 407: .Fl ,
1.1 cgd 408: the output is sent to the terminal.
1.7 cgd 409: .It Ic macdef Ar macro-name
1.1 cgd 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.12 lukem 440: .Nm
1.1 cgd 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.15 lukem 470: .Ic ls ,
1.1 cgd 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.12 lukem 476: .Nm
1.1 cgd 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.13 lukem 485: .Ar mode-name .
1.1 cgd 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.13 lukem 502: .It Ic msend Ar local-files
503: A synonym for
504: .Ic mput .
1.1 cgd 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.13 lukem 510: .Ic newer .
1.1 cgd 511: Otherwise, this command is identical to
1.13 lukem 512: .Ar get .
1.15 lukem 513: .It Ic nlist Op Ar remote-directory Op Ar local-file
514: A synonym for
515: .Ic ls .
1.1 cgd 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.13 lukem 536: .Ar outpattern .
1.1 cgd 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.13 lukem 546: .Ar inpattern .
1.1 cgd 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.13 lukem 610: .Ar outchars .
1.1 cgd 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.12 lukem 623: .Nm
1.1 cgd 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.12 lukem 630: .Nm
1.1 cgd 631: will also attempt to automatically log the user in to
632: the
633: .Tn FTP
634: server (see below).
1.18 ! lukem 635: .It Ic page Ar file
! 636: Retrieve
! 637: .Ic file
! 638: and display with the program defined in
! 639: .Ev PAGER
! 640: (which defaults to
! 641: .Xr less 1 ).
1.8 cgd 642: .It Ic passive
643: Toggle passive mode. If passive mode is turned on
644: (default is off), the ftp client will
645: send a
646: .Dv PASV
647: command for all data connections instead of the usual
648: .Dv PORT
649: command. The
650: .Dv PASV
651: command requests that the remote server open a port for the data connection
652: and return the address of that port. The remote server listens on that
653: port and the client connects to it. When using the more traditional
654: .Dv PORT
655: command, the client listens on a port and sends that address to the remote
656: server, who connects back to it. Passive mode is useful when using
1.12 lukem 657: .Nm
1.8 cgd 658: through a gateway router or host that controls the directionality of
659: traffic.
660: (Note that though ftp servers are required to support the
661: .Dv PASV
662: command by RFC 1123, some do not.)
1.13 lukem 663: .It Ic preserve
1.14 lukem 664: Toggle preservation of modification times on retrieved files.
665: .It Ic progress
666: Toggle display of transfer progress bar.
1.18 ! lukem 667: The progress bar will be disabled for a transfer that has
! 668: .Ar local-file
! 669: as
! 670: .Sq Fl
! 671: or a command that starts with
! 672: .Sq \&| .
! 673: Refer to
! 674: .Sx FILE NAMING CONVENTIONS
! 675: for more information.
1.1 cgd 676: .It Ic prompt
677: Toggle interactive prompting.
678: Interactive prompting
679: occurs during multiple file transfers to allow the
680: user to selectively retrieve or store files.
681: If prompting is turned off (default is on), any
682: .Ic mget
683: or
684: .Ic mput
685: will transfer all files, and any
686: .Ic mdelete
687: will delete all files.
1.13 lukem 688: .Pp
689: When prompting is on, the following commands are available at a prompt:
1.16 lukem 690: .Bl -tag -width 2n -offset indent
1.13 lukem 691: .It Ic n
692: Do not transfer the file.
693: .It Ic a
694: Answer
695: .Sq yes
696: to the current file, and automatically answer
697: .Sq yes
698: to any remaining files for the current command.
699: .It Ic p
700: Answer
1.14 lukem 701: .Sq yes
1.13 lukem 702: to the current file, and turn off prompt mode
703: (as is
704: .Dq prompt off
705: had been given).
706: .El
707: .Pp
708: Any other reponse will answer
709: .Sq yes
710: to the current file.
1.1 cgd 711: .It Ic proxy Ar ftp-command
712: Execute an ftp command on a secondary control connection.
713: This command allows simultaneous connection to two remote ftp
714: servers for transferring files between the two servers.
715: The first
716: .Ic proxy
717: command should be an
718: .Ic open ,
719: to establish the secondary control connection.
720: Enter the command "proxy ?" to see other ftp commands executable on the
721: secondary connection.
722: The following commands behave differently when prefaced by
723: .Ic proxy :
724: .Ic open
725: will not define new macros during the auto-login process,
726: .Ic close
727: will not erase existing macro definitions,
728: .Ic get
729: and
730: .Ic mget
731: transfer files from the host on the primary control connection
732: to the host on the secondary control connection, and
733: .Ic put ,
734: .Ic mput ,
735: and
736: .Ic append
737: transfer files from the host on the secondary control connection
738: to the host on the primary control connection.
739: Third party file transfers depend upon support of the ftp protocol
740: .Dv PASV
741: command by the server on the secondary control connection.
742: .It Ic put Ar local-file Op Ar remote-file
743: Store a local file on the remote machine.
744: If
745: .Ar remote-file
746: is left unspecified, the local file name is used
747: after processing according to any
748: .Ic ntrans
749: or
750: .Ic nmap
751: settings
752: in naming the remote file.
753: File transfer uses the
754: current settings for
755: .Ic type ,
756: .Ic format ,
757: .Ic mode ,
758: and
1.13 lukem 759: .Ic structure .
1.1 cgd 760: .It Ic pwd
761: Print the name of the current working directory on the remote
762: machine.
763: .It Ic quit
764: A synonym for
1.13 lukem 765: .Ic bye .
1.1 cgd 766: .It Ic quote Ar arg1 arg2 ...
767: The arguments specified are sent, verbatim, to the remote
768: .Tn FTP
769: server.
770: .It Ic recv Ar remote-file Op Ar local-file
1.13 lukem 771: A synonym for
772: .Ic get .
1.1 cgd 773: .It Ic reget Ar remote-file Op Ar local-file
774: Reget acts like get, except that if
775: .Ar local-file
776: exists and is
777: smaller than
778: .Ar remote-file ,
779: .Ar local-file
780: is presumed to be
781: a partially transferred copy of
782: .Ar remote-file
783: and the transfer
784: is continued from the apparent point of failure.
785: This command
786: is useful when transferring very large files over networks that
787: are prone to dropping connections.
788: .It Ic remotehelp Op Ar command-name
789: Request help from the remote
790: .Tn FTP
791: server.
792: If a
793: .Ar command-name
794: is specified it is supplied to the server as well.
1.16 lukem 795: .It Ic rstatus Op Ar file-name
1.1 cgd 796: With no arguments, show status of remote machine.
797: If
798: .Ar file-name
799: is specified, show status of
800: .Ar file-name
801: on remote machine.
1.15 lukem 802: .It Ic rename Op Ar from Op Ar to
1.1 cgd 803: Rename the file
804: .Ar from
805: on the remote machine, to the file
1.13 lukem 806: .Ar to .
1.1 cgd 807: .It Ic reset
808: Clear reply queue.
809: This command re-synchronizes command/reply sequencing with the remote
810: ftp server.
811: Resynchronization may be necessary following a violation of the ftp protocol
812: by the remote server.
813: .It Ic restart Ar marker
814: Restart the immediately following
815: .Ic get
816: or
817: .Ic put
818: at the
819: indicated
1.13 lukem 820: .Ar marker .
1.1 cgd 821: On
822: .Ux
823: systems, marker is usually a byte
824: offset into the file.
825: .It Ic rmdir Ar directory-name
826: Delete a directory on the remote machine.
827: .It Ic runique
828: Toggle storing of files on the local system with unique filenames.
829: If a file already exists with a name equal to the target
830: local filename for a
831: .Ic get
832: or
833: .Ic mget
834: command, a ".1" is appended to the name.
835: If the resulting name matches another existing file,
836: a ".2" is appended to the original name.
837: If this process continues up to ".99", an error
838: message is printed, and the transfer does not take place.
839: The generated unique filename will be reported.
840: Note that
841: .Ic runique
842: will not affect local files generated from a shell command
843: (see below).
844: The default value is off.
845: .It Ic send Ar local-file Op Ar remote-file
1.13 lukem 846: A synonym for
847: .Ic put .
1.1 cgd 848: .It Ic sendport
849: Toggle the use of
850: .Dv PORT
851: commands.
852: By default,
1.12 lukem 853: .Nm
1.1 cgd 854: will attempt to use a
855: .Dv PORT
856: command when establishing
857: a connection for each data transfer.
858: The use of
859: .Dv PORT
860: commands can prevent delays
861: when performing multiple file transfers.
862: If the
863: .Dv PORT
864: command fails,
1.12 lukem 865: .Nm
1.1 cgd 866: will use the default data port.
867: When the use of
868: .Dv PORT
869: commands is disabled, no attempt will be made to use
870: .Dv PORT
871: commands for each data transfer.
872: This is useful
873: for certain
874: .Tn FTP
875: implementations which do ignore
876: .Dv PORT
877: commands but, incorrectly, indicate they've been accepted.
878: .It Ic site Ar arg1 arg2 ...
879: The arguments specified are sent, verbatim, to the remote
880: .Tn FTP
881: server as a
882: .Dv SITE
883: command.
884: .It Ic size Ar file-name
885: Return size of
886: .Ar file-name
887: on remote machine.
888: .It Ic status
889: Show the current status of
1.13 lukem 890: .Nm ftp .
1.1 cgd 891: .It Ic struct Op Ar struct-name
892: Set the file transfer
893: .Ar structure
894: to
895: .Ar struct-name .
896: By default \*(Lqstream\*(Rq structure is used.
897: .It Ic sunique
898: Toggle storing of files on remote machine under unique file names.
899: Remote ftp server must support ftp protocol
900: .Dv STOU
901: command for
902: successful completion.
903: The remote server will report unique name.
904: Default value is off.
905: .It Ic system
906: Show the type of operating system running on the remote machine.
907: .It Ic tenex
908: Set the file transfer type to that needed to
909: talk to
910: .Tn TENEX
911: machines.
912: .It Ic trace
913: Toggle packet tracing.
914: .It Ic type Op Ar type-name
915: Set the file transfer
916: .Ic type
917: to
1.13 lukem 918: .Ar type-name .
1.1 cgd 919: If no type is specified, the current type
920: is printed.
921: The default type is network
922: .Tn ASCII .
923: .It Ic umask Op Ar newmask
924: Set the default umask on the remote server to
1.13 lukem 925: .Ar newmask .
1.1 cgd 926: If
927: .Ar newmask
1.6 cgd 928: is omitted, the current umask is printed.
1.1 cgd 929: .It Xo
930: .Ic user Ar user-name
1.15 lukem 931: .Op Ar password Op Ar account
1.1 cgd 932: .Xc
933: Identify yourself to the remote
934: .Tn FTP
935: server.
936: If the
937: .Ar password
938: is not specified and the server requires it,
1.12 lukem 939: .Nm
1.1 cgd 940: will prompt the user for it (after disabling local echo).
941: If an
942: .Ar account
943: field is not specified, and the
944: .Tn FTP
945: server
946: requires it, the user will be prompted for it.
947: If an
948: .Ar account
949: field is specified, an account command will
950: be relayed to the remote server after the login sequence
951: is completed if the remote server did not require it
952: for logging in.
953: Unless
1.12 lukem 954: .Nm
1.1 cgd 955: is invoked with \*(Lqauto-login\*(Rq disabled, this
956: process is done automatically on initial connection to
957: the
958: .Tn FTP
959: server.
960: .It Ic verbose
961: Toggle verbose mode.
962: In verbose mode, all responses from
963: the
964: .Tn FTP
965: server are displayed to the user.
966: In addition,
967: if verbose is on, when a file transfer completes, statistics
968: regarding the efficiency of the transfer are reported.
969: By default,
970: verbose is on.
971: .It Ic ? Op Ar command
1.13 lukem 972: A synonym for
973: .Ic help .
1.1 cgd 974: .El
975: .Pp
976: Command arguments which have embedded spaces may be quoted with
977: quote `"' marks.
1.12 lukem 978: .Pp
1.13 lukem 979: Commands which toggle settings can take an explicit
980: .Ic on
981: or
982: .Ic off
983: argument to force the setting appropriately.
984: .Pp
1.12 lukem 985: If
986: .Nm
987: receives a
988: .Dv SIGINFO
989: (see the
990: .Dq status
1.16 lukem 991: argument of
1.12 lukem 992: .Xr stty 1 )
993: signal whilst a transfer is in progress, the current transfer rate
994: statistics will be written to the standard error output, in the
995: same format as the standard completion message.
1.16 lukem 996: .Sh AUTO-FETCHING FILES
997: In addition to standard commands, this version of
998: .Nm
999: supports an auto-fetch feature.
1000: To enable auto-fetch, simply pass the list of hostnames/files
1001: on the command line.
1002: .Pp
1003: The following formats are valid syntax for an auto-fetch element:
1004: .Bl -tag -width "http://host[:port]/file"
1005: .It host:/file
1006: .Dq Classic
1007: ftp format
1008: .It ftp://host[:port]/file
1009: FTP URL, using the ftp protocol.
1010: .It http://host[:port]/file
1011: HTTP URL, using the http protocol.
1012: If
1013: .Ev http_proxy
1014: is defined, it is used as a URL to an HTTP proxy server.
1015: .El
1016: .Pp
1017: If a classic format or a ftp URL format has a trailing
1018: .Sq / ,
1019: then
1020: .Nm
1021: will connect to the site and
1022: .Ic cd
1023: to the directory given as the path, and leave the user in interactive
1024: mode ready for further input.
1025: .Pp
1026: If successive auto-fetch ftp elements refer to the same host, then
1027: the connection is maintained between transfers, reducing overhead on
1028: connection creation and deletion.
1.18 ! lukem 1029: .Pp
! 1030: If
! 1031: .Ic file
! 1032: contains a glob character and globbing is enabled,
! 1033: (see
! 1034: .Ic glob ),
! 1035: then the equivalent of
! 1036: .Ic "mget file"
! 1037: is performed.
! 1038: .Pp
! 1039: If the directory component of
! 1040: .Ic file
! 1041: contains no globbing characters,
! 1042: it is stored in the current directory as the
! 1043: .Xr basename 1
! 1044: of
! 1045: .Ic file .
! 1046: Otherwise, the remote name is used as the local name.
1.1 cgd 1047: .Sh ABORTING A FILE TRANSFER
1048: To abort a file transfer, use the terminal interrupt key
1049: (usually Ctrl-C).
1050: Sending transfers will be immediately halted.
1051: Receiving transfers will be halted by sending a ftp protocol
1052: .Dv ABOR
1053: command to the remote server, and discarding any further data received.
1054: The speed at which this is accomplished depends upon the remote
1055: server's support for
1056: .Dv ABOR
1057: processing.
1058: If the remote server does not support the
1059: .Dv ABOR
1060: command, an
1061: .Ql ftp>
1062: prompt will not appear until the remote server has completed
1063: sending the requested file.
1064: .Pp
1065: The terminal interrupt key sequence will be ignored when
1.12 lukem 1066: .Nm
1.1 cgd 1067: has completed any local processing and is awaiting a reply
1068: from the remote server.
1069: A long delay in this mode may result from the ABOR processing described
1070: above, or from unexpected behavior by the remote server, including
1071: violations of the ftp protocol.
1072: If the delay results from unexpected remote server behavior, the local
1.12 lukem 1073: .Nm
1.1 cgd 1074: program must be killed by hand.
1075: .Sh FILE NAMING CONVENTIONS
1076: Files specified as arguments to
1.12 lukem 1077: .Nm
1.1 cgd 1078: commands are processed according to the following rules.
1079: .Bl -enum
1080: .It
1081: If the file name
1082: .Sq Fl
1083: is specified, the
1084: .Ar stdin
1085: (for reading) or
1086: .Ar stdout
1087: (for writing) is used.
1088: .It
1089: If the first character of the file name is
1090: .Sq \&| ,
1091: the
1092: remainder of the argument is interpreted as a shell command.
1.12 lukem 1093: .Nm
1.1 cgd 1094: then forks a shell, using
1095: .Xr popen 3
1096: with the argument supplied, and reads (writes) from the stdout
1097: (stdin).
1098: If the shell command includes spaces, the argument
1099: must be quoted; e.g.
1100: \*(Lq" ls -lt"\*(Rq.
1101: A particularly
1.16 lukem 1102: useful example of this mechanism is: \*(Lqdir \&|more\*(Rq.
1.1 cgd 1103: .It
1104: Failing the above checks, if ``globbing'' is enabled,
1105: local file names are expanded
1106: according to the rules used in the
1107: .Xr csh 1 ;
1108: c.f. the
1109: .Ic glob
1110: command.
1111: If the
1.12 lukem 1112: .Nm
1.1 cgd 1113: command expects a single local file (.e.g.
1114: .Ic put ) ,
1115: only the first filename generated by the "globbing" operation is used.
1116: .It
1117: For
1118: .Ic mget
1119: commands and
1120: .Ic get
1121: commands with unspecified local file names, the local filename is
1122: the remote filename, which may be altered by a
1123: .Ic case ,
1124: .Ic ntrans ,
1125: or
1126: .Ic nmap
1127: setting.
1128: The resulting filename may then be altered if
1129: .Ic runique
1130: is on.
1131: .It
1132: For
1133: .Ic mput
1134: commands and
1135: .Ic put
1136: commands with unspecified remote file names, the remote filename is
1137: the local filename, which may be altered by a
1138: .Ic ntrans
1139: or
1140: .Ic nmap
1141: setting.
1142: The resulting filename may then be altered by the remote server if
1143: .Ic sunique
1144: is on.
1145: .El
1146: .Sh FILE TRANSFER PARAMETERS
1147: The FTP specification specifies many parameters which may
1148: affect a file transfer.
1149: The
1150: .Ic type
1151: may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary),
1152: \*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for
1153: .Tn PDP Ns -10's
1154: and
1155: .Tn PDP Ns -20's
1156: mostly).
1.12 lukem 1157: .Nm
1.1 cgd 1158: supports the ascii and image types of file transfer,
1159: plus local byte size 8 for
1160: .Ic tenex
1161: mode transfers.
1162: .Pp
1.12 lukem 1163: .Nm
1.1 cgd 1164: supports only the default values for the remaining
1165: file transfer parameters:
1166: .Ic mode ,
1167: .Ic form ,
1168: and
1.13 lukem 1169: .Ic struct .
1.1 cgd 1170: .Sh THE .netrc FILE
1171: The
1172: .Pa .netrc
1173: file contains login and initialization information
1174: used by the auto-login process.
1175: It resides in the user's home directory.
1176: The following tokens are recognized; they may be separated by spaces,
1177: tabs, or new-lines:
1178: .Bl -tag -width password
1179: .It Ic machine Ar name
1180: Identify a remote machine
1181: .Ar name .
1182: The auto-login process searches the
1183: .Pa .netrc
1184: file for a
1185: .Ic machine
1186: token that matches the remote machine specified on the
1.12 lukem 1187: .Nm
1.1 cgd 1188: command line or as an
1189: .Ic open
1190: command argument.
1191: Once a match is made, the subsequent
1192: .Pa .netrc
1193: tokens are processed,
1194: stopping when the end of file is reached or another
1195: .Ic machine
1196: or a
1197: .Ic default
1198: token is encountered.
1199: .It Ic default
1200: This is the same as
1201: .Ic machine
1202: .Ar name
1203: except that
1204: .Ic default
1205: matches any name.
1206: There can be only one
1207: .Ic default
1208: token, and it must be after all
1209: .Ic machine
1210: tokens.
1211: This is normally used as:
1212: .Pp
1213: .Dl default login anonymous password user@site
1214: .Pp
1215: thereby giving the user
1216: .Ar automatic
1217: anonymous ftp login to
1218: machines not specified in
1219: .Pa .netrc .
1220: This can be overridden
1221: by using the
1222: .Fl n
1223: flag to disable auto-login.
1224: .It Ic login Ar name
1225: Identify a user on the remote machine.
1226: If this token is present, the auto-login process will initiate
1227: a login using the specified
1228: .Ar name .
1229: .It Ic password Ar string
1230: Supply a password.
1231: If this token is present, the auto-login process will supply the
1232: specified string if the remote server requires a password as part
1233: of the login process.
1234: Note that if this token is present in the
1235: .Pa .netrc
1236: file for any user other
1237: than
1238: .Ar anonymous ,
1.12 lukem 1239: .Nm
1.1 cgd 1240: will abort the auto-login process if the
1241: .Pa .netrc
1242: is readable by
1243: anyone besides the user.
1244: .It Ic account Ar string
1245: Supply an additional account password.
1246: If this token is present, the auto-login process will supply the
1247: specified string if the remote server requires an additional
1248: account password, or the auto-login process will initiate an
1249: .Dv ACCT
1250: command if it does not.
1251: .It Ic macdef Ar name
1252: Define a macro.
1253: This token functions like the
1.12 lukem 1254: .Nm
1.1 cgd 1255: .Ic macdef
1256: command functions.
1257: A macro is defined with the specified name; its contents begin with the
1258: next
1259: .Pa .netrc
1260: line and continue until a null line (consecutive new-line
1261: characters) is encountered.
1262: If a macro named
1263: .Ic init
1264: is defined, it is automatically executed as the last step in the
1265: auto-login process.
1266: .El
1.16 lukem 1267: .Sh COMMAND LINE EDITING
1268: .Nm
1269: supports interactive command line editing, via the
1270: .Xr editline 3
1271: library.
1272: It is enabled with the
1273: .Ic edit
1.18 ! lukem 1274: command, and is enabled by default if input is from a tty.
1.16 lukem 1275: Previous lines can be recalled and edited with the arrow keys,
1276: and other GNU Emacs-style editing keys may be used as well.
1277: .Pp
1278: The
1279: .Xr editline 3
1280: library is configured with a
1281: .Pa .editrc
1282: file - refer to
1283: .Xr editrc 5
1284: for more information.
1285: .Pp
1286: An extra key binding is available to
1287: .Nm
1288: to provide context sensitive command and filename completion
1289: (including remote file completion).
1290: To use this, bind a key to the
1291: .Xr editline 3
1292: command
1293: .Ic ftp-complete .
1294: By default, this is bound to the TAB key.
1.1 cgd 1295: .Sh ENVIRONMENT
1.12 lukem 1296: .Nm
1.1 cgd 1297: utilizes the following environment variables.
1.16 lukem 1298: .Bl -tag -width "http_proxy"
1.1 cgd 1299: .It Ev HOME
1300: For default location of a
1301: .Pa .netrc
1302: file, if one exists.
1.18 ! lukem 1303: .It Ev PAGER
! 1304: Used by
! 1305: .Ic page
! 1306: to display files.
1.1 cgd 1307: .It Ev SHELL
1308: For default shell.
1.16 lukem 1309: .It Ev http_proxy
1310: URL of HTTP proxy to use when making HTTP requests.
1.1 cgd 1311: .El
1312: .Sh SEE ALSO
1.16 lukem 1313: .Xr editrc 5 ,
1.1 cgd 1314: .Xr ftpd 8
1315: .Sh HISTORY
1316: The
1.12 lukem 1317: .Nm
1.1 cgd 1318: command appeared in
1319: .Bx 4.2 .
1.16 lukem 1320: .Pp
1321: Various features such as command line editing, context sensitive
1322: command and file completion, dynamic progress bar, automatic
1323: fetching of files, ftp and http URLs, and modification time
1324: preservation were implemented in
1.18 ! lukem 1325: .Nx 1.3
1.16 lukem 1326: by Luke Mewburn, with assistance from Jason Thorpe.
1.1 cgd 1327: .Sh BUGS
1328: Correct execution of many commands depends upon proper behavior
1329: by the remote server.
1330: .Pp
1331: An error in the treatment of carriage returns
1332: in the
1333: .Bx 4.2
1334: ascii-mode transfer code
1335: has been corrected.
1336: This correction may result in incorrect transfers of binary files
1337: to and from
1338: .Bx 4.2
1339: servers using the ascii type.
1340: Avoid this problem by using the binary image type.
CVSweb <webmaster@jp.NetBSD.org>
![[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 [cvs.NetBSD.org] / src / usr.bin / ftp