1 .\" Copyright (c) 1985, 1989, 1990 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" from: @(#)ftp.1 6.18 (Berkeley) 7/30/91
36 .Os "Linux NetKit (0.17)"
51 is the user interface to the
53 standard File Transfer Protocol.
54 The program allows a user to transfer files to and from a
57 Options may be specified at the command line, or to the
61 Use passive mode for data transfers. Allows use of ftp in environments
62 where a firewall prevents connections from the outside world back to
63 the client machine. Requires that the ftp server support the PASV
64 command. This is the default now for
66 clients (ftp and pftp) due to security concerns using the PORT transfer mode.
67 The flag is kept for compatibility only and has no effect anymore.
69 Turns off interactive prompting during multiple file transfers.
73 from attempting \*(Lqauto-login\*(Rq upon initial connection.
74 If auto-login is enabled,
80 file in the user's home directory for an entry describing
81 an account on the remote machine.
84 will prompt for the remote machine login name (default is the user
85 identity on the local machine), and, if necessary, prompt for a password
86 and an account with which to login.
88 Disables command editing and history support, if it was compiled into
91 executable. Otherwise, does nothing.
93 Disables file name globbing.
97 to show all responses from the remote server, as well
98 as report on data transfer statistics.
103 The client host with which
105 is to communicate may be specified on the command line.
108 will immediately attempt to establish a connection to an
110 server on that host; otherwise,
112 will enter its command interpreter and await instructions
116 is awaiting commands from the user the prompt
118 is provided to the user.
119 The following commands are recognized
123 .It Ic \&! Op Ar command Op Ar args
124 Invoke an interactive shell on the local machine.
125 If there are arguments, the first is taken to be a command to execute
126 directly, with the rest of the arguments as its arguments.
127 .It Ic \&$ Ar macro-name Op Ar args
130 that was defined with the
133 Arguments are passed to the macro unglobbed.
134 .It Ic account Op Ar passwd
135 Supply a supplemental password required by a remote system for access
136 to resources once a login has been successfully completed.
137 If no argument is included, the user will be prompted for an account
138 password in a non-echoing input mode.
139 .It Ic append Ar local-file Op Ar remote-file
140 Append a local file to a file on the remote machine.
143 is left unspecified, the local file name is used in naming the
144 remote file after being altered by any
149 File transfer uses the current settings for
156 Set the file transfer
160 This is the default type.
162 Arrange that a bell be sounded after each file transfer
163 command is completed.
165 Set the file transfer
167 to support binary image transfer.
171 session with the remote server
174 An end of file will also terminate the session and exit.
176 Toggle remote computer file name case mapping during
181 is on (default is off), remote computer file names with all letters in
182 upper case are written in the local directory with the letters mapped
184 .It Ic \&cd Ar remote-directory
185 Change the working directory on the remote machine
187 .Ar remote-directory .
189 Change the remote machine working directory to the parent of the
190 current remote machine working directory.
191 .It Ic chmod Ar mode file-name
192 Change the permission modes of the file
200 session with the remote server, and
201 return to the command interpreter.
202 Any defined macros are erased.
204 Toggle carriage return stripping during
205 ascii type file retrieval.
206 Records are denoted by a carriage return/linefeed sequence
207 during ascii type file transfer.
210 is on (the default), carriage returns are stripped from this
211 sequence to conform with the
213 single linefeed record
217 remote systems may contain single linefeeds;
218 when an ascii type transfer is made, these linefeeds may be
219 distinguished from a record delimiter only when
222 .It Ic delete Ar remote-file
225 on the remote machine.
226 .It Ic debug Op Ar debug-value
227 Toggle debugging mode.
230 is specified it is used to set the debugging level.
231 When debugging is on,
233 prints each command sent to the remote machine, preceded
238 .Op Ar remote-directory
241 Print a listing of the directory contents in the
243 .Ar remote-directory ,
244 and, optionally, placing the output in
246 If interactive prompting is on,
248 will prompt the user to verify that the last argument is indeed the
249 target local file for receiving
252 If no directory is specified, the current working
253 directory on the remote machine is used.
255 file is specified, or
259 output comes to the terminal.
263 .It Ic form Ar format
264 Set the file transfer
268 The default format is \*(Lqfile\*(Rq.
269 .It Ic get Ar remote-file Op Ar local-file
272 and store it on the local machine.
274 file name is not specified, it is given the same
275 name it has on the remote machine, subject to
276 alteration by the current
282 The current settings for
288 are used while transferring the file.
290 Toggle filename expansion for
295 If globbing is turned off with
297 the file name arguments
298 are taken literally and not expanded.
307 each remote file name is expanded
308 separately on the remote machine and the lists are not merged.
309 Expansion of a directory name is likely to be
310 different from expansion of the name of an ordinary file:
311 the exact result depends on the foreign operating system and ftp server,
312 and can be previewed by doing
313 .Ql mls remote-files \-
318 are not meant to transfer
319 entire directory subtrees of files.
323 archive of the subtree (in binary mode).
325 Toggle hash-sign (``#'') printing for each data block
327 The size of a data block is 1024 bytes.
328 .It Ic help Op Ar command
329 Print an informative message about the meaning of
331 If no argument is given,
333 prints a list of the known commands.
334 .It Ic idle Op Ar seconds
335 Set the inactivity timer on the remote server to
340 is ommitted, the current inactivity timer is printed.
341 .It Ic lcd Op Ar directory
342 Change the working directory on the local machine.
346 is specified, the user's home directory is used.
349 .Op Ar remote-directory
352 Print a listing of the contents of a
353 directory on the remote machine.
354 The listing includes any system-dependent information that the server
355 chooses to include; for example, most
358 output from the command
364 is left unspecified, the current working directory is used.
365 If interactive prompting is on,
367 will prompt the user to verify that the last argument is indeed the
368 target local file for receiving
371 If no local file is specified, or if
375 the output is sent to the terminal.
376 .It Ic macdef Ar macro-name
378 Subsequent lines are stored as the macro
380 a null line (consecutive newline characters
382 carriage returns from the terminal) terminates macro input mode.
383 There is a limit of 16 macros and 4096 total characters in all
385 Macros remain defined until a
388 The macro processor interprets `$' and `\e' as special characters.
389 A `$' followed by a number (or numbers) is replaced by the
390 corresponding argument on the macro invocation command line.
391 A `$' followed by an `i' signals that macro processor that the
392 executing macro is to be looped.
393 On the first pass `$i' is
394 replaced by the first argument on the macro invocation command line,
395 on the second pass it is replaced by the second argument, and so on.
396 A `\e' followed by any character is replaced by that character.
397 Use the `\e' to prevent special treatment of the `$'.
398 .It Ic mdelete Op Ar remote-files
401 on the remote machine.
402 .It Ic mdir Ar remote-files local-file
405 except multiple remote files may be specified.
406 If interactive prompting is on,
408 will prompt the user to verify that the last argument is indeed the
409 target local file for receiving
412 .It Ic mget Ar remote-files
415 on the remote machine
418 for each file name thus produced.
421 for details on the filename expansion.
422 Resulting file names will then be processed according to
428 Files are transferred into the local working directory,
429 which can be changed with
431 new local directories can be created with
432 .Ql "\&! mkdir directory" .
433 .It Ic mkdir Ar directory-name
434 Make a directory on the remote machine.
435 .It Ic mls Ar remote-files local-file
438 except multiple remote files may be specified,
442 If interactive prompting is on,
444 will prompt the user to verify that the last argument is indeed the
445 target local file for receiving
448 .It Ic mode Op Ar mode-name
449 Set the file transfer
453 The default mode is \*(Lqstream\*(Rq mode.
454 .It Ic modtime Ar file-name
455 Show the last modification time of the file on the remote machine.
456 .It Ic mput Ar local-files
457 Expand wild cards in the list of local files given as arguments
460 for each file in the resulting list.
463 for details of filename expansion.
464 Resulting file names will then be processed according to
469 .It Ic newer Ar file-name Op Ar local-file
470 Get the file only if the modification time of the remote file is more
471 recent that the file on the current system.
473 exist on the current system, the remote file is considered
475 Otherwise, this command is identical to
479 .Op Ar remote-directory
482 Print a list of the files in a
483 directory on the remote machine.
486 is left unspecified, the current working directory is used.
487 If interactive prompting is on,
489 will prompt the user to verify that the last argument is indeed the
490 target local file for receiving
493 If no local file is specified, or if
497 the output is sent to the terminal.
498 .It Ic nmap Op Ar inpattern outpattern
499 Set or unset the filename mapping mechanism.
500 If no arguments are specified, the filename mapping mechanism is unset.
501 If arguments are specified, remote filenames are mapped during
505 commands issued without a specified remote target filename.
506 If arguments are specified, local filenames are mapped during
510 commands issued without a specified local target filename.
511 This command is useful when connecting to a
514 with different file naming conventions or practices.
515 The mapping follows the pattern set by
520 is a template for incoming filenames (which may have already been
521 processed according to the
526 Variable templating is accomplished by including the
527 sequences `$1', `$2', ..., `$9' in
529 Use `\\' to prevent this special treatment of the `$' character.
530 All other characters are treated literally, and are used to determine the
536 $1.$2 and the remote file name "mydata.data", $1 would have the value
537 "mydata", and $2 would have the value "data".
540 determines the resulting mapped filename.
541 The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
545 The sequence `$0' is replace by the original filename.
546 Additionally, the sequence
547 .Ql Op Ar seq1 , Ar seq2
552 is not a null string; otherwise it is replaced by
554 For example, the command
556 .Bd -literal -offset indent -compact
557 nmap $1.$2.$3 [$1,$2].[$2,file]
561 the output filename "myfile.data" for input filenames "myfile.data" and
562 "myfile.data.old", "myfile.file" for the input filename "myfile", and
563 "myfile.myfile" for the input filename ".myfile".
564 Spaces may be included in
566 as in the example: `nmap $1 sed "s/ *$//" > $1' .
567 Use the `\e' character to prevent special treatment
568 of the `$','[','[', and `,' characters.
569 .It Ic ntrans Op Ar inchars Op Ar outchars
570 Set or unset the filename character translation mechanism.
571 If no arguments are specified, the filename character
572 translation mechanism is unset.
573 If arguments are specified, characters in
574 remote filenames are translated during
578 commands issued without a specified remote target filename.
579 If arguments are specified, characters in
580 local filenames are translated during
584 commands issued without a specified local target filename.
585 This command is useful when connecting to a
588 with different file naming conventions or practices.
589 Characters in a filename matching a character in
591 are replaced with the corresponding character in
593 If the character's position in
595 is longer than the length of
597 the character is deleted from the file name.
598 .It Ic open Ar host Op Ar port
599 Establish a connection to the specified
603 An optional port number may be supplied,
606 will attempt to contact an
611 option is on (default),
613 will also attempt to automatically log the user in to
618 Toggle interactive prompting.
619 Interactive prompting
620 occurs during multiple file transfers to allow the
621 user to selectively retrieve or store files.
622 If prompting is turned off (default is on), any
626 will transfer all files, and any
628 will delete all files.
629 .It Ic proxy Ar ftp-command
630 Execute an ftp command on a secondary control connection.
631 This command allows simultaneous connection to two remote ftp
632 servers for transferring files between the two servers.
637 to establish the secondary control connection.
638 Enter the command "proxy ?" to see other ftp commands executable on the
639 secondary connection.
640 The following commands behave differently when prefaced by
643 will not define new macros during the auto-login process,
645 will not erase existing macro definitions,
649 transfer files from the host on the primary control connection
650 to the host on the secondary control connection, and
655 transfer files from the host on the secondary control connection
656 to the host on the primary control connection.
657 Third party file transfers depend upon support of the ftp protocol
659 command by the server on the secondary control connection.
660 .It Ic put Ar local-file Op Ar remote-file
661 Store a local file on the remote machine.
664 is left unspecified, the local file name is used
665 after processing according to any
670 in naming the remote file.
671 File transfer uses the
679 Print the name of the current working directory on the remote
684 .It Ic quote Ar arg1 arg2 ...
685 The arguments specified are sent, verbatim, to the remote
688 .It Ic recv Ar remote-file Op Ar local-file
690 .It Ic reget Ar remote-file Op Ar local-file
691 Reget acts like get, except that if
698 a partially transferred copy of
701 is continued from the apparent point of failure.
703 is useful when transferring very large files over networks that
704 are prone to dropping connections.
705 .It Ic remotehelp Op Ar command-name
706 Request help from the remote
711 is specified it is supplied to the server as well.
712 .It Ic remotestatus Op Ar file-name
713 With no arguments, show status of remote machine.
716 is specified, show status of
726 on the remote machine, to the file
730 This command re-synchronizes command/reply sequencing with the remote
732 Resynchronization may be necessary following a violation of the ftp protocol
733 by the remote server.
734 .It Ic restart Ar marker
735 Restart the immediately following
744 systems, marker is usually a byte
745 offset into the file.
746 .It Ic rmdir Ar directory-name
747 Delete a directory on the remote machine.
749 Toggle storing of files on the local system with unique filenames.
750 If a file already exists with a name equal to the target
755 command, a ".1" is appended to the name.
756 If the resulting name matches another existing file,
757 a ".2" is appended to the original name.
758 If this process continues up to ".99", an error
759 message is printed, and the transfer does not take place.
760 The generated unique filename will be reported.
763 will not affect local files generated from a shell command
765 The default value is off.
766 .It Ic send Ar local-file Op Ar remote-file
774 will attempt to use a
776 command when establishing
777 a connection for each data transfer.
780 commands can prevent delays
781 when performing multiple file transfers.
786 will use the default data port.
789 commands is disabled, no attempt will be made to use
791 commands for each data transfer.
795 implementations which do ignore
797 commands but, incorrectly, indicate they've been accepted.
798 .It Ic site Ar arg1 arg2 ...
799 The arguments specified are sent, verbatim, to the remote
804 .It Ic size Ar file-name
809 Show the current status of
811 .It Ic struct Op Ar struct-name
812 Set the file transfer
816 By default \*(Lqstream\*(Rq structure is used.
818 Toggle storing of files on remote machine under unique file names.
819 Remote ftp server must support ftp protocol
822 successful completion.
823 The remote server will report unique name.
824 Default value is off.
826 Show the type of operating system running on the remote machine.
828 Set the file transfer type to that needed to
833 Toggle packet tracing.
834 .It Ic type Op Ar type-name
835 Set the file transfer
839 If no type is specified, the current type
841 The default type is network
843 .It Ic umask Op Ar newmask
844 Set the default umask on the remote server to
848 is ommitted, the current umask is printed.
850 .Ic user Ar user-name
854 Identify yourself to the remote
859 is not specified and the server requires it,
861 will prompt the user for it (after disabling local echo).
864 field is not specified, and the
867 requires it, the user will be prompted for it.
870 field is specified, an account command will
871 be relayed to the remote server after the login sequence
872 is completed if the remote server did not require it
876 is invoked with \*(Lqauto-login\*(Rq disabled, this
877 process is done automatically on initial connection to
883 In verbose mode, all responses from
886 server are displayed to the user.
888 if verbose is on, when a file transfer completes, statistics
889 regarding the efficiency of the transfer are reported.
892 .It Ic ? Op Ar command
896 Command arguments which have embedded spaces may be quoted with
898 .Sh ABORTING A FILE TRANSFER
899 To abort a file transfer, use the terminal interrupt key
901 Sending transfers will be immediately halted.
902 Receiving transfers will be halted by sending a ftp protocol
904 command to the remote server, and discarding any further data received.
905 The speed at which this is accomplished depends upon the remote
909 If the remote server does not support the
913 prompt will not appear until the remote server has completed
914 sending the requested file.
916 The terminal interrupt key sequence will be ignored when
918 has completed any local processing and is awaiting a reply
919 from the remote server.
920 A long delay in this mode may result from the ABOR processing described
921 above, or from unexpected behavior by the remote server, including
922 violations of the ftp protocol.
923 If the delay results from unexpected remote server behavior, the local
925 program must be killed by hand.
926 .Sh FILE NAMING CONVENTIONS
927 Files specified as arguments to
929 commands are processed according to the following rules.
938 (for writing) is used.
940 If the first character of the file name is
943 remainder of the argument is interpreted as a shell command.
945 then forks a shell, using
947 with the argument supplied, and reads (writes) from the stdout
949 If the shell command includes spaces, the argument
953 useful example of this mechanism is: \*(Lqdir more\*(Rq.
955 Failing the above checks, if ``globbing'' is enabled,
956 local file names are expanded
957 according to the rules used in the
964 command expects a single local file (.e.g.
966 only the first filename generated by the "globbing" operation is used.
972 commands with unspecified local file names, the local filename is
973 the remote filename, which may be altered by a
979 The resulting filename may then be altered if
987 commands with unspecified remote file names, the remote filename is
988 the local filename, which may be altered by a
993 The resulting filename may then be altered by the remote server if
997 .Sh FILE TRANSFER PARAMETERS
998 The FTP specification specifies many parameters which may
999 affect a file transfer.
1002 may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary),
1003 \*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for
1009 supports the ascii and image types of file transfer,
1010 plus local byte size 8 for
1015 supports only the default values for the remaining
1016 file transfer parameters:
1023 utilizes the following environment variables.
1026 For default location of a
1028 file, if one exists.
1041 Correct execution of many commands depends upon proper behavior
1042 by the remote server.
1044 An error in the treatment of carriage returns
1047 ascii-mode transfer code
1049 This correction may result in incorrect transfers of binary files
1052 servers using the ascii type.
1053 Avoid this problem by using the binary image type.