Imported upstream version 1.5
[manpages-zh.git] / raw / man1 / ftp.1
blobb8fe29b71d41275568b9fc62e7a8d93fb3737b95
1 .\" Copyright (c) 1985, 1989, 1990 The Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
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.
19 .\"
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
30 .\" SUCH DAMAGE.
31 .\"
32 .\"     from: @(#)ftp.1 6.18 (Berkeley) 7/30/91
33 .\"
34 .Dd August 15, 1999
35 .Dt FTP 1
36 .Os "Linux NetKit (0.17)"
37 .Sh NAME
38 .Nm ftp
39 .Nd
40 .Tn Internet
41 file transfer program
42 .Sh SYNOPSIS
43 .Nm ftp
44 .Op Fl pinegvd
45 .Op Ar host
46 .Nm pftp
47 .Op Fl inegvd
48 .Op Ar host
49 .Sh DESCRIPTION
50 .Nm Ftp
51 is the user interface to the
52 .Tn Internet
53 standard File Transfer Protocol.
54 The program allows a user to transfer files to and from a
55 remote network site.
56 .Pp
57 Options may be specified at the command line, or to the
58 command interpreter.
59 .Bl -tag -width flag
60 .It Fl p
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
65 .Nm all
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.
68 .It Fl i
69 Turns off interactive prompting during multiple file transfers.
70 .It Fl n
71 Restrains
72 .Nm ftp
73 from attempting \*(Lqauto-login\*(Rq upon initial connection.
74 If auto-login is enabled,
75 .Nm ftp
76 will check the
77 .Pa .netrc
78 (see 
79 .Xr netrc 5) 
80 file in the user's home directory for an entry describing
81 an account on the remote machine.
82 If no entry exists,
83 .Nm ftp
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.
87 .It Fl e
88 Disables command editing and history support, if it was compiled into
89 the
90 .Nm ftp
91 executable. Otherwise, does nothing.
92 .It Fl g
93 Disables file name globbing.
94 .It Fl v
95 Verbose option forces
96 .Nm ftp
97 to show all responses from the remote server, as well
98 as report on data transfer statistics.
99 .It Fl d
100 Enables debugging.
103 The client host with which
104 .Nm ftp
105 is to communicate may be specified on the command line.
106 If this is done,
107 .Nm ftp
108 will immediately attempt to establish a connection to an
109 .Tn FTP
110 server on that host; otherwise,
111 .Nm ftp
112 will enter its command interpreter and await instructions
113 from the user.
114 When
115 .Nm ftp
116 is awaiting commands from the user the prompt
117 .Ql ftp>
118 is provided to the user.
119 The following commands are recognized
121 .Nm ftp  :
122 .Bl -tag -width Fl
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
128 Execute the macro
129 .Ar macro-name
130 that was defined with the
131 .Ic macdef
132 command.
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.
142 .Ar remote-file
143 is left unspecified, the local file name is used in naming the
144 remote file after being altered by any
145 .Ic ntrans
147 .Ic nmap
148 setting.
149 File transfer uses the current settings for
150 .Ic type  ,
151 .Ic format ,
152 .Ic mode  ,
154 .Ic structure .
155 .It Ic ascii
156 Set the file transfer
157 .Ic type
158 to network
159 .Tn ASCII .
160 This is the default type.
161 .It Ic bell
162 Arrange that a bell be sounded after each file transfer
163 command is completed.
164 .It Ic binary
165 Set the file transfer
166 .Ic type
167 to support binary image transfer.
168 .It Ic bye
169 Terminate the
170 .Tn FTP
171 session with the remote server
172 and exit
173 .Nm ftp  .
174 An end of file will also terminate the session and exit.
175 .It Ic case
176 Toggle remote computer file name case mapping during
177 .Ic mget
178 commands.
179 When
180 .Ic case
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
183 to lower case.
184 .It Ic \&cd Ar remote-directory
185 Change the working directory on the remote machine
187 .Ar remote-directory  .
188 .It Ic cdup
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
193 .Ar file-name
194 on the remote
195 sytem to
196 .Ar mode  .
197 .It Ic close
198 Terminate the
199 .Tn FTP
200 session with the remote server, and
201 return to the command interpreter.
202 Any defined macros are erased.
203 .It Ic \&cr
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.
208 When
209 .Ic \&cr
210 is on (the default), carriage returns are stripped from this
211 sequence to conform with the
213 single linefeed record
214 delimiter.
215 Records on
216 .Pf non\- Ns Ux
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
220 .Ic \&cr
221 is off.
222 .It Ic delete Ar remote-file
223 Delete the file
224 .Ar remote-file
225 on the remote machine.
226 .It Ic debug Op Ar debug-value
227 Toggle debugging mode.
228 If an optional
229 .Ar debug-value
230 is specified it is used to set the debugging level.
231 When debugging is on,
232 .Nm ftp
233 prints each command sent to the remote machine, preceded
234 by the string
235 .Ql \-\->
236 .It Xo
237 .Ic dir
238 .Op Ar remote-directory
239 .Op Ar local-file
241 Print a listing of the directory contents in the
242 directory,
243 .Ar remote-directory  ,
244 and, optionally, placing the output in
245 .Ar local-file  .
246 If interactive prompting is on,
247 .Nm ftp
248 will prompt the user to verify that the last argument is indeed the
249 target local file for receiving
250 .Ic dir
251 output.
252 If no directory is specified, the current working
253 directory on the remote machine is used.
254 If no local
255 file is specified, or
256 .Ar local-file
258 .Fl  ,
259 output comes to the terminal.
260 .It Ic disconnect
261 A synonym for
262 .Ar close  .
263 .It Ic form Ar format
264 Set the file transfer
265 .Ic form
267 .Ar format  .
268 The default format is \*(Lqfile\*(Rq.
269 .It Ic get Ar remote-file Op Ar local-file
270 Retrieve the
271 .Ar remote-file
272 and store it on the local machine.
273 If the local
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
277 .Ic case  ,
278 .Ic ntrans ,
280 .Ic nmap
281 settings.
282 The current settings for
283 .Ic type  ,
284 .Ic form ,
285 .Ic mode  ,
287 .Ic structure
288 are used while transferring the file.
289 .It Ic glob
290 Toggle filename expansion for
291 .Ic mdelete  ,
292 .Ic mget
294 .Ic mput  .
295 If globbing is turned off with
296 .Ic glob  ,
297 the file name arguments
298 are taken literally and not expanded.
299 Globbing for
300 .Ic mput
301 is done as in
302 .Xr csh 1 .
304 .Ic mdelete
306 .Ic mget  ,
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 \-
314 Note:
315 .Ic mget
317 .Ic mput
318 are not meant to transfer
319 entire directory subtrees of files.
320 That can be done by
321 transferring a
322 .Xr tar 1
323 archive of the subtree (in binary mode).
324 .It Ic hash
325 Toggle hash-sign (``#'') printing for each data block
326 transferred.
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
330 .Ar command  .
331 If no argument is given,
332 .Nm ftp
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
336 .Ar seconds
337 seconds.
339 .Ar seconds
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.
345 .Ar directory
346 is specified, the user's home directory is used.
347 .It Xo
348 .Ic \&ls
349 .Op Ar remote-directory
350 .Op Ar local-file
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
357 systems will produce
358 output from the command
359 .Ql ls \-l .
360 (See also
361 .Ic nlist . )
363 .Ar remote-directory
364 is left unspecified, the current working directory is used.
365 If interactive prompting is on,
366 .Nm ftp
367 will prompt the user to verify that the last argument is indeed the
368 target local file for receiving
369 .Ic \&ls
370 output.
371 If no local file is specified, or if
372 .Ar local-file
374 .Sq Fl ,
375 the output is sent to the terminal.
376 .It Ic macdef Ar macro-name
377 Define a macro.
378 Subsequent lines are stored as the macro
379 .Ar macro-name  ;
380 a null line (consecutive newline characters
381 in a file or
382 carriage returns from the terminal) terminates macro input mode.
383 There is a limit of 16 macros and 4096 total characters in all
384 defined macros.
385 Macros remain defined until a
386 .Ic close
387 command is executed.
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
399 Delete the
400 .Ar remote-files
401 on the remote machine.
402 .It Ic mdir Ar remote-files local-file
403 Like
404 .Ic dir  ,
405 except multiple remote files may be specified.
406 If interactive prompting is on,
407 .Nm ftp
408 will prompt the user to verify that the last argument is indeed the
409 target local file for receiving
410 .Ic mdir
411 output.
412 .It Ic mget Ar remote-files
413 Expand the
414 .Ar remote-files
415 on the remote machine
416 and do a
417 .Ic get
418 for each file name thus produced.
420 .Ic glob
421 for details on the filename expansion.
422 Resulting file names will then be processed according to
423 .Ic case  ,
424 .Ic ntrans ,
426 .Ic nmap
427 settings.
428 Files are transferred into the local working directory,
429 which can be changed with
430 .Ql lcd directory ;
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
436 Like
437 .Ic nlist  ,
438 except multiple remote files may be specified,
439 and the
440 .Ar local-file
441 must be specified.
442 If interactive prompting is on,
443 .Nm ftp
444 will prompt the user to verify that the last argument is indeed the
445 target local file for receiving
446 .Ic mls
447 output.
448 .It Ic mode Op Ar mode-name
449 Set the file transfer
450 .Ic mode
452 .Ar mode-name  .
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
458 and do a
459 .Ic put
460 for each file in the resulting list.
462 .Ic glob
463 for details of filename expansion.
464 Resulting file names will then be processed according to
465 .Ic ntrans
467 .Ic nmap
468 settings.
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.
472 If the file does not
473 exist on the current system, the remote file is considered
474 .Ic newer  .
475 Otherwise, this command is identical to
476 .Ar get  .
477 .It Xo
478 .Ic nlist
479 .Op Ar remote-directory
480 .Op Ar local-file
482 Print a  list of the files in a
483 directory on the remote machine.
485 .Ar remote-directory
486 is left unspecified, the current working directory is used.
487 If interactive prompting is on,
488 .Nm ftp
489 will prompt the user to verify that the last argument is indeed the
490 target local file for receiving
491 .Ic nlist
492 output.
493 If no local file is specified, or if
494 .Ar local-file
496 .Fl  ,
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
502 .Ic mput
503 commands and
504 .Ic put
505 commands issued without a specified remote target filename.
506 If arguments are specified, local filenames are mapped during
507 .Ic mget
508 commands and
509 .Ic get
510 commands issued without a specified local target filename.
511 This command is useful when connecting to a
512 .No non\- Ns Ux
513 remote computer
514 with different file naming conventions or practices.
515 The mapping follows the pattern set by
516 .Ar inpattern
518 .Ar outpattern  .
519 .Op Ar Inpattern
520 is a template for incoming filenames (which may have already been
521 processed according to the
522 .Ic ntrans
524 .Ic case
525 settings).
526 Variable templating is accomplished by including the
527 sequences `$1', `$2', ..., `$9' in
528 .Ar inpattern  .
529 Use `\\' to prevent this special treatment of the `$' character.
530 All other characters are treated literally, and are used to determine the
531 .Ic nmap
532 .Op Ar inpattern
533 variable values.
534 For example, given
535 .Ar inpattern
536 $1.$2 and the remote file name "mydata.data", $1 would have the value
537 "mydata", and $2 would have the value "data".
539 .Ar outpattern
540 determines the resulting mapped filename.
541 The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
542 from the
543 .Ar inpattern
544 template.
545 The sequence `$0' is replace by the original filename.
546 Additionally, the sequence
547 .Ql Op Ar seq1 , Ar seq2
548 is replaced by
549 .Op Ar seq1
551 .Ar seq1
552 is not a null string; otherwise it is replaced by
553 .Ar seq2 .
554 For example, the command
556 .Bd -literal -offset indent -compact
557 nmap $1.$2.$3 [$1,$2].[$2,file]
560 would yield
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
565 .Ar outpattern  ,
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
575 .Ic mput
576 commands and
577 .Ic put
578 commands issued without a specified remote target filename.
579 If arguments are specified, characters in
580 local filenames are translated during
581 .Ic mget
582 commands and
583 .Ic get
584 commands issued without a specified local target filename.
585 This command is useful when connecting to a
586 .No non\- Ns Ux
587 remote computer
588 with different file naming conventions or practices.
589 Characters in a filename matching a character in
590 .Ar inchars
591 are replaced with the corresponding character in
592 .Ar outchars  .
593 If the character's position in
594 .Ar inchars
595 is longer than the length of
596 .Ar outchars  ,
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
600 .Ar host
601 .Tn FTP
602 server.
603 An optional port number may be supplied,
604 in which case,
605 .Nm ftp
606 will attempt to contact an
607 .Tn FTP
608 server at that port.
609 If the
610 .Ic auto-login
611 option is on (default),
612 .Nm ftp
613 will also attempt to automatically log the user in to
615 .Tn FTP
616 server (see below).
617 .It Ic prompt
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
623 .Ic mget
625 .Ic mput
626 will transfer all files, and any
627 .Ic mdelete
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.
633 The first
634 .Ic proxy
635 command should be an
636 .Ic open  ,
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
641 .Ic proxy  :
642 .Ic open
643 will not define new macros during the auto-login process,
644 .Ic close
645 will not erase existing macro definitions,
646 .Ic get
648 .Ic mget
649 transfer files from the host on the primary control connection
650 to the host on the secondary control connection, and
651 .Ic put  ,
652 .Ic mput ,
654 .Ic append
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
658 .Dv PASV
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.
663 .Ar remote-file
664 is left unspecified, the local file name is used
665 after processing according to any
666 .Ic ntrans
668 .Ic nmap
669 settings
670 in naming the remote file.
671 File transfer uses the
672 current settings for
673 .Ic type  ,
674 .Ic format ,
675 .Ic mode  ,
677 .Ic structure  .
678 .It Ic pwd
679 Print the name of the current working directory on the remote
680 machine.
681 .It Ic quit
682 A synonym for
683 .Ic bye  .
684 .It Ic quote Ar arg1 arg2 ...
685 The arguments specified are sent, verbatim, to the remote
686 .Tn FTP
687 server.
688 .It Ic recv Ar remote-file Op Ar local-file
689 A synonym for get.
690 .It Ic reget Ar remote-file Op Ar local-file
691 Reget acts like get, except that if
692 .Ar local-file
693 exists and is
694 smaller than
695 .Ar remote-file  ,
696 .Ar local-file
697 is presumed to be
698 a partially transferred copy of
699 .Ar remote-file
700 and the transfer
701 is continued from the apparent point of failure.
702 This command
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
707 .Tn FTP
708 server.
709 If a
710 .Ar command-name
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.
715 .Ar file-name
716 is specified, show status of
717 .Ar file-name
718 on remote machine.
719 .It Xo
720 .Ic rename
721 .Op Ar from
722 .Op Ar to
724 Rename the file
725 .Ar from
726 on the remote machine, to the file
727 .Ar to  .
728 .It Ic reset
729 Clear reply queue.
730 This command re-synchronizes command/reply sequencing with the remote
731 ftp server.
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
736 .Ic get
738 .Ic put
739 at the
740 indicated
741 .Ar marker  .
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.
748 .It Ic runique
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
751 local filename for a
752 .Ic get
754 .Ic mget
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.
761 Note that
762 .Ic runique
763 will not affect local files generated from a shell command
764 (see below).
765 The default value is off.
766 .It Ic send Ar local-file Op Ar remote-file
767 A synonym for put.
768 .It Ic sendport
769 Toggle the use of
770 .Dv PORT
771 commands.
772 By default,
773 .Nm ftp
774 will attempt to use a
775 .Dv PORT
776 command when establishing
777 a connection for each data transfer.
778 The use of
779 .Dv PORT
780 commands can prevent delays
781 when performing multiple file transfers.
782 If the
783 .Dv PORT
784 command fails,
785 .Nm ftp
786 will use the default data port.
787 When the use of
788 .Dv PORT
789 commands is disabled, no attempt will be made to use
790 .Dv PORT
791 commands for each data transfer.
792 This is useful
793 for certain
794 .Tn FTP
795 implementations which do ignore
796 .Dv PORT
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
800 .Tn FTP
801 server as a
802 .Dv SITE
803 command.
804 .It Ic size Ar file-name
805 Return size of
806 .Ar file-name
807 on remote machine.
808 .It Ic status
809 Show the current status of
810 .Nm ftp  .
811 .It Ic struct Op Ar struct-name
812 Set the file transfer
813 .Ar structure
815 .Ar struct-name .
816 By default \*(Lqstream\*(Rq structure is used.
817 .It Ic sunique
818 Toggle storing of files on remote machine under unique file names.
819 Remote ftp server must support ftp protocol
820 .Dv STOU
821 command for
822 successful completion.
823 The remote server will report unique name.
824 Default value is off.
825 .It Ic system
826 Show the type of operating system running on the remote machine.
827 .It Ic tenex
828 Set the file transfer type to that needed to
829 talk to
830 .Tn TENEX
831 machines.
832 .It Ic trace
833 Toggle packet tracing.
834 .It Ic type Op Ar type-name
835 Set the file transfer
836 .Ic type
838 .Ar type-name  .
839 If no type is specified, the current type
840 is printed.
841 The default type is network
842 .Tn ASCII .
843 .It Ic umask Op Ar newmask
844 Set the default umask on the remote server to
845 .Ar newmask  .
847 .Ar newmask
848 is ommitted, the current umask is printed.
849 .It Xo
850 .Ic user Ar user-name
851 .Op Ar password
852 .Op Ar account
854 Identify yourself to the remote
855 .Tn FTP
856 server.
857 If the
858 .Ar password
859 is not specified and the server requires it,
860 .Nm ftp
861 will prompt the user for it (after disabling local echo).
862 If an
863 .Ar account
864 field is not specified, and the
865 .Tn FTP
866 server
867 requires it, the user will be prompted for it.
868 If an
869 .Ar account
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
873 for logging in.
874 Unless
875 .Nm ftp
876 is invoked with \*(Lqauto-login\*(Rq disabled, this
877 process is done automatically on initial connection to
879 .Tn FTP
880 server.
881 .It Ic verbose
882 Toggle verbose mode.
883 In verbose mode, all responses from
885 .Tn FTP
886 server are displayed to the user.
887 In addition,
888 if verbose is on, when a file transfer completes, statistics
889 regarding the efficiency of the transfer are reported.
890 By default,
891 verbose is on.
892 .It Ic ? Op Ar command
893 A synonym for help.
896 Command arguments which have embedded spaces may be quoted with
897 quote `"' marks.
898 .Sh ABORTING A FILE TRANSFER
899 To abort a file transfer, use the terminal interrupt key
900 (usually Ctrl-C).
901 Sending transfers will be immediately halted.
902 Receiving transfers will be halted by sending a ftp protocol
903 .Dv ABOR
904 command to the remote server, and discarding any further data received.
905 The speed at which this is accomplished depends upon the remote
906 server's support for
907 .Dv ABOR
908 processing.
909 If the remote server does not support the
910 .Dv ABOR
911 command, an
912 .Ql ftp>
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
917 .Nm ftp
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
924 .Nm ftp
925 program must be killed by hand.
926 .Sh FILE NAMING CONVENTIONS
927 Files specified as arguments to
928 .Nm ftp
929 commands are processed according to the following rules.
930 .Bl -enum
932 If the file name
933 .Sq Fl
934 is specified, the
935 .Ar stdin
936 (for reading) or
937 .Ar stdout
938 (for writing) is used.
940 If the first character of the file name is
941 .Sq \&| ,
943 remainder of the argument is interpreted as a shell command.
944 .Nm Ftp
945 then forks a shell, using
946 .Xr popen 3
947 with the argument supplied, and reads (writes) from the stdout
948 (stdin).
949 If the shell command includes spaces, the argument
950 must be quoted; e.g.
951 \*(Lq" ls -lt"\*(Rq.
952 A particularly
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
958 .Xr csh  1  ;
959 c.f. the
960 .Ic glob
961 command.
962 If the
963 .Nm ftp
964 command expects a single local file (.e.g.
965 .Ic put  ) ,
966 only the first filename generated by the "globbing" operation is used.
969 .Ic mget
970 commands and
971 .Ic get
972 commands with unspecified local file names, the local filename is
973 the remote filename, which may be altered by a
974 .Ic case  ,
975 .Ic ntrans ,
977 .Ic nmap
978 setting.
979 The resulting filename may then be altered if
980 .Ic runique
981 is on.
984 .Ic mput
985 commands and
986 .Ic put
987 commands with unspecified remote file names, the remote filename is
988 the local filename, which may be altered by a
989 .Ic ntrans
991 .Ic nmap
992 setting.
993 The resulting filename may then be altered by the remote server if
994 .Ic sunique
995 is on.
997 .Sh FILE TRANSFER PARAMETERS
998 The FTP specification specifies many parameters which may
999 affect a file transfer.
1001 .Ic type
1002 may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary),
1003 \*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for
1004 .Tn PDP Ns -10's
1006 .Tn PDP Ns -20's
1007 mostly).
1008 .Nm Ftp
1009 supports the ascii and image types of file transfer,
1010 plus local byte size 8 for
1011 .Ic tenex
1012 mode transfers.
1014 .Nm Ftp
1015 supports only the default values for the remaining
1016 file transfer parameters:
1017 .Ic mode  ,
1018 .Ic form ,
1020 .Ic struct  .
1021 .Sh ENVIRONMENT
1022 .Nm Ftp
1023 utilizes the following environment variables.
1024 .Bl -tag -width Fl
1025 .It Ev HOME
1026 For default location of a
1027 .Pa .netrc
1028 file, if one exists.
1029 .It Ev SHELL
1030 For default shell.
1032 .Sh SEE ALSO
1033 .Xr ftpd 8 ,
1034 RFC 959
1035 .Sh HISTORY
1037 .Nm ftp
1038 command appeared in
1039 .Bx 4.2 .
1040 .Sh BUGS
1041 Correct execution of many commands depends upon proper behavior
1042 by the remote server.
1044 An error in the treatment of carriage returns
1045 in the
1046 .Bx 4.2
1047 ascii-mode transfer code
1048 has been corrected.
1049 This correction may result in incorrect transfers of binary files
1050 to and from
1051 .Bx 4.2
1052 servers using the ascii type.
1053 Avoid this problem by using the binary image type.