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