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