Annotation of src/usr.bin/ftp/ftp.1, Revision 1.75
1.75 ! deraadt 1: .\" $OpenBSD: ftp.1,v 1.74 2008/09/08 19:31:16 martynas Exp $
1.14 millert 2: .\" $NetBSD: ftp.1,v 1.22 1997/08/18 10:20:22 lukem Exp $
1.1 deraadt 3: .\"
4: .\" Copyright (c) 1985, 1989, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.39 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)ftp.1 8.3 (Berkeley) 10/9/94
32: .\"
1.75 ! deraadt 33: .Dd $Mdocdate: September 8 2008 $
1.1 deraadt 34: .Dt FTP 1
1.25 aaron 35: .Os
1.1 deraadt 36: .Sh NAME
37: .Nm ftp
1.42 jmc 38: .Nd ARPANET file transfer program
1.1 deraadt 39: .Sh SYNOPSIS
1.23 aaron 40: .Nm ftp
1.65 jmc 41: .Op Fl 46AadEegimnptVv
1.61 espie 42: .Op Fl k Ar seconds
1.6 millert 43: .Op Fl P Ar port
1.7 millert 44: .Op Fl r Ar seconds
1.75 ! deraadt 45: .Op Fl T Ar title
1.6 millert 46: .Op Ar host Op Ar port
1.3 deraadt 47: .Nm ftp
1.65 jmc 48: .Op Fl C
1.42 jmc 49: .Op Fl o Ar output
50: .Sm off
51: .No ftp:// Oo Ar user : password No @
52: .Oc Ar host Oo : Ar port
53: .Oc No / Ar file Oo /
54: .Oc
55: .Sm on
1.3 deraadt 56: .Nm ftp
1.65 jmc 57: .Op Fl C
58: .Op Fl c Ar cookie
1.42 jmc 59: .Op Fl o Ar output
60: .Sm off
61: .No http:// Ar host Oo : Ar port
62: .Oc No / Ar file
63: .Sm on
1.3 deraadt 64: .Nm ftp
1.65 jmc 65: .Op Fl C
66: .Op Fl c Ar cookie
1.42 jmc 67: .Op Fl o Ar output
68: .Sm off
1.54 deraadt 69: .No https:// Ar host Oo : Ar port
70: .Oc No / Ar file
71: .Sm on
72: .Nm ftp
1.65 jmc 73: .Op Fl C
1.54 deraadt 74: .Op Fl o Ar output
75: .Sm off
1.42 jmc 76: .Ar host : No / Ar file Oo /
77: .Oc
78: .Sm on
1.1 deraadt 79: .Sh DESCRIPTION
1.27 aaron 80: .Nm
1.1 deraadt 81: is the user interface to the
82: .Tn ARPANET
1.48 jmc 83: standard File Transfer Protocol (FTP).
1.1 deraadt 84: The program allows a user to transfer files to and from a
85: remote network site.
1.3 deraadt 86: .Pp
1.55 jmc 87: The latter four usage formats will fetch a file using either the
88: FTP, HTTP, or HTTPS protocols into the current directory.
1.29 aaron 89: This is ideal for scripts.
90: Refer to
1.9 millert 91: .Sx AUTO-FETCHING FILES
92: below for more information.
1.7 millert 93: .Pp
1.28 aaron 94: The options are as follows:
1.32 aaron 95: .Bl -tag -width Ds
1.42 jmc 96: .It Fl 4
97: Forces
98: .Nm
99: to use IPv4 addresses only.
100: .It Fl 6
101: Forces
102: .Nm
103: to use IPv6 addresses only.
1.16 millert 104: .It Fl A
1.48 jmc 105: Force active mode FTP.
1.29 aaron 106: By default,
1.16 millert 107: .Nm
1.48 jmc 108: will try to use passive mode FTP and fall back to active mode
1.29 aaron 109: if passive is not supported by the server.
110: This option causes
1.16 millert 111: .Nm
1.29 aaron 112: to always use an active connection.
113: It is only useful for connecting
1.16 millert 114: to very old servers that do not implement passive mode properly.
1.6 millert 115: .It Fl a
116: Causes
117: .Nm
1.22 aaron 118: to bypass the normal login procedure and use an anonymous login instead.
1.63 martynas 119: .It Fl C
1.65 jmc 120: Continue a previously interrupted file transfer.
1.64 jmc 121: .Nm
122: will continue transferring from an offset equal to the length of
123: .Ar file .
1.65 jmc 124: .Pp
1.64 jmc 125: Resuming HTTP(S) transfers are only supported
126: if the remote server supports the
127: .Dq Range
128: header.
1.60 jmc 129: .It Fl c Ar cookie
130: Load a Netscape-like cookiejar file
131: for HTTP and HTTPS transfers.
1.59 pyr 132: With this option relevant cookies from the jar are sent with each HTTP(S)
133: request.
1.60 jmc 134: Setting the
135: .Ev http_cookies
136: environment variable has the same effect.
137: If both the
138: .Ev http_cookies
139: environment variable is set and the
1.59 pyr 140: .Fl c
1.60 jmc 141: argument is given, the latter takes precedence.
1.6 millert 142: .It Fl d
143: Enables debugging.
1.53 fgsch 144: .It Fl E
145: Disables EPSV/EPRT command on IPv4 connections.
1.8 kstailey 146: .It Fl e
1.29 aaron 147: Disables command line editing.
148: Useful for Emacs ange-ftp.
1.6 millert 149: .It Fl g
150: Disables file name globbing.
151: .It Fl i
152: Turns off interactive prompting during
153: multiple file transfers.
1.61 espie 154: .It Fl k Ar seconds
1.67 jmc 155: When greater than zero,
1.66 espie 156: sends a byte after each
1.61 espie 157: .Ar seconds
158: period over the control connection during long transfers,
159: so that incorrectly configured network equipment won't
1.62 jmc 160: aggressively drop it.
1.61 espie 161: The FTP protocol supports a
162: .Dv NOOP
163: command that can be used for that purpose.
164: This assumes the FTP server can deal with extra commands coming over
165: the control connection during a transfer.
166: Well-behaved servers queue those commands, and process them after the
167: transfer.
1.68 espie 168: By default,
169: .Nm
170: will send a byte every 60 seconds.
1.20 millert 171: .It Fl m
172: Causes
173: .Nm
1.21 millert 174: to always display the progress meter in cases where it would not do
175: so by default.
1.1 deraadt 176: .It Fl n
177: Restrains
1.6 millert 178: .Nm
179: from attempting
180: .Dq auto-login
181: upon initial connection.
1.1 deraadt 182: If auto-login is enabled,
1.6 millert 183: .Nm
1.1 deraadt 184: will check the
185: .Pa .netrc
1.42 jmc 186: file (see below) in the user's home directory for an entry describing
1.1 deraadt 187: an account on the remote machine.
188: If no entry exists,
1.6 millert 189: .Nm
1.1 deraadt 190: will prompt for the remote machine login name (default is the user
191: identity on the local machine), and, if necessary, prompt for a password
1.47 jmc 192: and an account with which to log in.
1.17 millert 193: .It Fl o Ar output
1.42 jmc 194: When fetching a single file or URL, save the contents in
1.17 millert 195: .Ar output .
1.22 aaron 196: To make the contents go to stdout,
1.17 millert 197: use
1.48 jmc 198: .Sq -
1.17 millert 199: for
200: .Ar output .
1.42 jmc 201: .It Fl P Ar port
202: Sets the port number to
203: .Ar port .
1.6 millert 204: .It Fl p
205: Enable passive mode operation for use behind connection filtering firewalls.
1.16 millert 206: This option has been deprecated as
207: .Nm
208: now tries to use passive mode by default, falling back to active mode
209: if the server does not support passive connections.
1.42 jmc 210: .It Fl r Ar seconds
211: Retry to connect if failed, pausing for number of
212: .Ar seconds .
1.75 ! deraadt 213: .It Fl T Ar title
! 214: Set a filename
! 215: .Ar title
! 216: which will appear in the transfer progress bar.
1.6 millert 217: .It Fl t
218: Enables packet tracing.
1.42 jmc 219: .It Fl V
220: Disable verbose mode, overriding the default of enabled when input
221: is from a terminal.
1.6 millert 222: .It Fl v
223: Enable verbose mode.
224: This is the default if input is from a terminal.
225: Forces
226: .Nm
227: to show all responses from the remote server, as well
228: as report on data transfer statistics.
1.1 deraadt 229: .El
230: .Pp
1.43 jmc 231: The host with which
1.6 millert 232: .Nm
1.1 deraadt 233: is to communicate may be specified on the command line.
234: If this is done,
1.6 millert 235: .Nm
1.1 deraadt 236: will immediately attempt to establish a connection to an
1.48 jmc 237: FTP server on that host; otherwise,
1.6 millert 238: .Nm
1.1 deraadt 239: will enter its command interpreter and await instructions
240: from the user.
241: When
1.6 millert 242: .Nm
1.42 jmc 243: is awaiting commands, the prompt
1.51 jmc 244: .Dq ftp\*(Gt
1.1 deraadt 245: is provided to the user.
246: The following commands are recognized
247: by
1.48 jmc 248: .Nm :
1.1 deraadt 249: .Bl -tag -width Fl
1.73 sobrado 250: .It Ic \&! Oo Ar command
251: .Op Ar arg ...
252: .Oc
1.1 deraadt 253: Invoke an interactive shell on the local machine.
254: If there are arguments, the first is taken to be a command to execute
255: directly, with the rest of the arguments as its arguments.
1.73 sobrado 256: .It Ic \&$ Ar macro-name Op Ar arg ...
1.1 deraadt 257: Execute the macro
258: .Ar macro-name
259: that was defined with the
260: .Ic macdef
261: command.
262: Arguments are passed to the macro unglobbed.
1.42 jmc 263: .It Ic \&? Op Ar command
264: A synonym for
265: .Ic help .
1.73 sobrado 266: .It Ic account Op Ar password
1.1 deraadt 267: Supply a supplemental password required by a remote system for access
268: to resources once a login has been successfully completed.
269: If no argument is included, the user will be prompted for an account
270: password in a non-echoing input mode.
271: .It Ic append Ar local-file Op Ar remote-file
272: Append a local file to a file on the remote machine.
273: If
274: .Ar remote-file
275: is left unspecified, the local file name is used in naming the
276: remote file after being altered by any
277: .Ic ntrans
278: or
279: .Ic nmap
280: setting.
281: File transfer uses the current settings for
1.29 aaron 282: .Ic type ,
1.1 deraadt 283: .Ic format ,
1.29 aaron 284: .Ic mode ,
1.1 deraadt 285: and
286: .Ic structure .
287: .It Ic ascii
288: Set the file transfer
289: .Ic type
290: to network
291: .Tn ASCII .
1.73 sobrado 292: .It Ic bell Op Ic on | off
1.1 deraadt 293: Arrange that a bell be sounded after each file transfer
294: command is completed.
295: .It Ic binary
296: Set the file transfer
297: .Ic type
298: to support binary image transfer.
1.73 sobrado 299: This is the default type.
1.1 deraadt 300: .It Ic bye
1.48 jmc 301: Terminate the FTP session with the remote server and exit
302: .Nm .
1.22 aaron 303: An end-of-file will also terminate the session and exit.
1.73 sobrado 304: .It Ic case Op Ic on | off
1.1 deraadt 305: Toggle remote computer file name case mapping during
306: .Ic mget
307: commands.
308: When
309: .Ic case
310: is on (default is off), remote computer file names with all letters in
311: upper case are written in the local directory with the letters mapped
312: to lower case.
1.42 jmc 313: .It Ic cd Ar remote-directory
1.1 deraadt 314: Change the working directory on the remote machine
315: to
1.6 millert 316: .Ar remote-directory .
1.1 deraadt 317: .It Ic cdup
318: Change the remote machine working directory to the parent of the
319: current remote machine working directory.
1.73 sobrado 320: .It Ic chmod Ar mode file
321: Change the permission modes of
322: .Ar file
1.1 deraadt 323: on the remote
1.6 millert 324: system to
325: .Ar mode .
1.1 deraadt 326: .It Ic close
1.48 jmc 327: Terminate the FTP session with the remote server and
1.1 deraadt 328: return to the command interpreter.
329: Any defined macros are erased.
1.73 sobrado 330: .It Ic cr Op Ic on | off
1.1 deraadt 331: Toggle carriage return stripping during
1.22 aaron 332: ASCII type file retrieval.
1.1 deraadt 333: Records are denoted by a carriage return/linefeed sequence
1.22 aaron 334: during ASCII type file transfer.
1.1 deraadt 335: When
1.42 jmc 336: .Ic cr
1.1 deraadt 337: is on (the default), carriage returns are stripped from this
338: sequence to conform with the
339: .Ux
1.42 jmc 340: single linefeed record delimiter.
341: Records on non-UNIX
1.1 deraadt 342: remote systems may contain single linefeeds;
1.22 aaron 343: when an ASCII type transfer is made, these linefeeds may be
1.1 deraadt 344: distinguished from a record delimiter only when
1.42 jmc 345: .Ic cr
1.1 deraadt 346: is off.
1.73 sobrado 347: .It Ic debug Oo Ic on | off |
348: .Ar debuglevel
349: .Oc
1.1 deraadt 350: Toggle debugging mode.
351: If an optional
1.73 sobrado 352: .Ar debuglevel
1.42 jmc 353: is specified, it is used to set the debugging level.
1.1 deraadt 354: When debugging is on,
1.6 millert 355: .Nm
1.7 millert 356: prints each command sent to the remote machine,
357: preceded by the string
1.51 jmc 358: .Ql --\*(Gt .
1.42 jmc 359: .It Ic delete Ar remote-file
360: Delete the file
361: .Ar remote-file
362: on the remote machine.
1.6 millert 363: .It Ic dir Op Ar remote-directory Op Ar local-file
1.30 millert 364: A synonym for
365: .Ic ls .
1.1 deraadt 366: .It Ic disconnect
367: A synonym for
1.6 millert 368: .Ic close .
1.73 sobrado 369: .It Ic edit Op Ic on | off
1.6 millert 370: Toggle command line editing, and context sensitive command and file
371: completion.
372: This is automatically enabled if input is from a terminal, and
373: disabled otherwise.
1.73 sobrado 374: .It Ic epsv4 Op Ic on | off
1.31 itojun 375: Toggle use of EPSV/EPRT command on IPv4 connection.
1.6 millert 376: .It Ic exit
377: A synonym for
378: .Ic bye .
1.1 deraadt 379: .It Ic form Ar format
380: Set the file transfer
381: .Ic form
382: to
1.6 millert 383: .Ar format .
1.42 jmc 384: The default format is
385: .Dq file .
386: .It Ic ftp Ar host Op Ar port
387: A synonym for
388: .Ic open .
1.73 sobrado 389: .It Ic gate Oo Ic on | off |
390: .Ar host Op Ar port
391: .Oc
1.42 jmc 392: Toggle gate-ftp mode.
393: This will not be permitted if the gate-ftp server hasn't been set
394: (either explicitly by the user, or from the
395: .Ev FTPSERVER
396: environment variable).
397: If
398: .Ar host
399: is given,
400: then gate-ftp mode will be enabled, and the gate-ftp server will be set to
401: .Ar host .
402: If
403: .Ar port
404: is also given, that will be used as the port to connect to on the
405: gate-ftp server.
1.1 deraadt 406: .It Ic get Ar remote-file Op Ar local-file
407: Retrieve the
408: .Ar remote-file
409: and store it on the local machine.
410: If the local
411: file name is not specified, it is given the same
412: name it has on the remote machine, subject to
413: alteration by the current
1.29 aaron 414: .Ic case ,
1.1 deraadt 415: .Ic ntrans ,
416: and
417: .Ic nmap
418: settings.
419: The current settings for
1.29 aaron 420: .Ic type ,
1.1 deraadt 421: .Ic form ,
1.29 aaron 422: .Ic mode ,
1.1 deraadt 423: and
424: .Ic structure
425: are used while transferring the file.
1.73 sobrado 426: .It Ic glob Op Ic on | off
1.1 deraadt 427: Toggle filename expansion for
1.29 aaron 428: .Ic mdelete ,
1.1 deraadt 429: .Ic mget
430: and
1.6 millert 431: .Ic mput .
1.1 deraadt 432: If globbing is turned off with
1.29 aaron 433: .Ic glob ,
1.1 deraadt 434: the file name arguments
435: are taken literally and not expanded.
436: Globbing for
437: .Ic mput
438: is done as in
439: .Xr csh 1 .
440: For
441: .Ic mdelete
442: and
1.29 aaron 443: .Ic mget ,
1.1 deraadt 444: each remote file name is expanded
445: separately on the remote machine and the lists are not merged.
446: Expansion of a directory name is likely to be
447: different from expansion of the name of an ordinary file:
1.48 jmc 448: the exact result depends on the foreign operating system and FTP server,
1.1 deraadt 449: and can be previewed by doing
1.42 jmc 450: .Dq mls remote-files - .
1.1 deraadt 451: Note:
452: .Ic mget
453: and
454: .Ic mput
455: are not meant to transfer
456: entire directory subtrees of files.
457: That can be done by
458: transferring a
459: .Xr tar 1
460: archive of the subtree (in binary mode).
1.73 sobrado 461: .It Ic hash Oo Ic on | off |
462: .Ar size
463: .Oc
1.29 aaron 464: Toggle hash mark
465: .Pq Ql #
466: printing for each data block transferred.
1.5 kstailey 467: The size of a data block defaults to 1024 bytes.
1.6 millert 468: This can be changed by specifying
469: .Ar size
470: in bytes.
1.1 deraadt 471: .It Ic help Op Ar command
472: Print an informative message about the meaning of
1.6 millert 473: .Ar command .
1.1 deraadt 474: If no argument is given,
1.6 millert 475: .Nm
1.1 deraadt 476: prints a list of the known commands.
477: .It Ic idle Op Ar seconds
478: Set the inactivity timer on the remote server to
479: .Ar seconds
480: seconds.
481: If
482: .Ar seconds
483: is omitted, the current inactivity timer is printed.
1.73 sobrado 484: .It Ic lcd Op Ar local-directory
1.1 deraadt 485: Change the working directory on the local machine.
486: If
487: no
1.73 sobrado 488: .Ar local-directory
1.1 deraadt 489: is specified, the user's home directory is used.
1.10 millert 490: .It Ic less Ar file
491: A synonym for
492: .Ic page .
1.6 millert 493: .It Ic lpwd
494: Print the working directory on the local machine.
1.42 jmc 495: .It Ic ls Op Ar remote-directory Op Ar local-file
496: Print a listing of the contents of a directory on the remote machine.
1.30 millert 497: The listing includes any system-dependent information that the server
498: chooses to include; for example, most
499: .Ux
1.42 jmc 500: systems will produce output from the command
501: .Ql ls -l .
1.1 deraadt 502: If
503: .Ar remote-directory
504: is left unspecified, the current working directory is used.
505: If interactive prompting is on,
1.6 millert 506: .Nm
1.1 deraadt 507: will prompt the user to verify that the last argument is indeed the
508: target local file for receiving
1.6 millert 509: .Ic ls
1.1 deraadt 510: output.
511: If no local file is specified, or if
512: .Ar local-file
513: is
1.49 jmc 514: .Sq - ,
1.1 deraadt 515: the output is sent to the terminal.
516: .It Ic macdef Ar macro-name
517: Define a macro.
518: Subsequent lines are stored as the macro
1.29 aaron 519: .Ar macro-name ;
1.1 deraadt 520: a null line (consecutive newline characters
521: in a file or
522: carriage returns from the terminal) terminates macro input mode.
523: There is a limit of 16 macros and 4096 total characters in all
524: defined macros.
1.50 jmc 525: Macro names can be a maximum of 8 characters.
526: Macros are only applicable to the current session they are
527: defined in (or if defined outside a session, to the session
528: invoked with the next
529: .Ic open
530: command), and remain defined until a
1.1 deraadt 531: .Ic close
532: command is executed.
1.51 jmc 533: To invoke a macro,
1.52 jmc 534: use the
535: .Ic $
536: command (see above).
1.51 jmc 537: .Pp
1.29 aaron 538: The macro processor interprets
539: .Ql $
540: and
541: .Ql \e
542: as special characters.
543: A
544: .Ql $
545: followed by a number (or numbers) is replaced by the
1.1 deraadt 546: corresponding argument on the macro invocation command line.
1.29 aaron 547: A
548: .Ql $
549: followed by an
550: .Sq i
551: tells the macro processor that the
1.1 deraadt 552: executing macro is to be looped.
1.29 aaron 553: On the first pass
554: .Ql $i
555: is
1.1 deraadt 556: replaced by the first argument on the macro invocation command line,
557: on the second pass it is replaced by the second argument, and so on.
1.29 aaron 558: A
559: .Ql \e
560: followed by any character is replaced by that character.
561: Use the
562: .Ql \e
563: to prevent special treatment of the
564: .Ql $ .
1.1 deraadt 565: .It Ic mdelete Op Ar remote-files
566: Delete the
567: .Ar remote-files
568: on the remote machine.
569: .It Ic mdir Ar remote-files local-file
1.30 millert 570: A synonym for
571: .Ic mls .
1.70 martynas 572: .It Xo Ic mget
1.74 martynas 573: .Op Fl cnr
574: .Op Fl d Ar depth
1.70 martynas 575: .Ar remote-files
576: .Xc
1.1 deraadt 577: Expand the
578: .Ar remote-files
579: on the remote machine
580: and do a
581: .Ic get
582: for each file name thus produced.
583: See
584: .Ic glob
585: for details on the filename expansion.
586: Resulting file names will then be processed according to
1.29 aaron 587: .Ic case ,
1.1 deraadt 588: .Ic ntrans ,
589: and
590: .Ic nmap
591: settings.
592: Files are transferred into the local working directory,
593: which can be changed with
594: .Ql lcd directory ;
595: new local directories can be created with
596: .Ql "\&! mkdir directory" .
1.71 martynas 597: .Pp
1.74 martynas 598: The options are as follows:
599: .Bl -tag -width Ds
600: .It Fl c
601: Use
1.71 martynas 602: .Ic reget
1.74 martynas 603: instead of
1.71 martynas 604: .Ic get .
1.74 martynas 605: .It Fl d Ar depth
606: Specify the maximum recursion level
607: .Ar depth .
608: The default is 0, which means unlimited.
609: .It Fl n
610: Use
611: .Ic newer
612: instead of
613: .Ic get .
614: .It Fl r
615: Recursively descend the directory tree, transferring all files and
616: directories.
617: .El
1.1 deraadt 618: .It Ic mkdir Ar directory-name
619: Make a directory on the remote machine.
620: .It Ic mls Ar remote-files local-file
621: Like
1.29 aaron 622: .Ic ls ,
1.1 deraadt 623: except multiple remote files may be specified,
624: and the
625: .Ar local-file
626: must be specified.
627: If interactive prompting is on,
1.6 millert 628: .Nm
1.1 deraadt 629: will prompt the user to verify that the last argument is indeed the
630: target local file for receiving
631: .Ic mls
632: output.
633: .It Ic mode Op Ar mode-name
634: Set the file transfer
635: .Ic mode
636: to
1.6 millert 637: .Ar mode-name .
1.42 jmc 638: The default mode is
639: .Dq stream
640: mode.
1.73 sobrado 641: .It Ic modtime Ar file
642: Show the last modification time of
643: .Ar file
644: on the remote machine.
1.10 millert 645: .It Ic more Ar file
646: A synonym for
647: .Ic page .
1.70 martynas 648: .It Xo Ic mput
649: .Op Fl c
650: .Ar local-files
651: .Xc
1.1 deraadt 652: Expand wild cards in the list of local files given as arguments
653: and do a
654: .Ic put
655: for each file in the resulting list.
656: See
657: .Ic glob
658: for details of filename expansion.
659: Resulting file names will then be processed according to
660: .Ic ntrans
661: and
662: .Ic nmap
663: settings.
1.71 martynas 664: .Pp
665: If the
666: .Fl c
667: flag is specified then
668: .Ic reput
669: is used instead of
670: .Ic put .
1.73 sobrado 671: .It Xo Ic msend
672: .Op Fl c
673: .Ar local-files
674: .Xc
1.6 millert 675: A synonym for
676: .Ic mput .
1.73 sobrado 677: .It Ic newer Ar remote-file Op Ar local-file
1.1 deraadt 678: Get the file only if the modification time of the remote file is more
1.22 aaron 679: recent than the file on the current system.
1.1 deraadt 680: If the file does not
681: exist on the current system, the remote file is considered
1.6 millert 682: .Ic newer .
1.1 deraadt 683: Otherwise, this command is identical to
1.6 millert 684: .Ar get .
685: .It Ic nlist Op Ar remote-directory Op Ar local-file
1.30 millert 686: Print a list of the files in a
687: directory on the remote machine.
688: If
689: .Ar remote-directory
690: is left unspecified, the current working directory is used.
691: If interactive prompting is on,
692: .Nm
693: will prompt the user to verify that the last argument is indeed the
694: target local file for receiving
695: .Ic nlist
696: output.
697: If no local file is specified, or if
698: .Ar local-file
699: is
1.49 jmc 700: .Sq - ,
1.38 jmc 701: the output is sent to the terminal.
702: Note that on some servers, the
1.30 millert 703: .Ic nlist
704: command will only return information on normal files (not directories
705: or special files).
1.1 deraadt 706: .It Ic nmap Op Ar inpattern outpattern
707: Set or unset the filename mapping mechanism.
708: If no arguments are specified, the filename mapping mechanism is unset.
709: If arguments are specified, remote filenames are mapped during
710: .Ic mput
711: commands and
712: .Ic put
713: commands issued without a specified remote target filename.
714: If arguments are specified, local filenames are mapped during
715: .Ic mget
716: commands and
717: .Ic get
718: commands issued without a specified local target filename.
1.42 jmc 719: This command is useful when connecting to a non-UNIX remote computer
1.1 deraadt 720: with different file naming conventions or practices.
1.42 jmc 721: .Pp
1.1 deraadt 722: The mapping follows the pattern set by
723: .Ar inpattern
724: and
1.6 millert 725: .Ar outpattern .
1.22 aaron 726: .Ar inpattern
1.1 deraadt 727: is a template for incoming filenames (which may have already been
728: processed according to the
729: .Ic ntrans
730: and
731: .Ic case
732: settings).
733: Variable templating is accomplished by including the
1.29 aaron 734: sequences
735: .Ql $1 ,
736: .Ql $2 ,
1.44 jmc 737: \&...,
1.29 aaron 738: .Ql $9
739: in
1.6 millert 740: .Ar inpattern .
1.29 aaron 741: Use
742: .Ql \e
743: to prevent this special treatment of the
744: .Ql $
745: character.
1.1 deraadt 746: All other characters are treated literally, and are used to determine the
747: .Ic nmap
1.22 aaron 748: .Ar inpattern
1.1 deraadt 749: variable values.
1.45 jmc 750: .Pp
1.1 deraadt 751: For example, given
752: .Ar inpattern
753: $1.$2 and the remote file name "mydata.data", $1 would have the value
754: "mydata", and $2 would have the value "data".
755: The
756: .Ar outpattern
757: determines the resulting mapped filename.
1.29 aaron 758: The sequences
759: .Ql $1 ,
760: .Ql $2 ,
1.42 jmc 761: \&...,
1.29 aaron 762: .Ql $9
763: are replaced by any value resulting from the
1.1 deraadt 764: .Ar inpattern
765: template.
1.29 aaron 766: The sequence
767: .Ql $0
768: is replaced by the original filename.
1.1 deraadt 769: Additionally, the sequence
1.40 jmc 770: .Sq Op Ar seq1 , Ar seq2
1.1 deraadt 771: is replaced by
1.45 jmc 772: .Ar seq1
1.1 deraadt 773: if
774: .Ar seq1
775: is not a null string; otherwise it is replaced by
776: .Ar seq2 .
1.42 jmc 777: For example:
1.1 deraadt 778: .Pp
1.42 jmc 779: .Dl nmap $1.$2.$3 [$1,$2].[$2,file]
1.1 deraadt 780: .Pp
1.42 jmc 781: This command would yield the output filename
782: .Pa myfile.data
1.29 aaron 783: for input filenames
784: .Pa myfile.data
785: and
1.42 jmc 786: .Pa myfile.data.old ;
1.29 aaron 787: .Pa myfile.file
788: for the input filename
1.42 jmc 789: .Pa myfile ;
1.29 aaron 790: and
791: .Pa myfile.myfile
792: for the input filename
1.42 jmc 793: .Pa .myfile .
1.1 deraadt 794: Spaces may be included in
1.46 jmc 795: .Ar outpattern
796: by quoting them,
797: as in the following example:
1.42 jmc 798: .Bd -literal -offset indent
1.46 jmc 799: nmap $1.$2 "$1 $2"
1.29 aaron 800: .Ed
801: .Pp
802: Use the
803: .Ql \e
804: character to prevent special treatment
805: of the
806: .Ql $ ,
807: .Ql [ ,
808: .Ql \&] ,
809: and
810: .Ql \&,
811: characters.
1.1 deraadt 812: .It Ic ntrans Op Ar inchars Op Ar outchars
813: Set or unset the filename character translation mechanism.
814: If no arguments are specified, the filename character
815: translation mechanism is unset.
816: If arguments are specified, characters in
817: remote filenames are translated during
818: .Ic mput
819: commands and
820: .Ic put
821: commands issued without a specified remote target filename.
822: If arguments are specified, characters in
823: local filenames are translated during
824: .Ic mget
825: commands and
826: .Ic get
827: commands issued without a specified local target filename.
1.42 jmc 828: This command is useful when connecting to a non-UNIX remote computer
1.1 deraadt 829: with different file naming conventions or practices.
830: Characters in a filename matching a character in
831: .Ar inchars
832: are replaced with the corresponding character in
1.6 millert 833: .Ar outchars .
1.1 deraadt 834: If the character's position in
835: .Ar inchars
836: is longer than the length of
1.29 aaron 837: .Ar outchars ,
1.1 deraadt 838: the character is deleted from the file name.
839: .It Ic open Ar host Op Ar port
840: Establish a connection to the specified
841: .Ar host
1.48 jmc 842: FTP server.
1.42 jmc 843: An optional port number may be supplied,
1.22 aaron 844: in which case
1.6 millert 845: .Nm
1.48 jmc 846: will attempt to contact an FTP server at that port.
1.1 deraadt 847: If the
848: .Ic auto-login
849: option is on (default),
1.6 millert 850: .Nm
1.1 deraadt 851: will also attempt to automatically log the user in to
1.48 jmc 852: the FTP server (see below).
1.9 millert 853: .It Ic page Ar file
854: Retrieve
855: .Ic file
856: and display with the program defined in
1.25 aaron 857: .Ev PAGER
1.26 pjanzen 858: (defaulting to
859: .Xr more 1
860: if
861: .Ev PAGER
862: is null or not defined).
1.73 sobrado 863: .It Ic passive Op Ic on | off
1.29 aaron 864: Toggle passive mode.
1.48 jmc 865: If passive mode is turned on (default is on),
866: .Nm
867: will send a
1.57 jmc 868: .Dv EPSV
1.1 deraadt 869: command for all data connections instead of the usual
870: .Dv PORT
1.29 aaron 871: command.
872: The
1.1 deraadt 873: .Dv PASV
874: command requests that the remote server open a port for the data connection
1.29 aaron 875: and return the address of that port.
876: The remote server listens on that port and the client connects to it.
877: When using the more traditional
1.1 deraadt 878: .Dv PORT
879: command, the client listens on a port and sends that address to the remote
1.29 aaron 880: server, who connects back to it.
881: Passive mode is useful when using
1.6 millert 882: .Nm
1.1 deraadt 883: through a gateway router or host that controls the directionality of
884: traffic.
1.48 jmc 885: (Note that though FTP servers are required to support the
1.1 deraadt 886: .Dv PASV
887: command by RFC 1123, some do not.)
1.73 sobrado 888: .It Ic preserve Op Ic on | off
1.6 millert 889: Toggle preservation of modification times on retrieved files.
1.73 sobrado 890: .It Ic progress Op Ic on | off
1.6 millert 891: Toggle display of transfer progress bar.
1.9 millert 892: The progress bar will be disabled for a transfer that has
893: .Ar local-file
894: as
1.48 jmc 895: .Sq -
1.9 millert 896: or a command that starts with
897: .Sq \&| .
898: Refer to
899: .Sx FILE NAMING CONVENTIONS
900: for more information.
1.73 sobrado 901: .It Ic prompt Op Ic on | off
1.1 deraadt 902: Toggle interactive prompting.
903: Interactive prompting
904: occurs during multiple file transfers to allow the
905: user to selectively retrieve or store files.
906: If prompting is turned off (default is on), any
907: .Ic mget
908: or
909: .Ic mput
910: will transfer all files, and any
911: .Ic mdelete
912: will delete all files.
1.6 millert 913: .Pp
914: When prompting is on, the following commands are available at a prompt:
915: .Bl -tag -width 2n -offset indent
1.69 martynas 916: .It Ic ?\&
917: Print help message.
1.6 millert 918: .It Ic a
919: Answer
1.22 aaron 920: .Dq yes
921: to the current file and automatically answer
922: .Dq yes
1.6 millert 923: to any remaining files for the current command.
1.42 jmc 924: .It Ic n
925: Do not transfer the file.
1.6 millert 926: .It Ic p
927: Answer
1.22 aaron 928: .Dq yes
929: to the current file and turn off prompt mode
930: (as if
1.6 millert 931: .Dq prompt off
932: had been given).
1.69 martynas 933: .It Ic q
934: Answer
935: .Dq no
936: to the current file and automatically answer
937: .Dq no
938: to any remaining files for the current command.
1.42 jmc 939: .It Ic y
940: Transfer the file.
1.6 millert 941: .El
1.73 sobrado 942: .It Ic proxy Ar command
1.48 jmc 943: Execute an FTP command on a secondary control connection.
944: This command allows simultaneous connection to two remote FTP
1.1 deraadt 945: servers for transferring files between the two servers.
946: The first
947: .Ic proxy
948: command should be an
1.29 aaron 949: .Ic open ,
1.1 deraadt 950: to establish the secondary control connection.
1.29 aaron 951: Enter the command
1.41 jmc 952: .Ic proxy ?\&
1.48 jmc 953: to see other FTP commands executable on the
1.1 deraadt 954: secondary connection.
955: The following commands behave differently when prefaced by
1.29 aaron 956: .Ic proxy :
1.1 deraadt 957: .Ic open
1.42 jmc 958: will not define new macros during the auto-login process;
1.1 deraadt 959: .Ic close
1.42 jmc 960: will not erase existing macro definitions;
1.1 deraadt 961: .Ic get
962: and
963: .Ic mget
964: transfer files from the host on the primary control connection
1.42 jmc 965: to the host on the secondary control connection; and
1.29 aaron 966: .Ic put ,
1.1 deraadt 967: .Ic mput ,
968: and
969: .Ic append
970: transfer files from the host on the secondary control connection
971: to the host on the primary control connection.
1.48 jmc 972: Third party file transfers depend upon support of the FTP protocol
1.1 deraadt 973: .Dv PASV
974: command by the server on the secondary control connection.
975: .It Ic put Ar local-file Op Ar remote-file
976: Store a local file on the remote machine.
977: If
978: .Ar remote-file
979: is left unspecified, the local file name is used
980: after processing according to any
981: .Ic ntrans
982: or
983: .Ic nmap
984: settings
985: in naming the remote file.
986: File transfer uses the
987: current settings for
1.29 aaron 988: .Ic type ,
1.1 deraadt 989: .Ic format ,
1.29 aaron 990: .Ic mode ,
1.1 deraadt 991: and
1.6 millert 992: .Ic structure .
1.1 deraadt 993: .It Ic pwd
994: Print the name of the current working directory on the remote
995: machine.
996: .It Ic quit
997: A synonym for
1.6 millert 998: .Ic bye .
1.73 sobrado 999: .It Ic quote Ar arg ...
1.48 jmc 1000: The arguments specified are sent, verbatim, to the remote FTP server.
1.1 deraadt 1001: .It Ic recv Ar remote-file Op Ar local-file
1.6 millert 1002: A synonym for
1003: .Ic get .
1.1 deraadt 1004: .It Ic reget Ar remote-file Op Ar local-file
1005: Reget acts like get, except that if
1006: .Ar local-file
1007: exists and is
1008: smaller than
1.29 aaron 1009: .Ar remote-file ,
1.1 deraadt 1010: .Ar local-file
1011: is presumed to be
1012: a partially transferred copy of
1013: .Ar remote-file
1014: and the transfer
1015: is continued from the apparent point of failure.
1016: This command
1017: is useful when transferring very large files over networks that
1018: are prone to dropping connections.
1.73 sobrado 1019: .It Ic rename Ar from-name to-name
1.1 deraadt 1020: Rename the file
1.73 sobrado 1021: .Ar from-name
1.22 aaron 1022: on the remote machine to the file
1.73 sobrado 1023: .Ar to-name .
1.70 martynas 1024: .It Ic reput Ar local-file Op Ar remote-file
1025: Reput acts like put, except that if
1026: .Ar remote-file
1027: exists and is
1028: smaller than
1029: .Ar local-file ,
1030: .Ar remote-file
1031: is presumed to be
1032: a partially transferred copy of
1033: .Ar local-file
1034: and the transfer
1035: is continued from the apparent point of failure.
1036: This command
1037: is useful when transferring very large files over networks that
1038: are prone to dropping connections.
1.1 deraadt 1039: .It Ic reset
1040: Clear reply queue.
1041: This command re-synchronizes command/reply sequencing with the remote
1.48 jmc 1042: FTP server.
1043: Resynchronization may be necessary following a violation of the FTP protocol
1.1 deraadt 1044: by the remote server.
1045: .It Ic restart Ar marker
1046: Restart the immediately following
1047: .Ic get
1048: or
1049: .Ic put
1050: at the
1051: indicated
1.6 millert 1052: .Ar marker .
1.1 deraadt 1053: On
1054: .Ux
1.22 aaron 1055: systems,
1056: .Ar marker
1057: is usually a byte
1.1 deraadt 1058: offset into the file.
1.42 jmc 1059: .It Ic rhelp Op Ar command-name
1.48 jmc 1060: Request help from the remote FTP server.
1.42 jmc 1061: If a
1062: .Ar command-name
1063: is specified, it is supplied to the server as well.
1.1 deraadt 1064: .It Ic rmdir Ar directory-name
1065: Delete a directory on the remote machine.
1.73 sobrado 1066: .It Ic rstatus Op Ar file
1.42 jmc 1067: With no arguments, show status of remote machine.
1068: If
1.73 sobrado 1069: .Ar file
1.42 jmc 1070: is specified, show status of
1.73 sobrado 1071: .Ar file
1.42 jmc 1072: on remote machine.
1.73 sobrado 1073: .It Ic runique Op Ic on | off
1.1 deraadt 1074: Toggle storing of files on the local system with unique filenames.
1075: If a file already exists with a name equal to the target
1076: local filename for a
1077: .Ic get
1078: or
1079: .Ic mget
1.29 aaron 1080: command, a
1.42 jmc 1081: .Dq .1
1.29 aaron 1082: is appended to the name.
1.1 deraadt 1083: If the resulting name matches another existing file,
1.29 aaron 1084: a
1.42 jmc 1085: .Dq .2
1.29 aaron 1086: is appended to the original name.
1087: If this process continues up to
1.42 jmc 1088: .Dq .99 ,
1089: an error message is printed, and the transfer does not take place.
1.1 deraadt 1090: The generated unique filename will be reported.
1091: Note that
1092: .Ic runique
1093: will not affect local files generated from a shell command
1094: (see below).
1095: The default value is off.
1096: .It Ic send Ar local-file Op Ar remote-file
1.6 millert 1097: A synonym for
1098: .Ic put .
1.73 sobrado 1099: .It Ic sendport Op Ic on | off
1.1 deraadt 1100: Toggle the use of
1101: .Dv PORT
1102: commands.
1103: By default,
1.6 millert 1104: .Nm
1.1 deraadt 1105: will attempt to use a
1106: .Dv PORT
1107: command when establishing
1108: a connection for each data transfer.
1109: The use of
1110: .Dv PORT
1111: commands can prevent delays
1112: when performing multiple file transfers.
1113: If the
1114: .Dv PORT
1115: command fails,
1.6 millert 1116: .Nm
1.1 deraadt 1117: will use the default data port.
1118: When the use of
1119: .Dv PORT
1120: commands is disabled, no attempt will be made to use
1121: .Dv PORT
1122: commands for each data transfer.
1.48 jmc 1123: This is useful for certain FTP implementations which do ignore
1.1 deraadt 1124: .Dv PORT
1125: commands but, incorrectly, indicate they've been accepted.
1.73 sobrado 1126: .It Ic site Ar arg ...
1.48 jmc 1127: The arguments specified are sent, verbatim, to the remote FTP server as a
1.1 deraadt 1128: .Dv SITE
1129: command.
1.73 sobrado 1130: .It Ic size Ar file
1.1 deraadt 1131: Return size of
1.73 sobrado 1132: .Ar file
1.1 deraadt 1133: on remote machine.
1134: .It Ic status
1135: Show the current status of
1.48 jmc 1136: .Nm .
1.42 jmc 1137: .\" .It Ic struct Op Ar struct-name
1138: .\" Set the file transfer
1139: .\" .Ar structure
1140: .\" to
1141: .\" .Ar struct-name .
1142: .\" By default,
1143: .\" .Dq file
1144: .\" structure is used.
1.73 sobrado 1145: .It Ic sunique Op Ic on | off
1.1 deraadt 1146: Toggle storing of files on remote machine under unique file names.
1.48 jmc 1147: The remote FTP server must support the FTP protocol
1.1 deraadt 1148: .Dv STOU
1149: command for
1150: successful completion.
1.42 jmc 1151: The remote server will report the unique name.
1.1 deraadt 1152: Default value is off.
1153: .It Ic system
1154: Show the type of operating system running on the remote machine.
1155: .It Ic tenex
1156: Set the file transfer type to that needed to
1157: talk to
1158: .Tn TENEX
1159: machines.
1.73 sobrado 1160: .It Ic trace Op Ic on | off
1.1 deraadt 1161: Toggle packet tracing.
1162: .It Ic type Op Ar type-name
1163: Set the file transfer
1164: .Ic type
1165: to
1.6 millert 1166: .Ar type-name .
1.1 deraadt 1167: If no type is specified, the current type
1168: is printed.
1.42 jmc 1169: The default type is
1170: .Dq binary .
1.1 deraadt 1171: .It Ic umask Op Ar newmask
1172: Set the default umask on the remote server to
1.6 millert 1173: .Ar newmask .
1.1 deraadt 1174: If
1175: .Ar newmask
1176: is omitted, the current umask is printed.
1177: .It Xo
1.73 sobrado 1178: .Ic user Ar username
1.6 millert 1179: .Op Ar password Op Ar account
1.1 deraadt 1180: .Xc
1.48 jmc 1181: Identify yourself to the remote FTP server.
1.1 deraadt 1182: If the
1183: .Ar password
1184: is not specified and the server requires it,
1.6 millert 1185: .Nm
1.1 deraadt 1186: will prompt the user for it (after disabling local echo).
1187: If an
1188: .Ar account
1.48 jmc 1189: field is not specified, and the FTP server requires it,
1190: the user will be prompted for it.
1.1 deraadt 1191: If an
1192: .Ar account
1193: field is specified, an account command will
1194: be relayed to the remote server after the login sequence
1195: is completed if the remote server did not require it
1196: for logging in.
1197: Unless
1.6 millert 1198: .Nm
1.42 jmc 1199: is invoked with
1200: .Dq auto-login
1201: disabled, this process is done automatically on initial connection to the
1.48 jmc 1202: FTP server.
1.73 sobrado 1203: .It Ic verbose Op Ic on | off
1.1 deraadt 1204: Toggle verbose mode.
1205: In verbose mode, all responses from
1.48 jmc 1206: the FTP server are displayed to the user.
1.1 deraadt 1207: In addition,
1208: if verbose is on, when a file transfer completes, statistics
1209: regarding the efficiency of the transfer are reported.
1210: By default,
1211: verbose is on.
1212: .El
1213: .Pp
1214: Command arguments which have embedded spaces may be quoted with
1.29 aaron 1215: quote
1.42 jmc 1216: .Pq Ql \&"
1.29 aaron 1217: marks.
1.6 millert 1218: .Pp
1219: Commands which toggle settings can take an explicit
1220: .Ic on
1221: or
1222: .Ic off
1223: argument to force the setting appropriately.
1224: .Pp
1225: If
1226: .Nm
1227: receives a
1228: .Dv SIGINFO
1229: (see the
1230: .Dq status
1231: argument of
1232: .Xr stty 1 )
1233: signal whilst a transfer is in progress, the current transfer rate
1234: statistics will be written to the standard error output, in the
1235: same format as the standard completion message.
1236: .Sh AUTO-FETCHING FILES
1237: In addition to standard commands, this version of
1238: .Nm
1239: supports an auto-fetch feature.
1240: To enable auto-fetch, simply pass the list of hostnames/files
1241: on the command line.
1242: .Pp
1243: The following formats are valid syntax for an auto-fetch element:
1.56 ray 1244: .Bl -tag -width Ds
1.42 jmc 1245: .It host:/file[/]
1.6 millert 1246: .Dq Classic
1.48 jmc 1247: .Nm
1248: format.
1.42 jmc 1249: .It ftp://[user:password@]host[:port]/file[/]
1.48 jmc 1250: An FTP URL, retrieved using the FTP protocol if
1.10 millert 1251: .Ev ftp_proxy
1252: isn't defined.
1.48 jmc 1253: Otherwise, transfer using HTTP via the proxy defined in
1.10 millert 1254: .Ev ftp_proxy .
1.11 millert 1255: If
1.42 jmc 1256: .Ar user : Ns Ar password Ns @
1.11 millert 1257: is given and
1258: .Ev ftp_proxy
1.47 jmc 1259: isn't defined, log in as
1.11 millert 1260: .Ar user
1261: with a password of
1262: .Ar password .
1.6 millert 1263: .It http://host[:port]/file
1.48 jmc 1264: An HTTP URL, retrieved using the HTTP protocol.
1.6 millert 1265: If
1266: .Ev http_proxy
1267: is defined, it is used as a URL to an HTTP proxy server.
1.54 deraadt 1268: .It https://host[:port]/file
1269: An HTTPS URL, retrieved using the HTTPS protocol.
1270: If
1271: .Ev http_proxy
1272: is defined, this HTTPS proxy server will be used to fetch the
1273: file using the CONNECT method.
1.6 millert 1274: .El
1275: .Pp
1.48 jmc 1276: If a classic format or an FTP URL format has a trailing
1.6 millert 1277: .Sq / ,
1278: then
1279: .Nm
1280: will connect to the site and
1281: .Ic cd
1282: to the directory given as the path, and leave the user in interactive
1283: mode ready for further input.
1284: .Pp
1.48 jmc 1285: If successive auto-fetch FTP elements refer to the same host, then
1.6 millert 1286: the connection is maintained between transfers, reducing overhead on
1287: connection creation and deletion.
1.9 millert 1288: .Pp
1289: If
1.42 jmc 1290: .Ar file
1291: contains a glob character and globbing is enabled
1.9 millert 1292: (see
1.13 millert 1293: .Ic glob ) ,
1.9 millert 1294: then the equivalent of
1.42 jmc 1295: .Ic mget Ar file
1.9 millert 1296: is performed.
1297: .Pp
1.19 d 1298: If no
1299: .Fl o
1300: option is specified, and
1301: the directory component of
1.42 jmc 1302: .Ar file
1.9 millert 1303: contains no globbing characters,
1.19 d 1304: then
1.9 millert 1305: it is stored in the current directory as the
1306: .Xr basename 1
1307: of
1.42 jmc 1308: .Ar file .
1309: If
1310: .Fl o Ar output
1311: is specified, then
1312: .Ar file
1313: is stored as
1314: .Ar output .
1.9 millert 1315: Otherwise, the remote name is used as the local name.
1.1 deraadt 1316: .Sh ABORTING A FILE TRANSFER
1317: To abort a file transfer, use the terminal interrupt key
1318: (usually Ctrl-C).
1319: Sending transfers will be immediately halted.
1.48 jmc 1320: Receiving transfers will be halted by sending an FTP protocol
1.1 deraadt 1321: .Dv ABOR
1322: command to the remote server, and discarding any further data received.
1323: The speed at which this is accomplished depends upon the remote
1324: server's support for
1325: .Dv ABOR
1326: processing.
1327: If the remote server does not support the
1328: .Dv ABOR
1329: command, an
1.51 jmc 1330: .Ql ftp\*(Gt
1.1 deraadt 1331: prompt will not appear until the remote server has completed
1332: sending the requested file.
1333: .Pp
1334: The terminal interrupt key sequence will be ignored when
1.6 millert 1335: .Nm
1.1 deraadt 1336: has completed any local processing and is awaiting a reply
1337: from the remote server.
1338: A long delay in this mode may result from the ABOR processing described
1339: above, or from unexpected behavior by the remote server, including
1.48 jmc 1340: violations of the FTP protocol.
1.1 deraadt 1341: If the delay results from unexpected remote server behavior, the local
1.6 millert 1342: .Nm
1.1 deraadt 1343: program must be killed by hand.
1344: .Sh FILE NAMING CONVENTIONS
1345: Files specified as arguments to
1.6 millert 1346: .Nm
1.1 deraadt 1347: commands are processed according to the following rules.
1348: .Bl -enum
1349: .It
1350: If the file name
1.48 jmc 1351: .Sq -
1.29 aaron 1352: is specified, the standard input (for reading)
1353: or standard output (for writing)
1354: is used.
1.1 deraadt 1355: .It
1356: If the first character of the file name is
1357: .Sq \&| ,
1358: the
1359: remainder of the argument is interpreted as a shell command.
1.6 millert 1360: .Nm
1.1 deraadt 1361: then forks a shell, using
1362: .Xr popen 3
1.29 aaron 1363: with the argument supplied, and reads (writes) from the standard output
1364: (standard input).
1.1 deraadt 1365: If the shell command includes spaces, the argument
1.29 aaron 1366: must be quoted; e.g.,
1.42 jmc 1367: .Qq ls -lt .
1.1 deraadt 1368: A particularly
1.42 jmc 1369: useful example of this mechanism is:
1370: .Qq dir |more .
1.1 deraadt 1371: .It
1.29 aaron 1372: Failing the above checks, if
1373: .Dq globbing
1374: is enabled,
1.1 deraadt 1375: local file names are expanded
1376: according to the rules used in the
1.29 aaron 1377: .Xr csh 1 ;
1.1 deraadt 1378: c.f. the
1379: .Ic glob
1380: command.
1381: If the
1.6 millert 1382: .Nm
1.29 aaron 1383: command expects a single local file (e.g.,
1384: .Ic put ) ,
1385: only the first filename generated by the
1386: .Dq globbing
1387: operation is used.
1.1 deraadt 1388: .It
1389: For
1390: .Ic mget
1391: commands and
1392: .Ic get
1393: commands with unspecified local file names, the local filename is
1394: the remote filename, which may be altered by a
1.29 aaron 1395: .Ic case ,
1.1 deraadt 1396: .Ic ntrans ,
1397: or
1398: .Ic nmap
1399: setting.
1400: The resulting filename may then be altered if
1401: .Ic runique
1402: is on.
1403: .It
1404: For
1405: .Ic mput
1406: commands and
1407: .Ic put
1408: commands with unspecified remote file names, the remote filename is
1409: the local filename, which may be altered by a
1410: .Ic ntrans
1411: or
1412: .Ic nmap
1413: setting.
1414: The resulting filename may then be altered by the remote server if
1415: .Ic sunique
1416: is on.
1417: .El
1418: .Sh FILE TRANSFER PARAMETERS
1419: The FTP specification specifies many parameters which may
1420: affect a file transfer.
1421: The
1422: .Ic type
1.42 jmc 1423: may be one of
1424: .Dq ascii ,
1425: .Dq binary ,
1426: .Dq image ,
1427: .Dq ebcdic
1428: .Pq currently not supported
1429: or
1430: .Dq tenex
1431: (local byte size 8, for PDP-10's and PDP-20's mostly).
1.6 millert 1432: .Nm
1.38 jmc 1433: supports the ASCII and image types of file transfer,
1.1 deraadt 1434: plus local byte size 8 for
1435: .Ic tenex
1436: mode transfers.
1437: .Pp
1.6 millert 1438: .Nm
1.1 deraadt 1439: supports only the default values for the remaining
1440: file transfer parameters:
1.29 aaron 1441: .Ic mode ,
1.1 deraadt 1442: .Ic form ,
1443: and
1.6 millert 1444: .Ic struct .
1.1 deraadt 1445: .Sh THE .netrc FILE
1446: The
1447: .Pa .netrc
1448: file contains login and initialization information
1449: used by the auto-login process.
1450: It resides in the user's home directory.
1451: The following tokens are recognized; they may be separated by spaces,
1452: tabs, or new-lines:
1453: .Bl -tag -width password
1454: .It Ic machine Ar name
1455: Identify a remote machine
1456: .Ar name .
1457: The auto-login process searches the
1458: .Pa .netrc
1459: file for a
1460: .Ic machine
1461: token that matches the remote machine specified on the
1.6 millert 1462: .Nm
1.1 deraadt 1463: command line or as an
1464: .Ic open
1465: command argument.
1466: Once a match is made, the subsequent
1467: .Pa .netrc
1468: tokens are processed,
1469: stopping when the end of file is reached or another
1470: .Ic machine
1471: or a
1472: .Ic default
1473: token is encountered.
1474: .It Ic default
1475: This is the same as
1476: .Ic machine
1477: .Ar name
1478: except that
1479: .Ic default
1480: matches any name.
1481: There can be only one
1482: .Ic default
1483: token, and it must be after all
1484: .Ic machine
1485: tokens.
1486: This is normally used as:
1487: .Pp
1488: .Dl default login anonymous password user@site
1489: .Pp
1490: thereby giving the user
1491: .Ar automatic
1.48 jmc 1492: anonymous FTP login to
1.1 deraadt 1493: machines not specified in
1494: .Pa .netrc .
1495: This can be overridden
1496: by using the
1497: .Fl n
1498: flag to disable auto-login.
1499: .It Ic login Ar name
1500: Identify a user on the remote machine.
1501: If this token is present, the auto-login process will initiate
1502: a login using the specified
1503: .Ar name .
1504: .It Ic password Ar string
1505: Supply a password.
1506: If this token is present, the auto-login process will supply the
1507: specified string if the remote server requires a password as part
1508: of the login process.
1509: Note that if this token is present in the
1510: .Pa .netrc
1511: file for any user other
1512: than
1.29 aaron 1513: .Ar anonymous ,
1.6 millert 1514: .Nm
1.1 deraadt 1515: will abort the auto-login process if the
1516: .Pa .netrc
1517: is readable by
1518: anyone besides the user.
1519: .It Ic account Ar string
1520: Supply an additional account password.
1521: If this token is present, the auto-login process will supply the
1522: specified string if the remote server requires an additional
1523: account password, or the auto-login process will initiate an
1524: .Dv ACCT
1525: command if it does not.
1526: .It Ic macdef Ar name
1527: Define a macro.
1528: This token functions like the
1.6 millert 1529: .Nm
1.1 deraadt 1530: .Ic macdef
1531: command functions.
1532: A macro is defined with the specified name; its contents begin with the
1533: next
1534: .Pa .netrc
1535: line and continue until a null line (consecutive new-line
1536: characters) is encountered.
1.50 jmc 1537: Like the other tokens in the
1538: .Pa .netrc
1539: file, a
1540: .Ic macdef
1541: is applicable only to the
1542: .Ic machine
1543: definition preceding it.
1544: A
1545: .Ic macdef
1546: entry cannot be utilized by multiple
1547: .Ic machine
1548: definitions; rather, it must be defined following each
1549: .Ic machine
1550: it is intended to be used with.
1.1 deraadt 1551: If a macro named
1552: .Ic init
1553: is defined, it is automatically executed as the last step in the
1554: auto-login process.
1555: .El
1.6 millert 1556: .Sh COMMAND LINE EDITING
1557: .Nm
1.25 aaron 1558: supports interactive command line editing, via the
1.6 millert 1559: .Xr editline 3
1560: library.
1561: It is enabled with the
1562: .Ic edit
1.9 millert 1563: command, and is enabled by default if input is from a tty.
1.6 millert 1564: Previous lines can be recalled and edited with the arrow keys,
1565: and other GNU Emacs-style editing keys may be used as well.
1566: .Pp
1567: The
1568: .Xr editline 3
1569: library is configured with a
1570: .Pa .editrc
1.42 jmc 1571: file \- refer to
1.6 millert 1572: .Xr editrc 5
1573: for more information.
1574: .Pp
1575: An extra key binding is available to
1576: .Nm
1577: to provide context sensitive command and filename completion
1578: (including remote file completion).
1579: To use this, bind a key to the
1580: .Xr editline 3
1581: command
1582: .Ic ftp-complete .
1583: By default, this is bound to the TAB key.
1.1 deraadt 1584: .Sh ENVIRONMENT
1.6 millert 1585: .Nm
1.22 aaron 1586: utilizes the following environment variables:
1.15 millert 1587: .Bl -tag -width "FTPSERVERPORT"
1.16 millert 1588: .It Ev FTPMODE
1.29 aaron 1589: Overrides the default operation mode.
1590: Recognized values are:
1.48 jmc 1591: .Pp
1592: .Bl -tag -width "passive " -offset indent -compact
1.16 millert 1593: .It passive
1.48 jmc 1594: passive mode FTP only
1.16 millert 1595: .It active
1.48 jmc 1596: active mode FTP only
1.16 millert 1597: .It auto
1598: automatic determination of passive or active (this is the default)
1599: .It gate
1600: gate-ftp mode
1601: .El
1.14 millert 1602: .It Ev FTPSERVER
1603: Host to use as gate-ftp server when
1604: .Ic gate
1605: is enabled.
1606: .It Ev FTPSERVERPORT
1607: Port to use when connecting to gate-ftp server when
1608: .Ic gate
1609: is enabled.
1610: Default is port returned by a
1611: .Fn getservbyname
1.25 aaron 1612: lookup of
1.14 millert 1613: .Dq ftpgate/tcp .
1.1 deraadt 1614: .It Ev HOME
1615: For default location of a
1616: .Pa .netrc
1617: file, if one exists.
1.9 millert 1618: .It Ev PAGER
1619: Used by
1620: .Ic page
1621: to display files.
1.1 deraadt 1622: .It Ev SHELL
1623: For default shell.
1.15 millert 1624: .It Ev TMPDIR
1.72 martynas 1625: Directory in which temporary files are stored.
1.10 millert 1626: .It Ev ftp_proxy
1627: URL of FTP proxy to use when making FTP URL requests
1.48 jmc 1628: (if not defined, use the standard FTP protocol).
1.6 millert 1629: .It Ev http_proxy
1.54 deraadt 1630: URL of HTTP proxy to use when making HTTP or HTTPS URL requests.
1.59 pyr 1631: .It Ev http_cookies
1.60 jmc 1632: Path of a Netscape-like cookiejar file to use when making
1.59 pyr 1633: HTTP or HTTPS URL requests.
1.1 deraadt 1634: .El
1.36 jakob 1635: .Sh PORT ALLOCATION
1.38 jmc 1636: For active mode data connections,
1.36 jakob 1637: .Nm
1.42 jmc 1638: will listen to a random high TCP port.
1.36 jakob 1639: The interval of ports used are configurable using
1.38 jmc 1640: .Xr sysctl 8
1.36 jakob 1641: variables
1.42 jmc 1642: .Va net.inet.ip.porthifirst
1.36 jakob 1643: and
1.42 jmc 1644: .Va net.inet.ip.porthilast .
1.1 deraadt 1645: .Sh SEE ALSO
1.42 jmc 1646: .Xr basename 1 ,
1647: .Xr csh 1 ,
1648: .Xr more 1 ,
1649: .Xr stty 1 ,
1650: .Xr tar 1 ,
1.28 aaron 1651: .Xr tftp 1 ,
1.42 jmc 1652: .Xr editline 3 ,
1.14 millert 1653: .Xr getservbyname 3 ,
1.42 jmc 1654: .Xr popen 3 ,
1.6 millert 1655: .Xr editrc 5 ,
1.14 millert 1656: .Xr services 5 ,
1.34 beck 1657: .Xr ftp-proxy 8 ,
1.1 deraadt 1658: .Xr ftpd 8
1659: .Sh HISTORY
1660: The
1.6 millert 1661: .Nm
1.1 deraadt 1662: command appeared in
1663: .Bx 4.2 .
1664: .Sh BUGS
1665: Correct execution of many commands depends upon proper behavior
1666: by the remote server.
1667: .Pp
1668: An error in the treatment of carriage returns
1669: in the
1670: .Bx 4.2
1.22 aaron 1671: ASCII-mode transfer code
1.1 deraadt 1672: has been corrected.
1673: This correction may result in incorrect transfers of binary files
1674: to and from
1675: .Bx 4.2
1.22 aaron 1676: servers using the ASCII type.
1.1 deraadt 1677: Avoid this problem by using the binary image type.
1.71 martynas 1678: .Pp
1679: In the recursive mode of
1680: .Ic mget ,
1681: files and directories starting with whitespace are ignored
1682: because the list cannot be parsed any other way.
![[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