xref: /netbsd/usr.bin/ftp/ftp.1 (revision c4a72b64)
1.\" 	$NetBSD: ftp.1,v 1.88 2002/10/02 15:56:27 wiz Exp $
2.\"
3.\" Copyright (c) 1996-2002 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Luke Mewburn.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"	This product includes software developed by the NetBSD
20.\"	Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.\"
38.\" Copyright (c) 1985, 1989, 1990, 1993
39.\"	The Regents of the University of California.  All rights reserved.
40.\"
41.\" Redistribution and use in source and binary forms, with or without
42.\" modification, are permitted provided that the following conditions
43.\" are met:
44.\" 1. Redistributions of source code must retain the above copyright
45.\"    notice, this list of conditions and the following disclaimer.
46.\" 2. Redistributions in binary form must reproduce the above copyright
47.\"    notice, this list of conditions and the following disclaimer in the
48.\"    documentation and/or other materials provided with the distribution.
49.\" 3. All advertising materials mentioning features or use of this software
50.\"    must display the following acknowledgement:
51.\"	This product includes software developed by the University of
52.\"	California, Berkeley and its contributors.
53.\" 4. Neither the name of the University nor the names of its contributors
54.\"    may be used to endorse or promote products derived from this software
55.\"    without specific prior written permission.
56.\"
57.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
58.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
60.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
61.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
62.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
63.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
65.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
66.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
67.\" SUCH DAMAGE.
68.\"
69.\"	@(#)ftp.1	8.3 (Berkeley) 10/9/94
70.\"
71.Dd July 7, 2002
72.Dt FTP 1
73.Os
74.Sh NAME
75.Nm ftp
76.Nd
77Internet file transfer program
78.Sh SYNOPSIS
79.Nm ""
80.Op Fl 46AadefginpRtvV
81.Bk -words
82.Op Fl N Ar netrc
83.Ek
84.Bk -words
85.Op Fl o Ar output
86.Ek
87.Bk -words
88.Op Fl P Ar port
89.Ek
90.Bk -words
91.Op Fl q Ar quittime
92.Ek
93.Bk -words
94.Op Fl r Ar retry
95.Ek
96.Bk -words
97.\" [-T dir,max[,inc]]
98.Oo
99.Fl T Xo
100.Sm off
101.Ar dir ,
102.Ar max
103.Op , Ar inc
104.Sm on
105.Xc
106.Oc
107.Ek
108.Bk -words
109.\" [[user@]host [port]]
110.Oo
111.Oo Ar user Ns Li \&@ Oc Ns Ar host
112.Op Ar port
113.Oc
114.Ek
115.Bk -words
116.\" [[user@]host:[path][/]]
117.Sm off
118.Oo
119.Op Ar user Li \&@
120.Ar host Li \&:
121.Op Ar path
122.Op Li /
123.Oc
124.Sm on
125.Ek
126.Bk -words
127.\" [file:///path]
128.Sm off
129.Oo
130.Li file:/// Ar path
131.Oc
132.Sm on
133.Ek
134.Bk -words
135.\" [ftp://[user[:password]@]host[:port]/path[/]]
136.Sm off
137.Oo
138.Li ftp://
139.Oo Ar user
140.Op Li \&: Ar password
141.Li \&@ Oc
142.Ar host Oo Li \&: Ar port Oc
143.Li / Ar path
144.Op Li /
145.Op Li ;type= Ar X
146.Oc
147.Sm on
148.Ek
149.Bk -words
150.\" [http://[user[:password]@]host[:port]/path]
151.Sm off
152.Oo
153.Li http://
154.Oo Ar user
155.Op Li \&: Ar password
156.Li \&@ Oc
157.Ar host Oo Li \&: Ar port Oc
158.Li / Ar path
159.Oc
160.Sm on
161.Ek
162.Op Ar \&.\&.\&.
163.Nm ""
164.Bk -words
165.Fl u Ar url Ar file
166.Ek
167.Op Ar \&.\&.\&.
168.Sh DESCRIPTION
169.Nm
170is the user interface to the Internet standard File Transfer Protocol.
171The program allows a user to transfer files to and from a
172remote network site.
173.Pp
174The last five arguments will fetch a file using the
175.Tn FTP
176or
177.Tn HTTP
178protocols, or by direct copying, into the current directory.
179This is ideal for scripts.
180Refer to
181.Sx AUTO-FETCHING FILES
182below for more information.
183.Pp
184Options may be specified at the command line, or to the
185command interpreter.
186.Bl -tag -width "port   "
187.It Fl 4
188Forces
189.Nm
190to only use IPv4 addresses.
191.It Fl 6
192Forces
193.Nm
194to only use IPv6 addresses.
195.It Fl A
196Force active mode ftp.
197By default,
198.Nm
199will try to use passive mode ftp and fall back to active mode
200if passive is not supported by the server.
201This option causes
202.Nm
203to always use an active connection.
204It is only useful for connecting to very old servers that do not
205implement passive mode properly.
206.It Fl a
207Causes
208.Nm
209to bypass normal login procedure, and use an anonymous login instead.
210.It Fl d
211Enables debugging.
212.It Fl e
213Disables command line editing.
214This is useful for Emacs ange-ftp mode.
215.It Fl f
216Forces a cache reload for transfers that go through the
217.Tn FTP
218or
219.Tn HTTP
220proxies.
221.It Fl g
222Disables file name globbing.
223.It Fl i
224Turns off interactive prompting during
225multiple file transfers.
226.It Fl n
227Restrains
228.Nm
229from attempting
230.Dq auto-login
231upon initial connection.
232If auto-login is enabled,
233.Nm
234will check the
235.Pa .netrc
236(see below) file in the user's home directory for an entry describing
237an account on the remote machine.
238If no entry exists,
239.Nm
240will prompt for the remote machine login name (default is the user
241identity on the local machine), and, if necessary, prompt for a password
242and an account with which to login.
243.It Fl N Ar netrc
244Use
245.Ar netrc
246instead of
247.Pa ~/.netrc .
248Refer to
249.Sx THE .netrc FILE
250for more information.
251.It Fl o Ar output
252When auto-fetching files, save the contents in
253.Ar output .
254.Ar output
255is parsed according to the
256.Sx FILE NAMING CONVENTIONS
257below.
258If
259.Ar output
260is not
261.Sq -
262or doesn't start with
263.Sq \&| ,
264then only the first file specified will be retrieved into
265.Ar output ;
266all other files will be retrieved into the basename of their
267remote name.
268.It Fl p
269Enable passive mode operation for use behind connection filtering firewalls.
270This option has been deprecated as
271.Nm
272now tries to use passive mode by default, falling back to active mode
273if the server does not support passive connections.
274.It Fl P Ar port
275Sets the port number to
276.Ar port .
277.It Fl r Ar wait
278Retry the connection attempt if it failed, pausing for
279.Ar wait
280seconds.
281.It Fl q Ar quittime
282Quit if the connection has stalled for
283.Ar quittime
284seconds.
285.It Fl R
286Restart all non-proxied auto-fetches.
287.It Fl t
288Enables packet tracing.
289.It Xo
290.Fl T
291.Sm off
292.Ar direction ,
293.Ar maximum
294.Op , Ar increment
295.Sm on
296.Xc
297Set the maximum transfer rate for
298.Ar direction
299to
300.Ar maximum
301bytes/second,
302and if specified, the increment to
303.Ar increment
304bytes/second.
305Refer to
306.Ic rate
307for more information.
308.It Fl u Ar url file Op \&.\&.\&.
309Upload files on the command line to
310.Ar url
311where
312.Ar url
313is one of the ftp URL types as supported by auto-fetch
314(with an optional target filename for single file uploads), and
315.Ar file
316is one or more local files to be uploaded.
317.It Fl v
318Enable
319.Ic verbose
320and
321.Ic progress .
322This is the default if output is to a terminal (and in the case of
323.Ic progress ,
324.Nm
325is the foreground process).
326Forces
327.Nm
328to show all responses from the remote server, as well
329as report on data transfer statistics.
330.It Fl V
331Disable
332.Ic verbose
333and
334.Ic progress ,
335overriding the default of enabled when output is to a terminal.
336.El
337.Pp
338The client host with which
339.Nm
340is to communicate may be specified on the command line.
341If this is done,
342.Nm
343will immediately attempt to establish a connection to an
344.Tn FTP
345server on that host; otherwise,
346.Nm
347will enter its command interpreter and await instructions
348from the user.
349When
350.Nm
351is awaiting commands from the user the prompt
352.Ql ftp\*[Gt]
353is provided to the user.
354The following commands are recognized
355by
356.Nm ftp  :
357.Bl -tag -width Fl
358.It Ic \&! Op Ar command Op Ar args
359Invoke an interactive shell on the local machine.
360If there are arguments, the first is taken to be a command to execute
361directly, with the rest of the arguments as its arguments.
362.It Ic \&$ Ar macro-name Op Ar args
363Execute the macro
364.Ar macro-name
365that was defined with the
366.Ic macdef
367command.
368Arguments are passed to the macro unglobbed.
369.It Ic account Op Ar passwd
370Supply a supplemental password required by a remote system for access
371to resources once a login has been successfully completed.
372If no argument is included, the user will be prompted for an account
373password in a non-echoing input mode.
374.It Ic append Ar local-file Op Ar remote-file
375Append a local file to a file on the remote machine.
376If
377.Ar remote-file
378is left unspecified, the local file name is used in naming the
379remote file after being altered by any
380.Ic ntrans
381or
382.Ic nmap
383setting.
384File transfer uses the current settings for
385.Ic type  ,
386.Ic format ,
387.Ic mode  ,
388and
389.Ic structure .
390.It Ic ascii
391Set the file transfer
392.Ic type
393to network
394.Tn ASCII .
395This is the default type.
396.It Ic bell
397Arrange that a bell be sounded after each file transfer
398command is completed.
399.It Ic binary
400Set the file transfer
401.Ic type
402to support binary image transfer.
403.It Ic bye
404Terminate the
405.Tn FTP
406session with the remote server
407and exit
408.Nm ftp .
409An end of file will also terminate the session and exit.
410.It Ic case
411Toggle remote computer file name case mapping during
412.Ic get ,
413.Ic mget
414and
415.Ic mput
416commands.
417When
418.Ic case
419is on (default is off), remote computer file names with all letters in
420upper case are written in the local directory with the letters mapped
421to lower case.
422.It Ic \&cd Ar remote-directory
423Change the working directory on the remote machine
424to
425.Ar remote-directory .
426.It Ic cdup
427Change the remote machine working directory to the parent of the
428current remote machine working directory.
429.It Ic chmod Ar mode remote-file
430Change the permission modes of the file
431.Ar remote-file
432on the remote
433system to
434.Ar mode .
435.It Ic close
436Terminate the
437.Tn FTP
438session with the remote server, and
439return to the command interpreter.
440Any defined macros are erased.
441.It Ic \&cr
442Toggle carriage return stripping during
443ascii type file retrieval.
444Records are denoted by a carriage return/linefeed sequence
445during ascii type file transfer.
446When
447.Ic \&cr
448is on (the default), carriage returns are stripped from this
449sequence to conform with the
450.Ux
451single linefeed record
452delimiter.
453Records on
454.Pf non\- Ns Ux
455remote systems may contain single linefeeds;
456when an ascii type transfer is made, these linefeeds may be
457distinguished from a record delimiter only when
458.Ic \&cr
459is off.
460.It Ic debug Op Ar debug-value
461Toggle debugging mode.
462If an optional
463.Ar debug-value
464is specified it is used to set the debugging level.
465When debugging is on,
466.Nm
467prints each command sent to the remote machine, preceded
468by the string
469.Ql \-\-\*[Gt]
470.It Ic delete Ar remote-file
471Delete the file
472.Ar remote-file
473on the remote machine.
474.It Ic dir Op Ar remote-path Op Ar local-file
475Print a listing of the contents of a
476directory on the remote machine.
477The listing includes any system-dependent information that the server
478chooses to include; for example, most
479.Ux
480systems will produce
481output from the command
482.Ql ls \-l .
483If
484.Ar remote-path
485is left unspecified, the current working directory is used.
486If interactive prompting is on,
487.Nm
488will prompt the user to verify that the last argument is indeed the
489target local file for receiving
490.Ic dir
491output.
492If no local file is specified, or if
493.Ar local-file
494is
495.Sq Fl ,
496the output is sent to the terminal.
497.It Ic disconnect
498A synonym for
499.Ic close .
500.It Ic edit
501Toggle command line editing, and context sensitive command and file
502completion.
503This is automatically enabled if input is from a terminal, and
504disabled otherwise.
505.It Ic epsv4
506Toggle the use of the extended
507.Dv EPSV
508and
509.Dv EPRT
510commands on IPv4 connections; first try
511.Dv EPSV /
512.Dv EPRT ,
513and then
514.Dv PASV /
515.Dv PORT .
516This is enabled by default.
517If an extended command fails then this option will be temporarily
518disabled for the duration of the current connection, or until
519.Ic epsv4
520is executed again.
521.It Ic exit
522A synonym for
523.Ic bye .
524.It Ic features
525Display what features the remote server supports (using the
526.Dv FEAT
527command).
528.It Ic fget Ar localfile
529Retrieve the files listed in
530.Ar localfile ,
531which has one line per filename.
532.It Ic form Ar format
533Set the file transfer
534.Ic form
535to
536.Ar format .
537The default (and only supported)
538format is
539.Dq non-print .
540.It Ic ftp Ar host Op Ar port
541A synonym for
542.Ic open .
543.It Ic gate Op Ar host Op Ar port
544Toggle gate-ftp mode, which used to connect through the
545TIS FWTK and Gauntlet ftp proxies.
546This will not be permitted if the gate-ftp server hasn't been set
547(either explicitly by the user, or from the
548.Ev FTPSERVER
549environment variable).
550If
551.Ar host
552is given,
553then gate-ftp mode will be enabled, and the gate-ftp server will be set to
554.Ar host .
555If
556.Ar port
557is also given, that will be used as the port to connect to on the
558gate-ftp server.
559.It Ic get Ar remote-file Op Ar local-file
560Retrieve the
561.Ar remote-file
562and store it on the local machine.
563If the local
564file name is not specified, it is given the same
565name it has on the remote machine, subject to
566alteration by the current
567.Ic case  ,
568.Ic ntrans ,
569and
570.Ic nmap
571settings.
572The current settings for
573.Ic type  ,
574.Ic form ,
575.Ic mode  ,
576and
577.Ic structure
578are used while transferring the file.
579.It Ic glob
580Toggle filename expansion for
581.Ic mdelete  ,
582.Ic mget ,
583.Ic mput ,
584and
585.Ic mreget .
586If globbing is turned off with
587.Ic glob  ,
588the file name arguments
589are taken literally and not expanded.
590Globbing for
591.Ic mput
592is done as in
593.Xr csh 1 .
594For
595.Ic mdelete ,
596.Ic mget ,
597and
598.Ic mreget ,
599each remote file name is expanded
600separately on the remote machine and the lists are not merged.
601Expansion of a directory name is likely to be
602different from expansion of the name of an ordinary file:
603the exact result depends on the foreign operating system and ftp server,
604and can be previewed by doing
605.Ql mls remote-files \-
606Note:
607.Ic mget ,
608.Ic mput
609and
610.Ic mreget
611are not meant to transfer
612entire directory subtrees of files.
613That can be done by
614transferring a
615.Xr tar 1
616archive of the subtree (in binary mode).
617.It Ic hash Op Ar size
618Toggle hash-sign (``#'') printing for each data block
619transferred.
620The size of a data block defaults to 1024 bytes.
621This can be changed by specifying
622.Ar size
623in bytes.
624Enabling
625.Ic hash
626disables
627.Ic progress .
628.It Ic help Op Ar command
629Print an informative message about the meaning of
630.Ar command .
631If no argument is given,
632.Nm
633prints a list of the known commands.
634.It Ic idle Op Ar seconds
635Set the inactivity timer on the remote server to
636.Ar seconds
637seconds.
638If
639.Ar seconds
640is omitted, the current inactivity timer is printed.
641.It Ic image
642A synonym for
643.Ic binary .
644.It Ic lcd Op Ar directory
645Change the working directory on the local machine.
646If
647no
648.Ar directory
649is specified, the user's home directory is used.
650.It Ic less Ar file
651A synonym for
652.Ic page .
653.It Ic lpage Ar local-file
654Display
655.Ar local-file
656with the program specified by the
657.Ic "set pager"
658option.
659.It Ic lpwd
660Print the working directory on the local machine.
661.It Ic \&ls Op Ar remote-path Op Ar local-file
662A synonym for
663.Ic dir .
664.It Ic macdef Ar macro-name
665Define a macro.
666Subsequent lines are stored as the macro
667.Ar macro-name  ;
668a null line (consecutive newline characters
669in a file or
670carriage returns from the terminal) terminates macro input mode.
671There is a limit of 16 macros and 4096 total characters in all
672defined macros.
673Macros remain defined until a
674.Ic close
675command is executed.
676The macro processor interprets `$' and `\e' as special characters.
677A `$' followed by a number (or numbers) is replaced by the
678corresponding argument on the macro invocation command line.
679A `$' followed by an `i' signals that macro processor that the
680executing macro is to be looped.
681On the first pass `$i' is
682replaced by the first argument on the macro invocation command line,
683on the second pass it is replaced by the second argument, and so on.
684A `\e' followed by any character is replaced by that character.
685Use the `\e' to prevent special treatment of the `$'.
686.It Ic mdelete Op Ar remote-files
687Delete the
688.Ar remote-files
689on the remote machine.
690.It Ic mdir Ar remote-files local-file
691Like
692.Ic dir  ,
693except multiple remote files may be specified.
694If interactive prompting is on,
695.Nm
696will prompt the user to verify that the last argument is indeed the
697target local file for receiving
698.Ic mdir
699output.
700.It Ic mget Ar remote-files
701Expand the
702.Ar remote-files
703on the remote machine
704and do a
705.Ic get
706for each file name thus produced.
707See
708.Ic glob
709for details on the filename expansion.
710Resulting file names will then be processed according to
711.Ic case  ,
712.Ic ntrans ,
713and
714.Ic nmap
715settings.
716Files are transferred into the local working directory,
717which can be changed with
718.Ql lcd directory ;
719new local directories can be created with
720.Ql "\&! mkdir directory" .
721.It Ic mkdir Ar directory-name
722Make a directory on the remote machine.
723.It Ic mls Ar remote-files local-file
724Like
725.Ic ls  ,
726except multiple remote files may be specified,
727and the
728.Ar local-file
729must be specified.
730If interactive prompting is on,
731.Nm
732will prompt the user to verify that the last argument is indeed the
733target local file for receiving
734.Ic mls
735output.
736.It Ic mlsd Op Ar remote-path
737Display the contents of
738.Ar remote-path
739(which should default to the current directory if not given)
740in a machine-parsable form, using
741.Dv MLSD .
742The format of display can be changed with
743.Sq "remopts mlst ..." .
744.It Ic mlst Op Ar remote-path
745Display the details about
746.Ar remote-path
747(which should default to the current directory if not given)
748in a machine-parsable form, using
749.Dv MLST .
750The format of display can be changed with
751.Sq "remopts mlst ..." .
752.It Ic mode Ar mode-name
753Set the file transfer
754.Ic mode
755to
756.Ar mode-name .
757The default (and only supported)
758mode is
759.Dq stream .
760.It Ic modtime Ar remote-file
761Show the last modification time of the file on the remote machine.
762.It Ic more Ar file
763A synonym for
764.Ic page .
765.It Ic mput Ar local-files
766Expand wild cards in the list of local files given as arguments
767and do a
768.Ic put
769for each file in the resulting list.
770See
771.Ic glob
772for details of filename expansion.
773Resulting file names will then be processed according to
774.Ic ntrans
775and
776.Ic nmap
777settings.
778.It Ic mreget Ar remote-files
779As per
780.Ic mget ,
781but performs a
782.Ic reget
783instead of
784.Ic get .
785.It Ic msend Ar local-files
786A synonym for
787.Ic mput .
788.It Ic newer Ar remote-file Op Ar local-file
789Get the file only if the modification time of the remote file is more
790recent that the file on the current system.
791If the file does not
792exist on the current system, the remote file is considered
793.Ic newer .
794Otherwise, this command is identical to
795.Ar get .
796.It Ic nlist Op Ar remote-path Op Ar local-file
797A synonym for
798.Ic ls .
799.It Ic nmap Op Ar inpattern outpattern
800Set or unset the filename mapping mechanism.
801If no arguments are specified, the filename mapping mechanism is unset.
802If arguments are specified, remote filenames are mapped during
803.Ic mput
804commands and
805.Ic put
806commands issued without a specified remote target filename.
807If arguments are specified, local filenames are mapped during
808.Ic mget
809commands and
810.Ic get
811commands issued without a specified local target filename.
812This command is useful when connecting to a
813.No non\- Ns Ux
814remote computer
815with different file naming conventions or practices.
816The mapping follows the pattern set by
817.Ar inpattern
818and
819.Ar outpattern .
820.Op Ar Inpattern
821is a template for incoming filenames (which may have already been
822processed according to the
823.Ic ntrans
824and
825.Ic case
826settings).
827Variable templating is accomplished by including the
828sequences `$1', `$2', ..., `$9' in
829.Ar inpattern .
830Use `\\' to prevent this special treatment of the `$' character.
831All other characters are treated literally, and are used to determine the
832.Ic nmap
833.Op Ar inpattern
834variable values.
835For example, given
836.Ar inpattern
837$1.$2 and the remote file name "mydata.data", $1 would have the value
838"mydata", and $2 would have the value "data".
839The
840.Ar outpattern
841determines the resulting mapped filename.
842The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
843from the
844.Ar inpattern
845template.
846The sequence `$0' is replace by the original filename.
847Additionally, the sequence
848.Ql Op Ar seq1 , Ar seq2
849is replaced by
850.Op Ar seq1
851if
852.Ar seq1
853is not a null string; otherwise it is replaced by
854.Ar seq2 .
855For example, the command
856.Pp
857.Bd -literal -offset indent -compact
858nmap $1.$2.$3 [$1,$2].[$2,file]
859.Ed
860.Pp
861would yield
862the output filename "myfile.data" for input filenames "myfile.data" and
863"myfile.data.old", "myfile.file" for the input filename "myfile", and
864"myfile.myfile" for the input filename ".myfile".
865Spaces may be included in
866.Ar outpattern  ,
867as in the example: `nmap $1 sed "s/  *$//" \*[Gt] $1' .
868Use the `\e' character to prevent special treatment
869of the `$','[',']', and `,' characters.
870.It Ic ntrans Op Ar inchars Op Ar outchars
871Set or unset the filename character translation mechanism.
872If no arguments are specified, the filename character
873translation mechanism is unset.
874If arguments are specified, characters in
875remote filenames are translated during
876.Ic mput
877commands and
878.Ic put
879commands issued without a specified remote target filename.
880If arguments are specified, characters in
881local filenames are translated during
882.Ic mget
883commands and
884.Ic get
885commands issued without a specified local target filename.
886This command is useful when connecting to a
887.No non\- Ns Ux
888remote computer
889with different file naming conventions or practices.
890Characters in a filename matching a character in
891.Ar inchars
892are replaced with the corresponding character in
893.Ar outchars .
894If the character's position in
895.Ar inchars
896is longer than the length of
897.Ar outchars  ,
898the character is deleted from the file name.
899.It Ic open Ar host Op Ar port
900Establish a connection to the specified
901.Ar host
902.Tn FTP
903server.
904An optional port number may be supplied,
905in which case,
906.Nm
907will attempt to contact an
908.Tn FTP
909server at that port.
910If the
911.Ic "set auto-login"
912option is on (default),
913.Nm
914will also attempt to automatically log the user in to
915the
916.Tn FTP
917server (see below).
918.It Ic page Ar file
919Retrieve
920.Ic file
921and display with the program specified by the
922.Ic "set pager"
923option.
924.It Ic passive Op Cm auto
925Toggle passive mode (if no arguments are given).
926If
927.Cm auto
928is given, act as if
929.Ev FTPMODE
930is set to
931.Sq auto .
932If passive mode is turned on (default),
933.Nm
934will send a
935.Dv PASV
936command for all data connections instead of a
937.Dv PORT
938command.
939The
940.Dv PASV
941command requests that the remote server open a port for the data connection
942and return the address of that port.
943The remote server listens on that port and the client connects to it.
944When using the more traditional
945.Dv PORT
946command, the client listens on a port and sends that address to the remote
947server, who connects back to it.
948Passive mode is useful when using
949.Nm
950through a gateway router or host that controls the directionality of
951traffic.
952(Note that though
953.Tn FTP
954servers are required to support the
955.Dv PASV
956command by RFC 1123, some do not.)
957.It Ic pdir Op Ar remote-path
958Perform
959.Ic dir
960.Op Ar remote-path ,
961and display the result with the program specified by the
962.Ic "set pager"
963option.
964.It Ic pls Op Ar remote-path
965Perform
966.Ic ls
967.Op Ar remote-path ,
968and display the result with the program specified by the
969.Ic "set pager"
970option.
971.It Ic pmlsd Op Ar remote-path
972Perform
973.Ic mlsd
974.Op Ar remote-path ,
975and display the result with the program specified by the
976.Ic "set pager"
977option.
978.It Ic preserve
979Toggle preservation of modification times on retrieved files.
980.It Ic progress
981Toggle display of transfer progress bar.
982The progress bar will be disabled for a transfer that has
983.Ar local-file
984as
985.Sq Fl
986or a command that starts with
987.Sq \&| .
988Refer to
989.Sx FILE NAMING CONVENTIONS
990for more information.
991Enabling
992.Ic progress
993disables
994.Ic hash .
995.It Ic prompt
996Toggle interactive prompting.
997Interactive prompting
998occurs during multiple file transfers to allow the
999user to selectively retrieve or store files.
1000If prompting is turned off (default is on), any
1001.Ic mget
1002or
1003.Ic mput
1004will transfer all files, and any
1005.Ic mdelete
1006will delete all files.
1007.Pp
1008When prompting is on, the following commands are available at a prompt:
1009.Bl -tag -width 2n -offset indent
1010.It Cm a
1011Answer
1012.Sq yes
1013to the current file, and automatically answer
1014.Sq yes
1015to any remaining files for the current command.
1016.It Cm n
1017Answer
1018.Sq no ,
1019and do not transfer the file.
1020.It Cm p
1021Answer
1022.Sq yes
1023to the current file, and turn off prompt mode
1024(as is
1025.Dq prompt off
1026had been given).
1027.It Cm q
1028Terminate the current operation.
1029.It Cm y
1030Answer
1031.Sq yes ,
1032and transfer the file.
1033.It Cm ?
1034Display a help message.
1035.El
1036.Pp
1037Any other response will answer
1038.Sq yes
1039to the current file.
1040.It Ic proxy Ar ftp-command
1041Execute an ftp command on a secondary control connection.
1042This command allows simultaneous connection to two remote
1043.Tn FTP
1044servers for transferring files between the two servers.
1045The first
1046.Ic proxy
1047command should be an
1048.Ic open  ,
1049to establish the secondary control connection.
1050Enter the command "proxy ?" to see other
1051.Tn FTP
1052commands executable on the secondary connection.
1053The following commands behave differently when prefaced by
1054.Ic proxy  :
1055.Ic open
1056will not define new macros during the auto-login process,
1057.Ic close
1058will not erase existing macro definitions,
1059.Ic get
1060and
1061.Ic mget
1062transfer files from the host on the primary control connection
1063to the host on the secondary control connection, and
1064.Ic put  ,
1065.Ic mput ,
1066and
1067.Ic append
1068transfer files from the host on the secondary control connection
1069to the host on the primary control connection.
1070Third party file transfers depend upon support of the
1071.Tn FTP
1072protocol
1073.Dv PASV
1074command by the server on the secondary control connection.
1075.It Ic put Ar local-file Op Ar remote-file
1076Store a local file on the remote machine.
1077If
1078.Ar remote-file
1079is left unspecified, the local file name is used
1080after processing according to any
1081.Ic ntrans
1082or
1083.Ic nmap
1084settings
1085in naming the remote file.
1086File transfer uses the
1087current settings for
1088.Ic type  ,
1089.Ic format ,
1090.Ic mode  ,
1091and
1092.Ic structure .
1093.It Ic pwd
1094Print the name of the current working directory on the remote
1095machine.
1096.It Ic quit
1097A synonym for
1098.Ic bye .
1099.It Ic quote Ar arg1 arg2 ...
1100The arguments specified are sent, verbatim, to the remote
1101.Tn FTP
1102server.
1103.It Xo
1104.Ic rate Ar direction
1105.Op Ar maximum Op Ar increment
1106.Xc
1107Throttle the maximum transfer rate to
1108.Ar maximum
1109bytes/second.
1110If
1111.Ar maximum
1112is 0, disable the throttle.
1113.Pp
1114.Ar direction
1115may be one of:
1116.Bl -tag -width "all" -offset indent -compact
1117.It Cm all
1118Both directions.
1119.It Cm get
1120Incoming transfers.
1121.It Cm put
1122Outgoing transfers.
1123.El
1124.Pp
1125.Ar maximum
1126can by modified on the fly by
1127.Ar increment
1128bytes (default: 1024) each time a given signal is received:
1129.B
1130.Bl -tag -width "SIGUSR1" -offset indent
1131.It Dv SIGUSR1
1132Increment
1133.Ar maximum
1134by
1135.Ar increment
1136bytes.
1137.It Dv SIGUSR2
1138Decrement
1139.Ar maximum
1140by
1141.Ar increment
1142bytes.
1143The result must be a positive number.
1144.El
1145.Pp
1146If
1147.Ar maximum
1148is not supplied, the current throttle rates are displayed.
1149.Pp
1150Note:
1151.Ic rate
1152is not yet implemented for ascii mode transfers.
1153.It Ic rcvbuf Ar size
1154Set the size of the socket receive buffer to
1155.Ar size .
1156.It Ic recv Ar remote-file Op Ar local-file
1157A synonym for
1158.Ic get .
1159.It Ic reget Ar remote-file Op Ar local-file
1160.Ic reget
1161acts like
1162.Ic get ,
1163except that if
1164.Ar local-file
1165exists and is
1166smaller than
1167.Ar remote-file  ,
1168.Ar local-file
1169is presumed to be
1170a partially transferred copy of
1171.Ar remote-file
1172and the transfer
1173is continued from the apparent point of failure.
1174This command
1175is useful when transferring very large files over networks that
1176are prone to dropping connections.
1177.It Ic remopts Ar command Op Ar command-options
1178Set options on the remote
1179.Tn FTP
1180server for
1181.Ar command
1182to
1183.Ar command-options
1184(whose absence is handled on a command-specific basis).
1185Remote
1186.Tn FTP
1187commands known to support options include:
1188.Sq MLST
1189(used for
1190.Dv MLSD
1191and
1192.Dv MLST ) .
1193.It Ic rename Op Ar from Op Ar to
1194Rename the file
1195.Ar from
1196on the remote machine, to the file
1197.Ar to .
1198.It Ic reset
1199Clear reply queue.
1200This command re-synchronizes command/reply sequencing with the remote
1201.Tn FTP
1202server.
1203Resynchronization may be necessary following a violation of the
1204.Tn FTP
1205protocol by the remote server.
1206.It Ic restart Ar marker
1207Restart the immediately following
1208.Ic get
1209or
1210.Ic put
1211at the
1212indicated
1213.Ar marker .
1214On
1215.Ux
1216systems, marker is usually a byte
1217offset into the file.
1218.It Ic rhelp Op Ar command-name
1219Request help from the remote
1220.Tn FTP
1221server.
1222If a
1223.Ar command-name
1224is specified it is supplied to the server as well.
1225.It Ic rmdir Ar directory-name
1226Delete a directory on the remote machine.
1227.It Ic rstatus Op Ar remote-file
1228With no arguments, show status of remote machine.
1229If
1230.Ar remote-file
1231is specified, show status of
1232.Ar remote-file
1233on remote machine.
1234.It Ic runique
1235Toggle storing of files on the local system with unique filenames.
1236If a file already exists with a name equal to the target
1237local filename for a
1238.Ic get
1239or
1240.Ic mget
1241command, a ".1" is appended to the name.
1242If the resulting name matches another existing file,
1243a ".2" is appended to the original name.
1244If this process continues up to ".99", an error
1245message is printed, and the transfer does not take place.
1246The generated unique filename will be reported.
1247Note that
1248.Ic runique
1249will not affect local files generated from a shell command
1250(see below).
1251The default value is off.
1252.It Ic send Ar local-file Op Ar remote-file
1253A synonym for
1254.Ic put .
1255.It Ic sendport
1256Toggle the use of
1257.Dv PORT
1258commands.
1259By default,
1260.Nm
1261will attempt to use a
1262.Dv PORT
1263command when establishing
1264a connection for each data transfer.
1265The use of
1266.Dv PORT
1267commands can prevent delays
1268when performing multiple file transfers.
1269If the
1270.Dv PORT
1271command fails,
1272.Nm
1273will use the default data port.
1274When the use of
1275.Dv PORT
1276commands is disabled, no attempt will be made to use
1277.Dv PORT
1278commands for each data transfer.
1279This is useful
1280for certain
1281.Tn FTP
1282implementations which do ignore
1283.Dv PORT
1284commands but, incorrectly, indicate they've been accepted.
1285.It Ic set Op Ar option Ar value
1286Set
1287.Ar option
1288to
1289.Ar value .
1290If
1291.Ar option
1292and
1293.Ar value
1294are not given, display all of the options and their values.
1295The currently supported options are:
1296.Bl -tag -width "http_proxy" -offset indent
1297.It Cm anonpass
1298Defaults to
1299.Ev $FTPANONPASS
1300.It Cm ftp_proxy
1301Defaults to
1302.Ev $ftp_proxy .
1303.It Cm http_proxy
1304Defaults to
1305.Ev $http_proxy .
1306.It Cm no_proxy
1307Defaults to
1308.Ev $no_proxy .
1309.It Cm pager
1310Defaults to
1311.Ev $PAGER .
1312.It Cm prompt
1313Defaults to
1314.Ev $FTPPROMPT .
1315.It Cm rprompt
1316Defaults to
1317.Ev $FTPRPROMPT .
1318.El
1319.It Ic site Ar arg1 arg2 ...
1320The arguments specified are sent, verbatim, to the remote
1321.Tn FTP
1322server as a
1323.Dv SITE
1324command.
1325.It Ic size Ar remote-file
1326Return size of
1327.Ar remote-file
1328on remote machine.
1329.It Ic sndbuf Ar size
1330Set the size of the socket send buffer to
1331.Ar size .
1332.It Ic status
1333Show the current status of
1334.Nm ftp .
1335.It Ic struct Ar struct-name
1336Set the file transfer
1337.Ar structure
1338to
1339.Ar struct-name .
1340The default (and only supported)
1341structure is
1342.Dq file .
1343.It Ic sunique
1344Toggle storing of files on remote machine under unique file names.
1345The remote
1346.Tn FTP
1347server must support
1348.Tn FTP
1349protocol
1350.Dv STOU
1351command for
1352successful completion.
1353The remote server will report unique name.
1354Default value is off.
1355.It Ic system
1356Show the type of operating system running on the remote machine.
1357.It Ic tenex
1358Set the file transfer type to that needed to
1359talk to
1360.Tn TENEX
1361machines.
1362.It Ic throttle
1363A synonym for
1364.Ic rate .
1365.It Ic trace
1366Toggle packet tracing.
1367.It Ic type Op Ar type-name
1368Set the file transfer
1369.Ic type
1370to
1371.Ar type-name .
1372If no type is specified, the current type
1373is printed.
1374The default type is network
1375.Tn ASCII .
1376.It Ic umask Op Ar newmask
1377Set the default umask on the remote server to
1378.Ar newmask .
1379If
1380.Ar newmask
1381is omitted, the current umask is printed.
1382.It Ic unset Ar option
1383Unset
1384.Ar option .
1385Refer to
1386.Ic set
1387for more information.
1388.It Ic usage Ar command
1389Print the usage message for
1390.Ar command .
1391.It Xo
1392.Ic user Ar user-name
1393.Op Ar password Op Ar account
1394.Xc
1395Identify yourself to the remote
1396.Tn FTP
1397server.
1398If the
1399.Ar password
1400is not specified and the server requires it,
1401.Nm
1402will prompt the user for it (after disabling local echo).
1403If an
1404.Ar account
1405field is not specified, and the
1406.Tn FTP
1407server
1408requires it, the user will be prompted for it.
1409If an
1410.Ar account
1411field is specified, an account command will
1412be relayed to the remote server after the login sequence
1413is completed if the remote server did not require it
1414for logging in.
1415Unless
1416.Nm
1417is invoked with
1418.Dq auto-login
1419disabled, this process is done automatically on initial connection to the
1420.Tn FTP
1421server.
1422.It Ic verbose
1423Toggle verbose mode.
1424In verbose mode, all responses from
1425the
1426.Tn FTP
1427server are displayed to the user.
1428In addition,
1429if verbose is on, when a file transfer completes, statistics
1430regarding the efficiency of the transfer are reported.
1431By default,
1432verbose is on.
1433.It Ic xferbuf Ar size
1434Set the size of the socket send and receive buffers to
1435.Ar size .
1436.It Ic ? Op Ar command
1437A synonym for
1438.Ic help .
1439.El
1440.Pp
1441Command arguments which have embedded spaces may be quoted with
1442quote `"' marks.
1443.Pp
1444Commands which toggle settings can take an explicit
1445.Ic on
1446or
1447.Ic off
1448argument to force the setting appropriately.
1449.Pp
1450Commands which take a byte count as an argument
1451(e.g.,
1452.Ic hash ,
1453.Ic rate ,
1454and
1455.Ic xferbuf )
1456support an optional suffix on the argument which changes the
1457interpretation of the argument.
1458Supported suffixes are:
1459.Bl -tag -width 3n -offset indent -compact
1460.It Li b
1461Causes no modification.
1462(Optional)
1463.It Li k
1464Kilo; multiply the argument by 1024
1465.It Li m
1466Mega; multiply the argument by 1048576
1467.It Li g
1468Giga; multiply the argument by 1073741824
1469.El
1470.Pp
1471If
1472.Nm
1473receives a
1474.Dv SIGINFO
1475(see the
1476.Dq status
1477argument of
1478.Xr stty 1 )
1479or
1480.Dv SIGQUIT
1481signal whilst a transfer is in progress, the current transfer rate
1482statistics will be written to the standard error output, in the
1483same format as the standard completion message.
1484.Sh AUTO-FETCHING FILES
1485In addition to standard commands, this version of
1486.Nm
1487supports an auto-fetch feature.
1488To enable auto-fetch, simply pass the list of hostnames/files
1489on the command line.
1490.Pp
1491The following formats are valid syntax for an auto-fetch element:
1492.Bl -tag -width "FOO "
1493.\" [user@]host:[path][/]
1494.It Xo
1495.Sm off
1496.Op Ar user Li \&@
1497.Ar host Li \&:
1498.Op Ar path
1499.Op Li /
1500.Sm on
1501.Xc
1502.Dq Classic
1503.Tn FTP
1504format.
1505.Pp
1506If
1507.Ar path
1508contains a glob character and globbing is enabled,
1509(see
1510.Ic glob ) ,
1511then the equivalent of
1512.Ql mget path
1513is performed.
1514.Pp
1515If the directory component of
1516.Ar path
1517contains no globbing characters,
1518it is stored locally with the name basename (see
1519.Xr basename 1 )
1520of
1521.Ic path ,
1522in the current directory.
1523Otherwise, the full remote name is used as the local name,
1524relative to the local root directory.
1525.\" ftp://[user[:password]@]host[:port]/path[/][;type=X]
1526.It Xo
1527.Sm off
1528.Li ftp://
1529.Oo Ar user
1530.Op Li \&: Ar password
1531.Li \&@ Oc
1532.Ar host Oo Li \&: Ar port Oc
1533.Li / Ar path
1534.Op Li /
1535.Op Li ;type= Ar X
1536.Sm on
1537.Xc
1538An
1539.Tn FTP
1540URL, retrieved using the
1541.Tn FTP
1542protocol if
1543.Ic "set ftp_proxy"
1544isn't defined.
1545Otherwise, transfer the URL using
1546.Tn HTTP
1547via the proxy defined in
1548.Ic "set ftp_proxy" .
1549If
1550.Ic "set ftp_proxy"
1551isn't defined and
1552.Ar user
1553is given, login as
1554.Ar user .
1555In this case, use
1556.Ar password
1557if supplied, otherwise prompt the user for one.
1558.Pp
1559If a suffix of
1560.Sq ;type=A
1561or
1562.Sq ;type=I
1563is supplied, then the transfer type will take place as
1564ascii or binary (respectively).
1565The default transfer type is binary.
1566.Pp
1567In order to be compliant with
1568.Cm RFC 1738 ,
1569.Nm
1570interprets the
1571.Ar path
1572part of an
1573.Dq ftp://
1574auto-fetch URL as follows:
1575.Bl -bullet
1576.It
1577The
1578.Sq Li /
1579immediately after the
1580.Ar host Ns Oo Li \&: Ns Ar port Oc
1581is interpreted as a separator before the
1582.Ar path ,
1583and not as part of the
1584.Ar path
1585itself.
1586.It
1587The
1588.Ar path
1589is interpreted as a
1590.So Li / Sc Ns -separated
1591list of name components.
1592For all but the last such component,
1593.Nm
1594performs the equivalent of a
1595.Ic cd
1596command.
1597For the last path component,
1598.Nm
1599performs the equivalent of a
1600.Ic get
1601command.
1602.It
1603Empty name components,
1604which result from
1605.Sq Li //
1606within the
1607.Ar path ,
1608or from an extra
1609.Sq Li /
1610at the beginning of the
1611.Ar path ,
1612will cause the equivalent of a
1613.Ic cd
1614command without a directory name.
1615This is unlikely to be useful.
1616.It
1617Any
1618.Sq Li \&% Ns Ar XX
1619codes within the path components are decoded, with
1620.Ar XX
1621representing a character code in hexadecimal.
1622This decoding takes place after the
1623.Ar path
1624has been split into components,
1625but before each component is used in the equivalent of a
1626.Ic cd
1627or
1628.Ic get
1629command.
1630Some often-used codes are
1631.Sq Li \&%2F
1632(which represents
1633.Sq Li / )
1634and
1635.Sq Li \&%7E
1636(which represents
1637.Sq Li ~ ) .
1638.El
1639.Pp
1640The above interpretation has the following consequences:
1641.Bl -bullet
1642.It
1643The path is interpreted relative to the
1644default login directory of the specified user or of the
1645.Sq anonymous
1646user.
1647If the
1648.Pa /
1649directory is required, use a leading path of
1650.Dq %2F .
1651If a user's home directory is required (and the remote server supports
1652the syntax), use a leading path of
1653.Dq %7Euser/ .
1654For example, to retrieve
1655.Pa /etc/motd
1656from
1657.Sq localhost
1658as the user
1659.Sq myname
1660with the password
1661.Sq mypass ,
1662use
1663.Dq ftp://myname:mypass@localhost/%2fetc/motd
1664.It
1665The exact
1666.Ic cd
1667and
1668.Ic get
1669commands can be controlled by careful choice of
1670where to use
1671.Sq /
1672and where to use
1673.Sq %2F
1674(or
1675.Sq %2f ) .
1676For example, the following URLs correspond to the
1677equivalents of the indicated commands:
1678.Bl -tag -width "ftp://host/%2Fdir1%2Fdir2%2Ffile"
1679.It ftp://host/dir1/dir2/file
1680.Dq "cd dir1" ,
1681.Dq "cd dir2" ,
1682.Dq "get file" .
1683.It ftp://host/%2Fdir1/dir2/file
1684.Dq "cd /dir1" ,
1685.Dq "cd dir2" ,
1686.Dq "get file" .
1687.It ftp://host/dir1%2Fdir2/file
1688.Dq "cd dir1/dir2" ,
1689.Dq "get file" .
1690.It ftp://host/%2Fdir1%2Fdir2/file
1691.Dq "cd /dir1/dir2" ,
1692.Dq "get file" .
1693.It ftp://host/dir1%2Fdir2%2Ffile
1694.Dq "get dir1/dir2/file" .
1695.It ftp://host/%2Fdir1%2Fdir2%2Ffile
1696.Dq "get /dir1/dir2/file" .
1697.El
1698.It
1699You must have appropriate access permission for each of the
1700intermediate directories that is used in the equivalent of a
1701.Ic cd
1702command.
1703.El
1704.\" http://[user[:password]@]host[:port]/path
1705.It Xo
1706.Sm off
1707.Li http://
1708.Oo Ar user
1709.Op Li \&: Ar password
1710.Li \&@ Oc
1711.Ar host Oo Li \&: Ar port Oc
1712.Li / Ar path
1713.Sm on
1714.Xc
1715An
1716.Tn HTTP
1717URL, retrieved using the
1718.Tn HTTP
1719protocol.
1720If
1721.Ic "set http_proxy"
1722is defined, it is used as a URL to an
1723.Tn HTTP
1724proxy server.
1725If
1726.Tn HTTP
1727authorization is required to retrieve
1728.Ar path ,
1729and
1730.Sq user
1731(and optionally
1732.Sq password )
1733is in the URL, use them for the first attempt to authenticate.
1734.\" file:///path
1735.It Xo
1736.Sm off
1737.Li file:/// Ar path
1738.Sm on
1739.Xc
1740A local URL, copied from
1741.Pa / Ns Ar path
1742on the local host.
1743.El
1744.Pp
1745Unless noted otherwise above, and
1746.Fl o Ar output
1747is not given, the file is stored in the current directory as the
1748.Xr basename 1
1749of
1750.Ar path .
1751.Pp
1752If a classic format or an
1753.Tn FTP
1754URL format has a trailing
1755.Sq /
1756or an empty
1757.Ar path
1758component, then
1759.Nm
1760will connect to the site and
1761.Ic cd
1762to the directory given as the path, and leave the user in interactive
1763mode ready for further input.
1764This will not work if
1765.Ic "set ftp_proxy"
1766is being used.
1767.Pp
1768Direct
1769.Tn HTTP
1770transfers use HTTP 1.1.
1771Proxied
1772.Tn FTP
1773and
1774.Tn HTTP
1775transfers use HTTP 1.0.
1776.Pp
1777If
1778.Fl R
1779is given, all auto-fetches that don't go via the
1780.Tn FTP
1781or
1782.Tn HTTP
1783proxies will be restarted.
1784For
1785.Tn FTP ,
1786this is implemented by using
1787.Nm reget
1788instead of
1789.Nm get .
1790For
1791.Tn HTTP ,
1792this is implemented by using the
1793.Sq "Range: bytes="
1794.Tn "HTTP/1.1"
1795directive.
1796.Pp
1797If WWW or proxy WWW authentication is required, you will be prompted
1798to enter a username and password to authenticate with.
1799.Pp
1800When specifying IPv6 numeric addresses in a URL, you need to
1801surround the address in square brackets.
1802E.g.:
1803.Dq ftp://[::1]:21/ .
1804This is because colons are used in IPv6 numeric address as well as
1805being the separator for the port number.
1806.Sh ABORTING A FILE TRANSFER
1807To abort a file transfer, use the terminal interrupt key
1808(usually Ctrl-C).
1809Sending transfers will be immediately halted.
1810Receiving transfers will be halted by sending an
1811.Tn FTP
1812protocol
1813.Dv ABOR
1814command to the remote server, and discarding any further data received.
1815The speed at which this is accomplished depends upon the remote
1816server's support for
1817.Dv ABOR
1818processing.
1819If the remote server does not support the
1820.Dv ABOR
1821command, the prompt will not appear until the remote server has completed
1822sending the requested file.
1823.Pp
1824If the terminal interrupt key sequence is used whilst
1825.Nm
1826is awaiting a reply from the remote server for the ABOR processing,
1827then the connection will be closed.
1828This is different from the traditional behaviour (which ignores the
1829terminal interrupt during this phase), but is considered more useful.
1830.Sh FILE NAMING CONVENTIONS
1831Files specified as arguments to
1832.Nm
1833commands are processed according to the following rules.
1834.Bl -enum
1835.It
1836If the file name
1837.Sq Fl
1838is specified, the
1839.Ar stdin
1840(for reading) or
1841.Ar stdout
1842(for writing) is used.
1843.It
1844If the first character of the file name is
1845.Sq \&| ,
1846the
1847remainder of the argument is interpreted as a shell command.
1848.Nm
1849then forks a shell, using
1850.Xr popen 3
1851with the argument supplied, and reads (writes) from the stdout
1852(stdin).
1853If the shell command includes spaces, the argument
1854must be quoted; e.g.
1855.Dq Qq Li \&| ls\ \-lt .
1856A particularly
1857useful example of this mechanism is:
1858.Dq Li dir \&"\&" \&|more .
1859.It
1860Failing the above checks, if ``globbing'' is enabled,
1861local file names are expanded
1862according to the rules used in the
1863.Xr csh  1  ;
1864c.f. the
1865.Ic glob
1866command.
1867If the
1868.Nm
1869command expects a single local file (e.g.
1870.Ic put  ) ,
1871only the first filename generated by the "globbing" operation is used.
1872.It
1873For
1874.Ic mget
1875commands and
1876.Ic get
1877commands with unspecified local file names, the local filename is
1878the remote filename, which may be altered by a
1879.Ic case  ,
1880.Ic ntrans ,
1881or
1882.Ic nmap
1883setting.
1884The resulting filename may then be altered if
1885.Ic runique
1886is on.
1887.It
1888For
1889.Ic mput
1890commands and
1891.Ic put
1892commands with unspecified remote file names, the remote filename is
1893the local filename, which may be altered by a
1894.Ic ntrans
1895or
1896.Ic nmap
1897setting.
1898The resulting filename may then be altered by the remote server if
1899.Ic sunique
1900is on.
1901.El
1902.Sh FILE TRANSFER PARAMETERS
1903The
1904.Tn FTP
1905specification specifies many parameters which may affect a file transfer.
1906The
1907.Ic type
1908may be one of
1909.Dq ascii ,
1910.Dq image
1911(binary),
1912.Dq ebcdic ,
1913and
1914.Dq local byte size
1915(for
1916.Tn PDP Ns -10's
1917and
1918.Tn PDP Ns -20's
1919mostly).
1920.Nm
1921supports the ascii and image types of file transfer,
1922plus local byte size 8 for
1923.Ic tenex
1924mode transfers.
1925.Pp
1926.Nm
1927supports only the default values for the remaining
1928file transfer parameters:
1929.Ic mode ,
1930.Ic form ,
1931and
1932.Ic struct .
1933.Sh THE .netrc FILE
1934The
1935.Pa .netrc
1936file contains login and initialization information
1937used by the auto-login process.
1938It resides in the user's home directory,
1939unless overridden with the
1940.Fl N Ar netrc
1941option, or specified in the
1942.Ev NETRC
1943environment variable.
1944The following tokens are recognized; they may be separated by spaces,
1945tabs, or new-lines:
1946.Bl -tag -width password
1947.It Ic machine Ar name
1948Identify a remote machine
1949.Ar name .
1950The auto-login process searches the
1951.Pa .netrc
1952file for a
1953.Ic machine
1954token that matches the remote machine specified on the
1955.Nm
1956command line or as an
1957.Ic open
1958command argument.
1959Once a match is made, the subsequent
1960.Pa .netrc
1961tokens are processed,
1962stopping when the end of file is reached or another
1963.Ic machine
1964or a
1965.Ic default
1966token is encountered.
1967.It Ic default
1968This is the same as
1969.Ic machine
1970.Ar name
1971except that
1972.Ic default
1973matches any name.
1974There can be only one
1975.Ic default
1976token, and it must be after all
1977.Ic machine
1978tokens.
1979This is normally used as:
1980.Pp
1981.Dl default login anonymous password user@site
1982.Pp
1983thereby giving the user an automatic anonymous
1984.Tn FTP
1985login to
1986machines not specified in
1987.Pa .netrc .
1988This can be overridden
1989by using the
1990.Fl n
1991flag to disable auto-login.
1992.It Ic login Ar name
1993Identify a user on the remote machine.
1994If this token is present, the auto-login process will initiate
1995a login using the specified
1996.Ar name .
1997.It Ic password Ar string
1998Supply a password.
1999If this token is present, the auto-login process will supply the
2000specified string if the remote server requires a password as part
2001of the login process.
2002Note that if this token is present in the
2003.Pa .netrc
2004file for any user other
2005than
2006.Ar anonymous  ,
2007.Nm
2008will abort the auto-login process if the
2009.Pa .netrc
2010is readable by
2011anyone besides the user.
2012.It Ic account Ar string
2013Supply an additional account password.
2014If this token is present, the auto-login process will supply the
2015specified string if the remote server requires an additional
2016account password, or the auto-login process will initiate an
2017.Dv ACCT
2018command if it does not.
2019.It Ic macdef Ar name
2020Define a macro.
2021This token functions like the
2022.Nm
2023.Ic macdef
2024command functions.
2025A macro is defined with the specified name; its contents begin with the
2026next
2027.Pa .netrc
2028line and continue until a blank line (consecutive new-line
2029characters) is encountered.
2030If a macro named
2031.Ic init
2032is defined, it is automatically executed as the last step in the
2033auto-login process.
2034.El
2035.Sh COMMAND LINE EDITING
2036.Nm
2037supports interactive command line editing, via the
2038.Xr editline 3
2039library.
2040It is enabled with the
2041.Ic edit
2042command, and is enabled by default if input is from a tty.
2043Previous lines can be recalled and edited with the arrow keys,
2044and other GNU Emacs-style editing keys may be used as well.
2045.Pp
2046The
2047.Xr editline 3
2048library is configured with a
2049.Pa .editrc
2050file - refer to
2051.Xr editrc 5
2052for more information.
2053.Pp
2054An extra key binding is available to
2055.Nm
2056to provide context sensitive command and filename completion
2057(including remote file completion).
2058To use this, bind a key to the
2059.Xr editline 3
2060command
2061.Ic ftp-complete .
2062By default, this is bound to the TAB key.
2063.Sh COMMAND LINE PROMPT
2064By default,
2065.Nm
2066displays a command line prompt of
2067.Dq "ftp\*[Gt] "
2068to the user.
2069This can be changed with the
2070.Ic "set prompt"
2071command.
2072.Pp
2073A prompt can be displayed on the right side of the screen (after the
2074command input) with the
2075.Ic "set rprompt"
2076command.
2077.Pp
2078The following formatting sequences are replaced by the given
2079information:
2080.Bl -tag -width "%% " -offset indent
2081.It Li \&%/
2082The current remote working directory.
2083.\" %c[[0]n], %.[[0]n]
2084.It Xo
2085.Sm off
2086.Li \&%c
2087.Op Oo Li 0 Oc Ar n
2088.Sm on
2089.No ,
2090.Sm off
2091.Li \&%.
2092.Op Oo Li 0 Oc Ar n
2093.Sm on
2094.Xc
2095The trailing component of the current remote working directory, or
2096.Em n
2097trailing components if a digit
2098.Em n
2099is given.
2100If
2101.Em n
2102begins with
2103.Sq 0 ,
2104the number of skipped components precede the trailing component(s) in
2105the format
2106.\" ``/<number>trailing''
2107.Do
2108.Sm off
2109.Li / Li \*[Lt] Va number Li \*[Gt]
2110.Va trailing
2111.Sm on
2112.Dc
2113(for
2114.Sq \&%c )
2115or
2116.\" ``...trailing''
2117.Dq Li \&... Ns Va trailing
2118(for
2119.Sq \&%. ) .
2120.It Li \&%M
2121The remote host name.
2122.It Li \&%m
2123The remote host name, up to the first
2124.Sq \&. .
2125.It Li \&%n
2126The remote user name.
2127.It Li \&%%
2128A single
2129.Sq % .
2130.El
2131.Sh ENVIRONMENT
2132.Nm
2133uses the following environment variables.
2134.Bl -tag -width "FTPSERVERPORT"
2135.It Ev FTPANONPASS
2136Password to send in an anonymous
2137.Tn FTP
2138transfer.
2139Defaults to
2140.Dq Li `whoami`@ .
2141.It Ev FTPMODE
2142Overrides the default operation mode.
2143Support values are:
2144.Bl -tag -width "passive"
2145.It Cm active
2146active mode
2147.Tn FTP
2148only
2149.It Cm auto
2150automatic determination of passive or active (this is the default)
2151.It Cm gate
2152gate-ftp mode
2153.It Cm passive
2154passive mode
2155.Tn FTP
2156only
2157.El
2158.It Ev FTPPROMPT
2159Command-line prompt to use.
2160Defaults to
2161.Dq "ftp\*[Gt] " .
2162Refer to
2163.Sx COMMAND LINE PROMPT
2164for more information.
2165.It Ev FTPRPROMPT
2166Command-line right side prompt to use.
2167Defaults to
2168.Dq "" .
2169Refer to
2170.Sx COMMAND LINE PROMPT
2171for more information.
2172.It Ev FTPSERVER
2173Host to use as gate-ftp server when
2174.Ic gate
2175is enabled.
2176.It Ev FTPSERVERPORT
2177Port to use when connecting to gate-ftp server when
2178.Ic gate
2179is enabled.
2180Default is port returned by a
2181.Fn getservbyname
2182lookup of
2183.Dq ftpgate/tcp .
2184.It Ev HOME
2185For default location of a
2186.Pa .netrc
2187file, if one exists.
2188.It Ev NETRC
2189An alternate location of the
2190.Pa .netrc
2191file.
2192.It Ev PAGER
2193Used by various commands to display files.
2194Defaults to
2195.Xr more 1
2196if empty or not set.
2197.It Ev SHELL
2198For default shell.
2199.It Ev ftp_proxy
2200URL of
2201.Tn FTP
2202proxy to use when making
2203.Tn FTP
2204URL requests
2205(if not defined, use the standard
2206.Tn FTP
2207protocol).
2208.Pp
2209.Em NOTE :
2210this is not used for interactive sessions, only for command-line
2211fetches.
2212.It Ev http_proxy
2213URL of
2214.Tn HTTP
2215proxy to use when making
2216.Tn HTTP
2217URL requests.
2218If proxy authentication is required and there is a username and
2219password in this URL, they will automatically be used in the first
2220attempt to authenticate to the proxy.
2221.Pp
2222Note that the use of a username and password in
2223.Ev ftp_proxy
2224and
2225.Ev http_proxy
2226may be incompatible with other programs that use it
2227(such as
2228.Xr lynx 1 ) .
2229.Pp
2230.Em NOTE :
2231this is not used for interactive sessions, only for command-line
2232fetches.
2233.It Ev no_proxy
2234A space or comma separated list of hosts (or domains) for which
2235proxying is not to be used.
2236Each entry may have an optional trailing ":port", which restricts
2237the matching to connections to that port.
2238.El
2239.Sh SEE ALSO
2240.Xr getservbyname 3 ,
2241.Xr editrc 5 ,
2242.Xr services 5 ,
2243.Xr ftpd 8
2244.Sh STANDARDS
2245.Nm
2246attempts to be compliant with
2247.Cm RFC 959 ,
2248.Cm RFC 1123 ,
2249.Cm RFC 1738 ,
2250.Cm RFC 2068 ,
2251.Cm RFC 2389 ,
2252.Cm RFC 2428 ,
2253.Cm RFC 2732 ,
2254and
2255.Cm draft-ietf-ftpext-mlst-11 .
2256.Sh HISTORY
2257The
2258.Nm
2259command appeared in
2260.Bx 4.2 .
2261.Pp
2262Various features such as command line editing, context sensitive
2263command and file completion, dynamic progress bar, automatic
2264fetching of files and URLs, modification time preservation,
2265transfer rate throttling, configurable command line prompt,
2266and other enhancements over the standard
2267.Bx
2268.Nm
2269were implemented in
2270.Nx 1.3
2271and later releases
2272by Luke Mewburn \*[Lt]lukem@netbsd.org\*[Gt].
2273.Pp
2274IPv6 support was added by the WIDE/KAME project
2275(but may not be present in all non-NetBSD versions of this program, depending
2276if the operating system supports IPv6 in a similar manner to KAME).
2277.Sh BUGS
2278Correct execution of many commands depends upon proper behavior
2279by the remote server.
2280.Pp
2281An error in the treatment of carriage returns
2282in the
2283.Bx 4.2
2284ascii-mode transfer code
2285has been corrected.
2286This correction may result in incorrect transfers of binary files
2287to and from
2288.Bx 4.2
2289servers using the ascii type.
2290Avoid this problem by using the binary image type.
2291.Pp
2292.Nm
2293assumes that all IPv4 mapped addresses
2294.Po
2295IPv6 addresses with a form like
2296.Li ::ffff:10.1.1.1
2297.Pc
2298indicate IPv4 destinations which can be handled by
2299.Dv AF_INET
2300sockets.
2301However, in certain IPv6 network configurations, this assumption is not true.
2302In such an environment, IPv4 mapped addresses must be passed to
2303.Dv AF_INET6
2304sockets directly.
2305For example, if your site uses a SIIT translator for IPv6-to-IPv4 translation,
2306.Nm
2307is unable to support your configuration.
2308