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