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