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