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