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