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