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