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