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