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