Improve parsing of chunked transfer chunks per RFC2616:
[dragonfly.git] / contrib / tnftp / ftp.1
CommitLineData
8b05fa7f 1.\" $NetBSD: ftp.1,v 1.121 2007/08/20 16:07:05 perry 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.\"
8b05fa7f 67.Dd August 6, 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
89.Bk -words
90.Op Fl r Ar retry
91.Ek
8b05fa7f 92.Op Fl s Ar srcaddr
eedc536d
PA
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
c106ca54 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
c106ca54
PA
790Show the last modification time of the file on the remote machine, in
791.Li RFC2822
792format.
eedc536d
PA
793.It Ic more Ar file
794A synonym for
795.Ic page .
796.It Ic mput Ar local-files
797Expand wild cards in the list of local files given as arguments
798and do a
799.Ic put
800for each file in the resulting list.
801See
802.Ic glob
803for details of filename expansion.
804Resulting file names will then be processed according to
805.Ic ntrans
806and
807.Ic nmap
808settings.
809.It Ic mreget Ar remote-files
810As per
811.Ic mget ,
812but performs a
813.Ic reget
814instead of
815.Ic get .
816.It Ic msend Ar local-files
817A synonym for
818.Ic mput .
819.It Ic newer Ar remote-file Op Ar local-file
820Get the file only if the modification time of the remote file is more
821recent that the file on the current system.
822If the file does not
823exist on the current system, the remote file is considered
824.Ic newer .
825Otherwise, this command is identical to
826.Ar get .
827.It Ic nlist Op Ar remote-path Op Ar local-file
828A synonym for
829.Ic ls .
830.It Ic nmap Op Ar inpattern outpattern
831Set or unset the filename mapping mechanism.
832If no arguments are specified, the filename mapping mechanism is unset.
833If arguments are specified, remote filenames are mapped during
834.Ic mput
835commands and
836.Ic put
837commands issued without a specified remote target filename.
838If arguments are specified, local filenames are mapped during
839.Ic mget
840commands and
841.Ic get
842commands issued without a specified local target filename.
843This command is useful when connecting to a
844.No non\- Ns Ux
845remote computer
846with different file naming conventions or practices.
847The mapping follows the pattern set by
848.Ar inpattern
849and
850.Ar outpattern .
851.Op Ar Inpattern
852is a template for incoming filenames (which may have already been
853processed according to the
854.Ic ntrans
855and
856.Ic case
857settings).
858Variable templating is accomplished by including the
859sequences
860.Dq $1 ,
861.Dq $2 ,
862\&...
863.Dq $9
864in
865.Ar inpattern .
866Use
867.Sq \e
868to prevent this special treatment of the
869.Sq $
870character.
871All other characters are treated literally, and are used to determine the
872.Ic nmap
873.Op Ar inpattern
874variable values.
875For example, given
876.Ar inpattern
877$1.$2 and the remote file name "mydata.data", $1 would have the value
878"mydata", and $2 would have the value "data".
879The
880.Ar outpattern
881determines the resulting mapped filename.
882The sequences
883.Dq $1 ,
884.Dq $2 ,
885\&...
886.Dq $9
887are replaced by any value resulting from the
888.Ar inpattern
889template.
890The sequence
891.Dq $0
892is replaced by the original filename.
893Additionally, the sequence
894.Dq Op Ar seq1 , Ar seq2
895is replaced by
896.Op Ar seq1
897if
898.Ar seq1
899is not a null string; otherwise it is replaced by
900.Ar seq2 .
901For example, the command
902.Pp
903.Bd -literal -offset indent -compact
904nmap $1.$2.$3 [$1,$2].[$2,file]
905.Ed
906.Pp
907would yield
908the output filename "myfile.data" for input filenames "myfile.data" and
909"myfile.data.old", "myfile.file" for the input filename "myfile", and
910"myfile.myfile" for the input filename ".myfile".
911Spaces may be included in
912.Ar outpattern ,
913as in the example:
914.Dl nmap $1 sed "s/ *$//" \*[Gt] $1
915Use the
916.Sq \e
917character to prevent special treatment
918of the
919.Sq $ ,
920.Sq \&[ ,
921.Sq \&] ,
922and
923.Sq \&,
924characters.
925.It Ic ntrans Op Ar inchars Op Ar outchars
926Set or unset the filename character translation mechanism.
927If no arguments are specified, the filename character
928translation mechanism is unset.
929If arguments are specified, characters in
930remote filenames are translated during
931.Ic mput
932commands and
933.Ic put
934commands issued without a specified remote target filename.
935If arguments are specified, characters in
936local filenames are translated during
937.Ic mget
938commands and
939.Ic get
940commands issued without a specified local target filename.
941This command is useful when connecting to a
942.No non\- Ns Ux
943remote computer
944with different file naming conventions or practices.
945Characters in a filename matching a character in
946.Ar inchars
947are replaced with the corresponding character in
948.Ar outchars .
949If the character's position in
950.Ar inchars
951is longer than the length of
952.Ar outchars ,
953the character is deleted from the file name.
954.It Ic open Ar host Op Ar port
955Establish a connection to the specified
956.Ar host
957.Tn FTP
958server.
959An optional port number may be supplied,
960in which case,
961.Nm
962will attempt to contact an
963.Tn FTP
964server at that port.
965If the
966.Ic "set auto-login"
967option is on (default),
968.Nm
969will also attempt to automatically log the user in to
970the
971.Tn FTP
972server (see below).
973.It Ic page Ar file
974Retrieve
975.Ic file
976and display with the program specified by the
977.Ic "set pager"
978option.
979.It Ic passive Op Cm auto
980Toggle passive mode (if no arguments are given).
981If
982.Cm auto
983is given, act as if
984.Ev FTPMODE
985is set to
986.Sq auto .
987If passive mode is turned on (default),
988.Nm
989will send a
990.Dv PASV
991command for all data connections instead of a
992.Dv PORT
993command.
994The
995.Dv PASV
996command requests that the remote server open a port for the data connection
997and return the address of that port.
998The remote server listens on that port and the client connects to it.
999When using the more traditional
1000.Dv PORT
1001command, the client listens on a port and sends that address to the remote
1002server, who connects back to it.
1003Passive mode is useful when using
1004.Nm
1005through a gateway router or host that controls the directionality of
1006traffic.
1007(Note that though
1008.Tn FTP
1009servers are required to support the
1010.Dv PASV
1011command by
c106ca54 1012.Li RFC1123 ,
eedc536d
PA
1013some do not.)
1014.It Ic pdir Op Ar remote-path
1015Perform
1016.Ic dir
1017.Op Ar remote-path ,
1018and display the result with the program specified by the
1019.Ic "set pager"
1020option.
1021.It Ic pls Op Ar remote-path
1022Perform
1023.Ic ls
1024.Op Ar remote-path ,
1025and display the result with the program specified by the
1026.Ic "set pager"
1027option.
1028.It Ic pmlsd Op Ar remote-path
1029Perform
1030.Ic mlsd
1031.Op Ar remote-path ,
1032and display the result with the program specified by the
1033.Ic "set pager"
1034option.
1035.It Ic preserve
1036Toggle preservation of modification times on retrieved files.
1037.It Ic progress
1038Toggle display of transfer progress bar.
1039The progress bar will be disabled for a transfer that has
1040.Ar local-file
1041as
1042.Sq Fl
1043or a command that starts with
1044.Sq \&| .
1045Refer to
1046.Sx FILE NAMING CONVENTIONS
1047for more information.
1048Enabling
1049.Ic progress
1050disables
1051.Ic hash .
1052.It Ic prompt
1053Toggle interactive prompting.
1054Interactive prompting
1055occurs during multiple file transfers to allow the
1056user to selectively retrieve or store files.
1057If prompting is turned off (default is on), any
1058.Ic mget
1059or
1060.Ic mput
1061will transfer all files, and any
1062.Ic mdelete
1063will delete all files.
1064.Pp
1065When prompting is on, the following commands are available at a prompt:
1066.Bl -tag -width 2n -offset indent
1067.It Cm a
1068Answer
1069.Sq yes
1070to the current file, and automatically answer
1071.Sq yes
1072to any remaining files for the current command.
1073.It Cm n
1074Answer
1075.Sq no ,
1076and do not transfer the file.
1077.It Cm p
1078Answer
1079.Sq yes
1080to the current file, and turn off prompt mode
1081(as is
1082.Dq prompt off
1083had been given).
1084.It Cm q
1085Terminate the current operation.
1086.It Cm y
1087Answer
1088.Sq yes ,
1089and transfer the file.
1090.It Cm \&?
1091Display a help message.
1092.El
1093.Pp
1094Any other response will answer
1095.Sq yes
1096to the current file.
1097.It Ic proxy Ar ftp-command
1098Execute an ftp command on a secondary control connection.
1099This command allows simultaneous connection to two remote
1100.Tn FTP
1101servers for transferring files between the two servers.
1102The first
1103.Ic proxy
1104command should be an
1105.Ic open ,
1106to establish the secondary control connection.
1107Enter the command "proxy ?" to see other
1108.Tn FTP
1109commands executable on the secondary connection.
1110The following commands behave differently when prefaced by
1111.Ic proxy :
1112.Ic open
1113will not define new macros during the auto-login process,
1114.Ic close
1115will not erase existing macro definitions,
1116.Ic get
1117and
1118.Ic mget
1119transfer files from the host on the primary control connection
1120to the host on the secondary control connection, and
1121.Ic put ,
1122.Ic mput ,
1123and
1124.Ic append
1125transfer files from the host on the secondary control connection
1126to the host on the primary control connection.
1127Third party file transfers depend upon support of the
1128.Tn FTP
1129protocol
1130.Dv PASV
1131command by the server on the secondary control connection.
1132.It Ic put Ar local-file Op Ar remote-file
1133Store a local file on the remote machine.
1134If
1135.Ar remote-file
1136is left unspecified, the local file name is used
1137after processing according to any
1138.Ic ntrans
1139or
1140.Ic nmap
1141settings
1142in naming the remote file.
1143File transfer uses the
1144current settings for
1145.Ic type ,
1146.Ic format ,
1147.Ic mode ,
1148and
1149.Ic structure .
1150.It Ic pwd
1151Print the name of the current working directory on the remote
1152machine.
1153.It Ic quit
1154A synonym for
1155.Ic bye .
1156.It Ic quote Ar arg1 arg2 ...
1157The arguments specified are sent, verbatim, to the remote
1158.Tn FTP
1159server.
1160.It Xo
1161.Ic rate Ar direction
1162.Op Ar maximum Op Ar increment
1163.Xc
1164Throttle the maximum transfer rate to
1165.Ar maximum
1166bytes/second.
1167If
1168.Ar maximum
1169is 0, disable the throttle.
1170.Pp
1171.Ar direction
1172may be one of:
1173.Bl -tag -width "all" -offset indent -compact
1174.It Cm all
1175Both directions.
1176.It Cm get
1177Incoming transfers.
1178.It Cm put
1179Outgoing transfers.
1180.El
1181.Pp
1182.Ar maximum
1183can be modified on the fly by
1184.Ar increment
1185bytes (default: 1024) each time a given signal is received:
1186.B
1187.Bl -tag -width "SIGUSR1" -offset indent
1188.It Dv SIGUSR1
1189Increment
1190.Ar maximum
1191by
1192.Ar increment
1193bytes.
1194.It Dv SIGUSR2
1195Decrement
1196.Ar maximum
1197by
1198.Ar increment
1199bytes.
1200The result must be a positive number.
1201.El
1202.Pp
1203If
1204.Ar maximum
1205is not supplied, the current throttle rates are displayed.
1206.Pp
1207Note:
1208.Ic rate
1209is not yet implemented for ascii mode transfers.
1210.It Ic rcvbuf Ar size
1211Set the size of the socket receive buffer to
1212.Ar size .
1213.It Ic recv Ar remote-file Op Ar local-file
1214A synonym for
1215.Ic get .
1216.It Ic reget Ar remote-file Op Ar local-file
1217.Ic reget
1218acts like
1219.Ic get ,
1220except that if
1221.Ar local-file
1222exists and is
1223smaller than
1224.Ar remote-file ,
1225.Ar local-file
1226is presumed to be
1227a partially transferred copy of
1228.Ar remote-file
1229and the transfer
1230is continued from the apparent point of failure.
1231This command
1232is useful when transferring very large files over networks that
1233are prone to dropping connections.
1234.It Ic remopts Ar command Op Ar command-options
1235Set options on the remote
1236.Tn FTP
1237server for
1238.Ar command
1239to
1240.Ar command-options
1241(whose absence is handled on a command-specific basis).
1242Remote
1243.Tn FTP
1244commands known to support options include:
1245.Sq MLST
1246(used for
1247.Dv MLSD
1248and
1249.Dv MLST ) .
1250.It Ic rename Op Ar from Op Ar to
1251Rename the file
1252.Ar from
1253on the remote machine, to the file
1254.Ar to .
1255.It Ic reset
1256Clear reply queue.
1257This command re-synchronizes command/reply sequencing with the remote
1258.Tn FTP
1259server.
1260Resynchronization may be necessary following a violation of the
1261.Tn FTP
1262protocol by the remote server.
1263.It Ic restart Ar marker
1264Restart the immediately following
1265.Ic get
1266or
1267.Ic put
1268at the
1269indicated
1270.Ar marker .
1271On
1272.Ux
1273systems, marker is usually a byte
1274offset into the file.
1275.It Ic rhelp Op Ar command-name
1276Request help from the remote
1277.Tn FTP
1278server.
1279If a
1280.Ar command-name
1281is specified it is supplied to the server as well.
1282.It Ic rmdir Ar directory-name
1283Delete a directory on the remote machine.
1284.It Ic rstatus Op Ar remote-file
1285With no arguments, show status of remote machine.
1286If
1287.Ar remote-file
1288is specified, show status of
1289.Ar remote-file
1290on remote machine.
1291.It Ic runique
1292Toggle storing of files on the local system with unique filenames.
1293If a file already exists with a name equal to the target
1294local filename for a
1295.Ic get
1296or
1297.Ic mget
1298command, a ".1" is appended to the name.
1299If the resulting name matches another existing file,
1300a ".2" is appended to the original name.
1301If this process continues up to ".99", an error
1302message is printed, and the transfer does not take place.
1303The generated unique filename will be reported.
1304Note that
1305.Ic runique
1306will not affect local files generated from a shell command
1307(see below).
1308The default value is off.
1309.It Ic send Ar local-file Op Ar remote-file
1310A synonym for
1311.Ic put .
1312.It Ic sendport
1313Toggle the use of
1314.Dv PORT
1315commands.
1316By default,
1317.Nm
1318will attempt to use a
1319.Dv PORT
1320command when establishing
1321a connection for each data transfer.
1322The use of
1323.Dv PORT
1324commands can prevent delays
1325when performing multiple file transfers.
1326If the
1327.Dv PORT
1328command fails,
1329.Nm
1330will use the default data port.
1331When the use of
1332.Dv PORT
1333commands is disabled, no attempt will be made to use
1334.Dv PORT
1335commands for each data transfer.
1336This is useful
1337for certain
1338.Tn FTP
1339implementations which do ignore
1340.Dv PORT
1341commands but, incorrectly, indicate they've been accepted.
1342.It Ic set Op Ar option Ar value
1343Set
1344.Ar option
1345to
1346.Ar value .
1347If
1348.Ar option
1349and
1350.Ar value
1351are not given, display all of the options and their values.
1352The currently supported options are:
1353.Bl -tag -width "http_proxy" -offset indent
1354.It Cm anonpass
1355Defaults to
1356.Ev $FTPANONPASS
1357.It Cm ftp_proxy
1358Defaults to
1359.Ev $ftp_proxy .
1360.It Cm http_proxy
1361Defaults to
1362.Ev $http_proxy .
1363.It Cm no_proxy
1364Defaults to
1365.Ev $no_proxy .
1366.It Cm pager
1367Defaults to
1368.Ev $PAGER .
1369.It Cm prompt
1370Defaults to
1371.Ev $FTPPROMPT .
1372.It Cm rprompt
1373Defaults to
1374.Ev $FTPRPROMPT .
1375.El
1376.It Ic site Ar arg1 arg2 ...
1377The arguments specified are sent, verbatim, to the remote
1378.Tn FTP
1379server as a
1380.Dv SITE
1381command.
1382.It Ic size Ar remote-file
1383Return size of
1384.Ar remote-file
1385on remote machine.
1386.It Ic sndbuf Ar size
1387Set the size of the socket send buffer to
1388.Ar size .
1389.It Ic status
1390Show the current status of
1391.Nm ftp .
1392.It Ic struct Ar struct-name
1393Set the file transfer
1394.Ar structure
1395to
1396.Ar struct-name .
1397The default (and only supported)
1398structure is
1399.Dq file .
1400.It Ic sunique
1401Toggle storing of files on remote machine under unique file names.
1402The remote
1403.Tn FTP
1404server must support
1405.Tn FTP
1406protocol
1407.Dv STOU
1408command for
1409successful completion.
1410The remote server will report unique name.
1411Default value is off.
1412.It Ic system
1413Show the type of operating system running on the remote machine.
1414.It Ic tenex
1415Set the file transfer type to that needed to
1416talk to
1417.Tn TENEX
1418machines.
1419.It Ic throttle
1420A synonym for
1421.Ic rate .
1422.It Ic trace
1423Toggle packet tracing.
1424.It Ic type Op Ar type-name
1425Set the file transfer
1426.Ic type
1427to
1428.Ar type-name .
1429If no type is specified, the current type
1430is printed.
1431The default type is network
1432.Tn ASCII .
1433.It Ic umask Op Ar newmask
1434Set the default umask on the remote server to
1435.Ar newmask .
1436If
1437.Ar newmask
1438is omitted, the current umask is printed.
1439.It Ic unset Ar option
1440Unset
1441.Ar option .
1442Refer to
1443.Ic set
1444for more information.
1445.It Ic usage Ar command
1446Print the usage message for
1447.Ar command .
1448.It Xo
1449.Ic user Ar user-name
1450.Op Ar password Op Ar account
1451.Xc
1452Identify yourself to the remote
1453.Tn FTP
1454server.
1455If the
1456.Ar password
1457is not specified and the server requires it,
1458.Nm
1459will prompt the user for it (after disabling local echo).
1460If an
1461.Ar account
1462field is not specified, and the
1463.Tn FTP
1464server
1465requires it, the user will be prompted for it.
1466If an
1467.Ar account
1468field is specified, an account command will
1469be relayed to the remote server after the login sequence
1470is completed if the remote server did not require it
1471for logging in.
1472Unless
1473.Nm
1474is invoked with
1475.Dq auto-login
1476disabled, this process is done automatically on initial connection to the
1477.Tn FTP
1478server.
1479.It Ic verbose
1480Toggle verbose mode.
1481In verbose mode, all responses from
1482the
1483.Tn FTP
1484server are displayed to the user.
1485In addition,
1486if verbose is on, when a file transfer completes, statistics
1487regarding the efficiency of the transfer are reported.
1488By default,
1489verbose is on.
1490.It Ic xferbuf Ar size
1491Set the size of the socket send and receive buffers to
1492.Ar size .
1493.It Ic \&? Op Ar command
1494A synonym for
1495.Ic help .
1496.El
1497.Pp
1498Command arguments which have embedded spaces may be quoted with
1499quote
1500.Sq \&"
1501marks.
1502.Pp
1503Commands which toggle settings can take an explicit
1504.Ic on
1505or
1506.Ic off
1507argument to force the setting appropriately.
1508.Pp
1509Commands which take a byte count as an argument
1510(e.g.,
1511.Ic hash ,
1512.Ic rate ,
1513and
1514.Ic xferbuf )
1515support an optional suffix on the argument which changes the
1516interpretation of the argument.
1517Supported suffixes are:
1518.Bl -tag -width 3n -offset indent -compact
1519.It Li b
1520Causes no modification.
1521(Optional)
1522.It Li k
1523Kilo; multiply the argument by 1024
1524.It Li m
1525Mega; multiply the argument by 1048576
1526.It Li g
1527Giga; multiply the argument by 1073741824
1528.El
1529.Pp
1530If
1531.Nm
1532receives a
1533.Dv SIGINFO
1534(see the
1535.Dq status
1536argument of
1537.Xr stty 1 )
1538or
1539.Dv SIGQUIT
1540signal whilst a transfer is in progress, the current transfer rate
1541statistics will be written to the standard error output, in the
1542same format as the standard completion message.
1543.Sh AUTO-FETCHING FILES
1544In addition to standard commands, this version of
1545.Nm
1546supports an auto-fetch feature.
1547To enable auto-fetch, simply pass the list of hostnames/files
1548on the command line.
1549.Pp
1550The following formats are valid syntax for an auto-fetch element:
1551.Bl -tag -width "FOO "
1552.\" [user@]host:[path][/]
1553.It Xo
1554.Sm off
1555.Op Ar user Li \&@
1556.Ar host Li \&:
1557.Op Ar path
1558.Op Li /
1559.Sm on
1560.Xc
1561.Dq Classic
1562.Tn FTP
1563format.
1564.Pp
1565If
1566.Ar path
1567contains a glob character and globbing is enabled,
1568(see
1569.Ic glob ) ,
1570then the equivalent of
1571.Ql mget path
1572is performed.
1573.Pp
1574If the directory component of
1575.Ar path
1576contains no globbing characters,
1577it is stored locally with the name basename (see
1578.Xr basename 1 )
1579of
1580.Ic path ,
1581in the current directory.
1582Otherwise, the full remote name is used as the local name,
1583relative to the local root directory.
1584.\" ftp://[user[:password]@]host[:port]/path[/][;type=X]
1585.It Xo
1586.Sm off
1587.Li ftp://
1588.Oo Ar user
1589.Op Li \&: Ar password
1590.Li \&@ Oc
1591.Ar host Oo Li \&: Ar port Oc
1592.Li / Ar path
1593.Op Li /
1594.Op Li ;type= Ar X
1595.Sm on
1596.Xc
1597An
1598.Tn FTP
1599URL, retrieved using the
1600.Tn FTP
1601protocol if
1602.Ic "set ftp_proxy"
1603isn't defined.
1604Otherwise, transfer the URL using
1605.Tn HTTP
1606via the proxy defined in
1607.Ic "set ftp_proxy" .
1608If
1609.Ic "set ftp_proxy"
1610isn't defined and
1611.Ar user
1612is given, login as
1613.Ar user .
1614In this case, use
1615.Ar password
1616if supplied, otherwise prompt the user for one.
1617.Pp
1618If a suffix of
1619.Sq ;type=A
1620or
1621.Sq ;type=I
1622is supplied, then the transfer type will take place as
1623ascii or binary (respectively).
1624The default transfer type is binary.
1625.Pp
1626In order to be compliant with
c106ca54 1627.Li RFC3986 ,
eedc536d
PA
1628.Nm
1629interprets the
1630.Ar path
1631part of an
1632.Dq ftp://
1633auto-fetch URL as follows:
1634.Bl -bullet
1635.It
1636The
1637.Sq Li /
1638immediately after the
1639.Ar host Ns Oo Li \&: Ns Ar port Oc
1640is interpreted as a separator before the
1641.Ar path ,
1642and not as part of the
1643.Ar path
1644itself.
1645.It
1646The
1647.Ar path
1648is interpreted as a
1649.So Li / Sc Ns -separated
1650list of name components.
1651For all but the last such component,
1652.Nm
1653performs the equivalent of a
1654.Ic cd
1655command.
1656For the last path component,
1657.Nm
1658performs the equivalent of a
1659.Ic get
1660command.
1661.It
1662Empty name components,
1663which result from
1664.Sq Li //
1665within the
1666.Ar path ,
1667or from an extra
1668.Sq Li /
1669at the beginning of the
1670.Ar path ,
1671will cause the equivalent of a
1672.Ic cd
1673command without a directory name.
1674This is unlikely to be useful.
1675.It
1676Any
1677.Sq Li \&% Ns Ar XX
1678codes
1679(per
c106ca54 1680.Li RFC3986 )
eedc536d
PA
1681within the path components are decoded, with
1682.Ar XX
1683representing a character code in hexadecimal.
1684This decoding takes place after the
1685.Ar path
1686has been split into components,
1687but before each component is used in the equivalent of a
1688.Ic cd
1689or
1690.Ic get
1691command.
1692Some often-used codes are
1693.Sq Li \&%2F
1694(which represents
1695.Sq Li / )
1696and
1697.Sq Li \&%7E
1698(which represents
1699.Sq Li ~ ) .
1700.El
1701.Pp
1702The above interpretation has the following consequences:
1703.Bl -bullet
1704.It
1705The path is interpreted relative to the
1706default login directory of the specified user or of the
1707.Sq anonymous
1708user.
1709If the
1710.Pa /
1711directory is required, use a leading path of
1712.Dq %2F .
1713If a user's home directory is required (and the remote server supports
1714the syntax), use a leading path of
1715.Dq %7Euser/ .
1716For example, to retrieve
1717.Pa /etc/motd
1718from
1719.Sq localhost
1720as the user
1721.Sq myname
1722with the password
1723.Sq mypass ,
1724use
1725.Dq ftp://myname:mypass@localhost/%2fetc/motd
1726.It
1727The exact
1728.Ic cd
1729and
1730.Ic get
1731commands can be controlled by careful choice of
1732where to use
1733.Sq /
1734and where to use
1735.Sq %2F
1736(or
1737.Sq %2f ) .
1738For example, the following URLs correspond to the
1739equivalents of the indicated commands:
1740.Bl -tag -width "ftp://host/%2Fdir1%2Fdir2%2Ffile"
1741.It ftp://host/dir1/dir2/file
1742.Dq "cd dir1" ,
1743.Dq "cd dir2" ,
1744.Dq "get file" .
1745.It ftp://host/%2Fdir1/dir2/file
1746.Dq "cd /dir1" ,
1747.Dq "cd dir2" ,
1748.Dq "get file" .
1749.It ftp://host/dir1%2Fdir2/file
1750.Dq "cd dir1/dir2" ,
1751.Dq "get file" .
1752.It ftp://host/%2Fdir1%2Fdir2/file
1753.Dq "cd /dir1/dir2" ,
1754.Dq "get file" .
1755.It ftp://host/dir1%2Fdir2%2Ffile
1756.Dq "get dir1/dir2/file" .
1757.It ftp://host/%2Fdir1%2Fdir2%2Ffile
1758.Dq "get /dir1/dir2/file" .
1759.El
1760.It
1761You must have appropriate access permission for each of the
1762intermediate directories that is used in the equivalent of a
1763.Ic cd
1764command.
1765.El
1766.\" http://[user[:password]@]host[:port]/path
1767.It Xo
1768.Sm off
1769.Li http://
1770.Oo Ar user
1771.Op Li \&: Ar password
1772.Li \&@ Oc
1773.Ar host Oo Li \&: Ar port Oc
1774.Li / Ar path
1775.Sm on
1776.Xc
1777An
1778.Tn HTTP
1779URL, retrieved using the
1780.Tn HTTP
1781protocol.
1782If
1783.Ic "set http_proxy"
1784is defined, it is used as a URL to an
1785.Tn HTTP
1786proxy server.
1787If
1788.Tn HTTP
1789authorization is required to retrieve
1790.Ar path ,
1791and
1792.Sq user
1793(and optionally
1794.Sq password )
1795is in the URL, use them for the first attempt to authenticate.
1796.\" file:///path
1797.It Xo
1798.Sm off
1799.Li file:/// Ar path
1800.Sm on
1801.Xc
1802A local URL, copied from
1803.Pa / Ns Ar path
1804on the local host.
c106ca54
PA
1805.\" about:
1806.It Xo
1807.Sm off
1808.Li about:
1809.Ar topic
1810.Sm on
1811.Xc
1812Display information regarding
1813.Ar topic ;
1814no file is retrieved for this auto-fetched element.
1815Supported values include:
1816.Bl -tag -width "about:version"
1817.It Li about:ftp
1818Information about
1819.Nm ftp .
1820.It Li about:version
1821The version of
1822.Nm ftp .
1823Useful to provide when reporting problems.
1824.El
eedc536d
PA
1825.El
1826.Pp
1827Unless noted otherwise above, and
1828.Fl o Ar output
1829is not given, the file is stored in the current directory as the
1830.Xr basename 1
1831of
1832.Ar path .
1833Note that if a
1834.Tn HTTP
1835redirect is received, the fetch is retried using the new target URL
1836supplied by the server, with a corresponding new
1837.Ar path .
1838Using an explicit
1839.Fl o Ar output
1840is recommended, to avoid writing to unexpected file names.
1841.Pp
1842If a classic format or an
1843.Tn FTP
1844URL format has a trailing
1845.Sq /
1846or an empty
1847.Ar path
1848component, then
1849.Nm
1850will connect to the site and
1851.Ic cd
1852to the directory given as the path, and leave the user in interactive
1853mode ready for further input.
1854This will not work if
1855.Ic "set ftp_proxy"
1856is being used.
1857.Pp
1858Direct
1859.Tn HTTP
1860transfers use HTTP 1.1.
1861Proxied
1862.Tn FTP
1863and
1864.Tn HTTP
1865transfers use HTTP 1.0.
1866.Pp
1867If
1868.Fl R
1869is given, all auto-fetches that don't go via the
1870.Tn FTP
1871or
1872.Tn HTTP
1873proxies will be restarted.
1874For
1875.Tn FTP ,
1876this is implemented by using
1877.Nm reget
1878instead of
1879.Nm get .
1880For
1881.Tn HTTP ,
1882this is implemented by using the
1883.Sq "Range: bytes="
1884.Tn "HTTP/1.1"
1885directive.
1886.Pp
1887If WWW or proxy WWW authentication is required, you will be prompted
1888to enter a username and password to authenticate with.
1889.Pp
1890When specifying IPv6 numeric addresses in a URL, you need to
1891surround the address in square brackets.
1892E.g.:
1893.Dq ftp://[::1]:21/ .
1894This is because colons are used in IPv6 numeric address as well as
1895being the separator for the port number.
1896.Sh ABORTING A FILE TRANSFER
1897To abort a file transfer, use the terminal interrupt key
1898(usually Ctrl-C).
1899Sending transfers will be immediately halted.
1900Receiving transfers will be halted by sending an
1901.Tn FTP
1902protocol
1903.Dv ABOR
1904command to the remote server, and discarding any further data received.
1905The speed at which this is accomplished depends upon the remote
1906server's support for
1907.Dv ABOR
1908processing.
1909If the remote server does not support the
1910.Dv ABOR
1911command, the prompt will not appear until the remote server has completed
1912sending the requested file.
1913.Pp
1914If the terminal interrupt key sequence is used whilst
1915.Nm
1916is awaiting a reply from the remote server for the ABOR processing,
1917then the connection will be closed.
1918This is different from the traditional behaviour (which ignores the
1919terminal interrupt during this phase), but is considered more useful.
1920.Sh FILE NAMING CONVENTIONS
1921Files specified as arguments to
1922.Nm
1923commands are processed according to the following rules.
1924.Bl -enum
1925.It
1926If the file name
1927.Sq Fl
1928is specified, the
1929.Ar stdin
1930(for reading) or
1931.Ar stdout
1932(for writing) is used.
1933.It
1934If the first character of the file name is
1935.Sq \&| ,
1936the
1937remainder of the argument is interpreted as a shell command.
1938.Nm
1939then forks a shell, using
1940.Xr popen 3
1941with the argument supplied, and reads (writes) from the stdout
1942(stdin).
1943If the shell command includes spaces, the argument
1944must be quoted; e.g.
1945.Dq Qq Li \&| ls\ \-lt .
1946A particularly
1947useful example of this mechanism is:
1948.Dq Li dir \&"\&" \&|more .
1949.It
1950Failing the above checks, if
1951.Dq globbing
1952is enabled, local file names are expanded according to the rules
1953used in the
1954.Xr csh 1 ;
1955see the
1956.Ic glob
1957command.
1958If the
1959.Nm
1960command expects a single local file (e.g.
1961.Ic put ) ,
1962only the first filename generated by the "globbing" operation is used.
1963.It
1964For
1965.Ic mget
1966commands and
1967.Ic get
1968commands with unspecified local file names, the local filename is
1969the remote filename, which may be altered by a
1970.Ic case ,
1971.Ic ntrans ,
1972or
1973.Ic nmap
1974setting.
1975The resulting filename may then be altered if
1976.Ic runique
1977is on.
1978.It
1979For
1980.Ic mput
1981commands and
1982.Ic put
1983commands with unspecified remote file names, the remote filename is
1984the local filename, which may be altered by a
1985.Ic ntrans
1986or
1987.Ic nmap
1988setting.
1989The resulting filename may then be altered by the remote server if
1990.Ic sunique
1991is on.
1992.El
1993.Sh FILE TRANSFER PARAMETERS
1994The
1995.Tn FTP
1996specification specifies many parameters which may affect a file transfer.
1997The
1998.Ic type
1999may be one of
2000.Dq ascii ,
2001.Dq image
2002(binary),
2003.Dq ebcdic ,
2004and
2005.Dq local byte size
2006(for
2007.Tn PDP Ns -10's
2008and
2009.Tn PDP Ns -20's
2010mostly).
2011.Nm
2012supports the ascii and image types of file transfer,
2013plus local byte size 8 for
2014.Ic tenex
2015mode transfers.
2016.Pp
2017.Nm
2018supports only the default values for the remaining
2019file transfer parameters:
2020.Ic mode ,
2021.Ic form ,
2022and
2023.Ic struct .
2024.Sh THE .netrc FILE
2025The
2026.Pa .netrc
2027file contains login and initialization information
2028used by the auto-login process.
2029It resides in the user's home directory,
2030unless overridden with the
2031.Fl N Ar netrc
2032option, or specified in the
2033.Ev NETRC
2034environment variable.
2035The following tokens are recognized; they may be separated by spaces,
2036tabs, or new-lines:
2037.Bl -tag -width password
2038.It Ic machine Ar name
2039Identify a remote machine
2040.Ar name .
2041The auto-login process searches the
2042.Pa .netrc
2043file for a
2044.Ic machine
2045token that matches the remote machine specified on the
2046.Nm
2047command line or as an
2048.Ic open
2049command argument.
2050Once a match is made, the subsequent
2051.Pa .netrc
2052tokens are processed,
2053stopping when the end of file is reached or another
2054.Ic machine
2055or a
2056.Ic default
2057token is encountered.
2058.It Ic default
2059This is the same as
2060.Ic machine
2061.Ar name
2062except that
2063.Ic default
2064matches any name.
2065There can be only one
2066.Ic default
2067token, and it must be after all
2068.Ic machine
2069tokens.
2070This is normally used as:
2071.Pp
2072.Dl default login anonymous password user@site
2073.Pp
2074thereby giving the user an automatic anonymous
2075.Tn FTP
2076login to
2077machines not specified in
2078.Pa .netrc .
2079This can be overridden
2080by using the
2081.Fl n
2082flag to disable auto-login.
2083.It Ic login Ar name
2084Identify a user on the remote machine.
2085If this token is present, the auto-login process will initiate
2086a login using the specified
2087.Ar name .
2088.It Ic password Ar string
2089Supply a password.
2090If this token is present, the auto-login process will supply the
2091specified string if the remote server requires a password as part
2092of the login process.
2093Note that if this token is present in the
2094.Pa .netrc
2095file for any user other
2096than
2097.Ar anonymous ,
2098.Nm
2099will abort the auto-login process if the
2100.Pa .netrc
2101is readable by
2102anyone besides the user.
2103.It Ic account Ar string
2104Supply an additional account password.
2105If this token is present, the auto-login process will supply the
2106specified string if the remote server requires an additional
2107account password, or the auto-login process will initiate an
2108.Dv ACCT
2109command if it does not.
2110.It Ic macdef Ar name
2111Define a macro.
2112This token functions like the
2113.Nm
2114.Ic macdef
2115command functions.
2116A macro is defined with the specified name; its contents begin with the
2117next
2118.Pa .netrc
2119line and continue until a blank line (consecutive new-line
2120characters) is encountered.
2121Like the other tokens in the
2122.Pa .netrc
2123file, a
2124.Ic macdef
2125is applicable only to the
2126.Ic machine
2127definition preceding it.
2128A
2129.Ic macdef
8b05fa7f 2130entry cannot be used by multiple
eedc536d
PA
2131.Ic machine
2132definitions; rather, it must be defined following each
2133.Ic machine
2134it is intended to be used with.
2135If a macro named
2136.Ic init
2137is defined, it is automatically executed as the last step in the
2138auto-login process.
2139For example,
2140.Bd -literal -offset indent
2141default
2142macdef init
2143epsv4 off
2144.Ed
2145.Pp
2146followed by a blank line.
2147.El
2148.Sh COMMAND LINE EDITING
2149.Nm
2150supports interactive command line editing, via the
2151.Xr editline 3
2152library.
2153It is enabled with the
2154.Ic edit
2155command, and is enabled by default if input is from a tty.
2156Previous lines can be recalled and edited with the arrow keys,
2157and other GNU Emacs-style editing keys may be used as well.
2158.Pp
2159The
2160.Xr editline 3
2161library is configured with a
2162.Pa .editrc
2163file - refer to
2164.Xr editrc 5
2165for more information.
2166.Pp
2167An extra key binding is available to
2168.Nm
2169to provide context sensitive command and filename completion
2170(including remote file completion).
2171To use this, bind a key to the
2172.Xr editline 3
2173command
2174.Ic ftp-complete .
2175By default, this is bound to the TAB key.
2176.Sh COMMAND LINE PROMPT
2177By default,
2178.Nm
2179displays a command line prompt of
2180.Dq "ftp\*[Gt] "
2181to the user.
2182This can be changed with the
2183.Ic "set prompt"
2184command.
2185.Pp
2186A prompt can be displayed on the right side of the screen (after the
2187command input) with the
2188.Ic "set rprompt"
2189command.
2190.Pp
2191The following formatting sequences are replaced by the given
2192information:
2193.Bl -tag -width "%% " -offset indent
2194.It Li \&%/
2195The current remote working directory.
2196.\" %c[[0]n], %.[[0]n]
2197.It Xo
2198.Sm off
2199.Li \&%c
2200.Op Oo Li 0 Oc Ar n Ns ,
2201.Li \&%.
2202.Op Oo Li 0 Oc Ar n
2203.Sm on
2204.Xc
2205The trailing component of the current remote working directory, or
2206.Em n
2207trailing components if a digit
2208.Em n
2209is given.
2210If
2211.Em n
2212begins with
2213.Sq 0 ,
2214the number of skipped components precede the trailing component(s) in
2215the format
2216.\" ``/<number>trailing''
2217.Do
2218.Sm off
2219.Li / Li \*[Lt] Va number Li \*[Gt]
2220.Va trailing
2221.Sm on
2222.Dc
2223(for
2224.Sq \&%c )
2225or
2226.\" ``...trailing''
2227.Dq Li \&... Ns Va trailing
2228(for
2229.Sq \&%. ) .
2230.It Li \&%M
2231The remote host name.
2232.It Li \&%m
2233The remote host name, up to the first
2234.Sq \&. .
2235.It Li \&%n
2236The remote user name.
2237.It Li \&%%
2238A single
2239.Sq % .
2240.El
2241.Sh ENVIRONMENT
2242.Nm
2243uses the following environment variables.
2244.Bl -tag -width "FTPSERVERPORT"
2245.It Ev FTPANONPASS
2246Password to send in an anonymous
2247.Tn FTP
2248transfer.
2249Defaults to
2250.Dq Li `whoami`@ .
2251.It Ev FTPMODE
2252Overrides the default operation mode.
2253Support values are:
2254.Bl -tag -width "passive"
2255.It Cm active
2256active mode
2257.Tn FTP
2258only
2259.It Cm auto
2260automatic determination of passive or active (this is the default)
2261.It Cm gate
2262gate-ftp mode
2263.It Cm passive
2264passive mode
2265.Tn FTP
2266only
2267.El
2268.It Ev FTPPROMPT
2269Command-line prompt to use.
2270Defaults to
2271.Dq "ftp\*[Gt] " .
2272Refer to
2273.Sx COMMAND LINE PROMPT
2274for more information.
2275.It Ev FTPRPROMPT
2276Command-line right side prompt to use.
2277Defaults to
2278.Dq "" .
2279Refer to
2280.Sx COMMAND LINE PROMPT
2281for more information.
2282.It Ev FTPSERVER
2283Host to use as gate-ftp server when
2284.Ic gate
2285is enabled.
2286.It Ev FTPSERVERPORT
2287Port to use when connecting to gate-ftp server when
2288.Ic gate
2289is enabled.
2290Default is port returned by a
2291.Fn getservbyname
2292lookup of
2293.Dq ftpgate/tcp .
2294.It Ev FTPUSERAGENT
2295The value to send for the
2296.Tn HTTP
2297User-Agent
2298header.
2299.It Ev HOME
2300For default location of a
2301.Pa .netrc
2302file, if one exists.
2303.It Ev NETRC
2304An alternate location of the
2305.Pa .netrc
2306file.
2307.It Ev PAGER
2308Used by various commands to display files.
2309Defaults to
2310.Xr more 1
2311if empty or not set.
2312.It Ev SHELL
2313For default shell.
2314.It Ev ftp_proxy
2315URL of
2316.Tn FTP
2317proxy to use when making
2318.Tn FTP
2319URL requests
2320(if not defined, use the standard
2321.Tn FTP
2322protocol).
2323.Pp
2324See
2325.Ev http_proxy
2326for further notes about proxy use.
2327.It Ev http_proxy
2328URL of
2329.Tn HTTP
2330proxy to use when making
2331.Tn HTTP
2332URL requests.
2333If proxy authentication is required and there is a username and
2334password in this URL, they will automatically be used in the first
2335attempt to authenticate to the proxy.
2336.Pp
2337If
2338.Dq unsafe
2339URL characters are required in the username or password
2340(for example
2341.Sq @
2342or
2343.Sq / ) ,
2344encode them with
c106ca54 2345.Li RFC3986
eedc536d
PA
2346.Sq Li \&% Ns Ar XX
2347encoding.
2348.Pp
2349Note that the use of a username and password in
2350.Ev ftp_proxy
2351and
2352.Ev http_proxy
2353may be incompatible with other programs that use it
2354(such as
2355.Xr lynx 1 ) .
2356.Pp
2357.Em NOTE :
2358this is not used for interactive sessions, only for command-line
2359fetches.
2360.It Ev no_proxy
2361A space or comma separated list of hosts (or domains) for which
2362proxying is not to be used.
2363Each entry may have an optional trailing ":port", which restricts
2364the matching to connections to that port.
2365.El
2366.Sh EXTENDED PASSIVE MODE AND FIREWALLS
2367Some firewall configurations do not allow
2368.Nm
2369to use extended passive mode.
2370If you find that even a simple
2371.Ic ls
2372appears to hang after printing a message such as this:
2373.Pp
2374.Dl 229 Entering Extended Passive Mode (|||58551|)
2375.Pp
2376then you will need to disable extended passive mode with
2377.Ic epsv4 off .
2378See the above section
2379.Sx The .netrc File
2380for an example of how to make this automatic.
2381.Sh SEE ALSO
2382.Xr getservbyname 3 ,
2383.Xr editrc 5 ,
2384.Xr services 5 ,
2385.Xr ftpd 8
2386.Sh STANDARDS
2387.Nm
c106ca54
PA
2388attempts to be compliant with:
2389.Bl -tag -offset indent -width 8n
2390.It Li RFC0959
2391.Em File Transfer Protocol
2392.It Li RFC1123
2393.Em Requirements for Internet Hosts - Application and Support
2394.It Li RFC1635
2395.Em How to Use Anonymous FTP
2396.It Li RFC2389
2397.Em Feature negotiation mechanism for the File Transfer Protocol
2398.It Li RFC2428
2399.Em FTP Extensions for IPv6 and NATs
2400.It Li RFC2616
2401.Em Hypertext Transfer Protocol -- HTTP/1.1
2402.It Li RFC2822
2403.Em Internet Message Format
2404.It Li RFC3659
2405.Em Extensions to FTP
2406.It Li RFC3986
2407.Em Uniform Resource Identifier (URI)
2408.El
eedc536d
PA
2409.Sh HISTORY
2410The
2411.Nm
2412command appeared in
2413.Bx 4.2 .
2414.Pp
2415Various features such as command line editing, context sensitive
2416command and file completion, dynamic progress bar, automatic
2417fetching of files and URLs, modification time preservation,
2418transfer rate throttling, configurable command line prompt,
2419and other enhancements over the standard
2420.Bx
2421.Nm
2422were implemented in
2423.Nx 1.3
2424and later releases
2425by
2426.An Luke Mewburn
2427.Aq lukem@NetBSD.org .
2428.Pp
2429IPv6 support was added by the WIDE/KAME project
2430(but may not be present in all non-NetBSD versions of this program, depending
2431if the operating system supports IPv6 in a similar manner to KAME).
2432.Sh BUGS
2433Correct execution of many commands depends upon proper behavior
2434by the remote server.
2435.Pp
2436An error in the treatment of carriage returns
2437in the
2438.Bx 4.2
2439ascii-mode transfer code
2440has been corrected.
2441This correction may result in incorrect transfers of binary files
2442to and from
2443.Bx 4.2
2444servers using the ascii type.
2445Avoid this problem by using the binary image type.
2446.Pp
2447.Nm
2448assumes that all IPv4 mapped addresses
2449.Po
2450IPv6 addresses with a form like
2451.Li ::ffff:10.1.1.1
2452.Pc
2453indicate IPv4 destinations which can be handled by
2454.Dv AF_INET
2455sockets.
2456However, in certain IPv6 network configurations, this assumption is not true.
2457In such an environment, IPv4 mapped addresses must be passed to
2458.Dv AF_INET6
2459sockets directly.
2460For example, if your site uses a SIIT translator for IPv6-to-IPv4 translation,
2461.Nm
2462is unable to support your configuration.