Debian Codegraph @

upstream/fedora-44/man1/ftp.1

raw
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 .\" $Id: ftp.1,v 1.1.1.1 2000/11/03 19:18:15 mk Exp $
34 .\"
35 .Dd August 15, 1999
36 .Dt FTP 1
37 .Os "Linux NetKit (0.17)"
38 .Sh NAME
39 .Nm ftp
40 .Nd
41 .Tn Internet
42 file transfer program
43 .Sh SYNOPSIS
44 .Nm ftp
45 .Op Fl pinegvd
46 .Op Ar host
47 .Nm pftp
48 .Op Fl inegvd
49 .Op Ar host
50 .Sh DESCRIPTION
51 .Nm Ftp
52 is the user interface to the
53 .Tn Internet
54 standard File Transfer Protocol.
55 The program allows a user to transfer files to and from a
56 remote network site.
57 .Pp
58 Options may be specified at the command line, or to the
59 command interpreter.
60 .Bl -tag -width flag
61 .It Fl A
62 Use active mode for data transfers. This is useful for transmissions
63 to servers which do not support passive connections (for whatever reason.)
64 .It Fl p
65 Use passive mode for data transfers. Allows use of ftp in environments
66 where a firewall prevents connections from the outside world back to
67 the client machine. Requires that the ftp server support the PASV
68 command. This is the default now for
69 .Nm all
70 clients (ftp and pftp) due to security concerns using the PORT transfer mode.
71 The flag is kept for compatibility only and has no effect anymore.
72 .It Fl i
73 Turns off interactive prompting during multiple file transfers.
74 .It Fl n
75 Restrains
76 .Nm ftp
77 from attempting \*(Lqauto-login\*(Rq upon initial connection.
78 If auto-login is enabled,
79 .Nm ftp
80 will check the
81 .Pa .netrc
82 (see
83 .Xr netrc 5)
84 file in the user's home directory for an entry describing
85 an account on the remote machine.
86 If no entry exists,
87 .Nm ftp
88 will prompt for the remote machine login name (default is the user
89 identity on the local machine), and, if necessary, prompt for a password
90 and an account with which to login.
91 .It Fl e
92 Disables command editing and history support, if it was compiled into
93 the
94 .Nm ftp
95 executable. Otherwise, does nothing.
96 .It Fl g
97 Disables file name globbing.
98 .It Fl m
99 The default requires that ftp explicitly binds to the same interface for the data
100 channel as the control channel in passive mode. Useful on multi-homed
101 clients. This option disables this behavior.
102 .It Fl v
103 Verbose option forces
104 .Nm ftp
105 to show all responses from the remote server, as well
106 as report on data transfer statistics.
107 .It Fl d
108 Enables debugging.
109 .El
110 .Pp
111 The client host with which
112 .Nm ftp
113 is to communicate may be specified on the command line.
114 If this is done,
115 .Nm ftp
116 will immediately attempt to establish a connection to an
117 .Tn FTP
118 server on that host; otherwise,
119 .Nm ftp
120 will enter its command interpreter and await instructions
121 from the user.
122 When
123 .Nm ftp
124 is awaiting commands from the user the prompt
125 .Ql ftp>
126 is provided to the user.
127 The following commands are recognized
128 by
129 .Nm ftp :
130 .Bl -tag -width Fl
131 .It Ic \&! Op Ar command Op Ar args
132 Invoke an interactive shell on the local machine.
133 If there are arguments, the first is taken to be a command to execute
134 directly, with the rest of the arguments as its arguments.
135 .It Ic \&$ Ar macro-name Op Ar args
136 Execute the macro
137 .Ar macro-name
138 that was defined with the
139 .Ic macdef
140 command.
141 Arguments are passed to the macro unglobbed.
142 .It Ic account Op Ar passwd
143 Supply a supplemental password required by a remote system for access
144 to resources once a login has been successfully completed.
145 If no argument is included, the user will be prompted for an account
146 password in a non-echoing input mode.
147 .It Ic append Ar local-file Op Ar remote-file
148 Append a local file to a file on the remote machine.
149 If
150 .Ar remote-file
151 is left unspecified, the local file name is used in naming the
152 remote file after being altered by any
153 .Ic ntrans
154 or
155 .Ic nmap
156 setting.
157 File transfer uses the current settings for
158 .Ic type ,
159 .Ic format ,
160 .Ic mode ,
161 and
162 .Ic structure .
163 .It Ic ascii
164 Set the file transfer
165 .Ic type
166 to network
167 .Tn ASCII .
168 This is the default type.
169 .It Ic bell
170 Arrange that a bell be sounded after each file transfer
171 command is completed.
172 .It Ic binary
173 Set the file transfer
174 .Ic type
175 to support binary image transfer.
176 .It Ic bye
177 Terminate the
178 .Tn FTP
179 session with the remote server
180 and exit
181 .Nm ftp .
182 An end of file will also terminate the session and exit.
183 .It Ic case
184 Toggle remote computer file name case mapping during
185 .Ic mget
186 commands.
187 When
188 .Ic case
189 is on (default is off), remote computer file names with all letters in
190 upper case are written in the local directory with the letters mapped
191 to lower case.
192 .It Ic \&cd Ar remote-directory
193 Change the working directory on the remote machine
194 to
195 .Ar remote-directory .
196 .It Ic cdup
197 Change the remote machine working directory to the parent of the
198 current remote machine working directory.
199 .It Ic chmod Ar mode file-name
200 Change the permission modes of the file
201 .Ar file-name
202 on the remote
203 system to
204 .Ar mode .
205 .It Ic close
206 Terminate the
207 .Tn FTP
208 session with the remote server, and
209 return to the command interpreter.
210 Any defined macros are erased.
211 .It Ic \&cr
212 Toggle carriage return stripping during
213 ascii type file retrieval.
214 Records are denoted by a carriage return/linefeed sequence
215 during ascii type file transfer.
216 When
217 .Ic \&cr
218 is on (the default), carriage returns are stripped from this
219 sequence to conform with the
220 .Ux
221 single linefeed record
222 delimiter.
223 Records on
224 .Pf non\- Ns Ux
225 remote systems may contain single linefeeds;
226 when an ascii type transfer is made, these linefeeds may be
227 distinguished from a record delimiter only when
228 .Ic \&cr
229 is off.
230 .It Ic delete Ar remote-file
231 Delete the file
232 .Ar remote-file
233 on the remote machine.
234 .It Ic debug Op Ar debug-value
235 Toggle debugging mode.
236 If an optional
237 .Ar debug-value
238 is specified it is used to set the debugging level.
239 When debugging is on,
240 .Nm ftp
241 prints each command sent to the remote machine, preceded
242 by the string
243 .Ql \-\->
244 .It Xo
245 .Ic dir
246 .Op Ar remote-directory
247 .Op Ar local-file
248 .Xc
249 Print a listing of the directory contents in the
250 directory,
251 .Ar remote-directory ,
252 and, optionally, placing the output in
253 .Ar local-file .
254 If interactive prompting is on,
255 .Nm ftp
256 will prompt the user to verify that the last argument is indeed the
257 target local file for receiving
258 .Ic dir
259 output.
260 If no directory is specified, the current working
261 directory on the remote machine is used.
262 If no local
263 file is specified, or
264 .Ar local-file
265 is
266 .Fl ,
267 output comes to the terminal.
268 .It Ic disconnect
269 A synonym for
270 .Ar close .
271 .It Ic form Ar format
272 Set the file transfer
273 .Ic form
274 to
275 .Ar format .
276 The default format is \*(Lqfile\*(Rq.
277 .It Ic get Ar remote-file Op Ar local-file
278 Retrieve the
279 .Ar remote-file
280 and store it on the local machine.
281 If the local
282 file name is not specified, it is given the same
283 name it has on the remote machine, subject to
284 alteration by the current
285 .Ic case ,
286 .Ic ntrans ,
287 and
288 .Ic nmap
289 settings.
290 The current settings for
291 .Ic type ,
292 .Ic form ,
293 .Ic mode ,
294 and
295 .Ic structure
296 are used while transferring the file.
297 .It Ic glob
298 Toggle filename expansion for
299 .Ic mdelete ,
300 .Ic mget
301 and
302 .Ic mput .
303 If globbing is turned off with
304 .Ic glob ,
305 the file name arguments
306 are taken literally and not expanded.
307 Globbing for
308 .Ic mput
309 is done as in
310 .Xr csh 1 .
311 For
312 .Ic mdelete
313 and
314 .Ic mget ,
315 each remote file name is expanded
316 separately on the remote machine and the lists are not merged.
317 Expansion of a directory name is likely to be
318 different from expansion of the name of an ordinary file:
319 the exact result depends on the foreign operating system and ftp server,
320 and can be previewed by doing
321 .Ql mls remote-files \-
322 Note:
323 .Ic mget
324 and
325 .Ic mput
326 are not meant to transfer
327 entire directory subtrees of files.
328 That can be done by
329 transferring a
330 .Xr tar 1
331 archive of the subtree (in binary mode).
332 .It Ic hash
333 Toggle hash-sign (``#'') printing for each data block
334 transferred.
335 The size of a data block is 1024 bytes.
336 .It Ic help Op Ar command
337 Print an informative message about the meaning of
338 .Ar command .
339 If no argument is given,
340 .Nm ftp
341 prints a list of the known commands.
342 .It Ic idle Op Ar seconds
343 Set the inactivity timer on the remote server to
344 .Ar seconds
345 seconds.
346 If
347 .Ar seconds
348 is omitted, the current inactivity timer is printed.
349 .It Ic lcd Op Ar directory
350 Change the working directory on the local machine.
351 If
352 no
353 .Ar directory
354 is specified, the user's home directory is used.
355 .It Xo
356 .Ic \&ls
357 .Op Ar remote-directory
358 .Op Ar local-file
359 .Xc
360 Print a listing of the contents of a
361 directory on the remote machine.
362 The listing includes any system-dependent information that the server
363 chooses to include; for example, most
364 .Ux
365 systems will produce
366 output from the command
367 .Ql ls \-l .
368 (See also
369 .Ic nlist . )
370 If
371 .Ar remote-directory
372 is left unspecified, the current working directory is used.
373 If interactive prompting is on,
374 .Nm ftp
375 will prompt the user to verify that the last argument is indeed the
376 target local file for receiving
377 .Ic \&ls
378 output.
379 If no local file is specified, or if
380 .Ar local-file
381 is
382 .Sq Fl ,
383 the output is sent to the terminal.
384 .It Ic macdef Ar macro-name
385 Define a macro.
386 Subsequent lines are stored as the macro
387 .Ar macro-name ;
388 a null line (consecutive newline characters
389 in a file or
390 carriage returns from the terminal) terminates macro input mode.
391 There is a limit of 16 macros and 4096 total characters in all
392 defined macros.
393 Macros remain defined until a
394 .Ic close
395 command is executed.
396 The macro processor interprets `$' and `\e' as special characters.
397 A `$' followed by a number (or numbers) is replaced by the
398 corresponding argument on the macro invocation command line.
399 A `$' followed by an `i' signals that macro processor that the
400 executing macro is to be looped.
401 On the first pass `$i' is
402 replaced by the first argument on the macro invocation command line,
403 on the second pass it is replaced by the second argument, and so on.
404 A `\e' followed by any character is replaced by that character.
405 Use the `\e' to prevent special treatment of the `$'.
406 .It Ic mdelete Op Ar remote-files
407 Delete the
408 .Ar remote-files
409 on the remote machine.
410 .It Ic mdir Ar remote-files local-file
411 Like
412 .Ic dir ,
413 except multiple remote files may be specified.
414 If interactive prompting is on,
415 .Nm ftp
416 will prompt the user to verify that the last argument is indeed the
417 target local file for receiving
418 .Ic mdir
419 output.
420 .It Ic mget Ar remote-files
421 Expand the
422 .Ar remote-files
423 on the remote machine
424 and do a
425 .Ic get
426 for each file name thus produced.
427 See
428 .Ic glob
429 for details on the filename expansion.
430 Resulting file names will then be processed according to
431 .Ic case ,
432 .Ic ntrans ,
433 and
434 .Ic nmap
435 settings.
436 Files are transferred into the local working directory,
437 which can be changed with
438 .Ql lcd directory ;
439 new local directories can be created with
440 .Ql "\&! mkdir directory" .
441 .It Ic mkdir Ar directory-name
442 Make a directory on the remote machine.
443 .It Ic mls Ar remote-files local-file
444 Like
445 .Ic nlist ,
446 except multiple remote files may be specified,
447 and the
448 .Ar local-file
449 must be specified.
450 If interactive prompting is on,
451 .Nm ftp
452 will prompt the user to verify that the last argument is indeed the
453 target local file for receiving
454 .Ic mls
455 output.
456 .It Ic mode Op Ar mode-name
457 Set the file transfer
458 .Ic mode
459 to
460 .Ar mode-name .
461 The default mode is \*(Lqstream\*(Rq mode.
462 .It Ic modtime Ar file-name
463 Show the last modification time of the file on the remote machine.
464 .It Ic mput Ar local-files
465 Expand wild cards in the list of local files given as arguments
466 and do a
467 .Ic put
468 for each file in the resulting list.
469 See
470 .Ic glob
471 for details of filename expansion.
472 Resulting file names will then be processed according to
473 .Ic ntrans
474 and
475 .Ic nmap
476 settings.
477 .It Ic newer Ar file-name Op Ar local-file
478 Get the file only if the modification time of the remote file is more
479 recent that the file on the current system.
480 If the file does not
481 exist on the current system, the remote file is considered
482 .Ic newer .
483 Otherwise, this command is identical to
484 .Ar get .
485 .It Xo
486 .Ic nlist
487 .Op Ar remote-directory
488 .Op Ar local-file
489 .Xc
490 Print a list of the files in a
491 directory on the remote machine.
492 If
493 .Ar remote-directory
494 is left unspecified, the current working directory is used.
495 If interactive prompting is on,
496 .Nm ftp
497 will prompt the user to verify that the last argument is indeed the
498 target local file for receiving
499 .Ic nlist
500 output.
501 If no local file is specified, or if
502 .Ar local-file
503 is
504 .Fl ,
505 the output is sent to the terminal.
506 .It Ic nmap Op Ar inpattern outpattern
507 Set or unset the filename mapping mechanism.
508 If no arguments are specified, the filename mapping mechanism is unset.
509 If arguments are specified, remote filenames are mapped during
510 .Ic mput
511 commands and
512 .Ic put
513 commands issued without a specified remote target filename.
514 If arguments are specified, local filenames are mapped during
515 .Ic mget
516 commands and
517 .Ic get
518 commands issued without a specified local target filename.
519 This command is useful when connecting to a
520 .No non\- Ns Ux
521 remote computer
522 with different file naming conventions or practices.
523 The mapping follows the pattern set by
524 .Ar inpattern
525 and
526 .Ar outpattern .
527 .Op Ar Inpattern
528 is a template for incoming filenames (which may have already been
529 processed according to the
530 .Ic ntrans
531 and
532 .Ic case
533 settings).
534 Variable templating is accomplished by including the
535 sequences `$1', `$2', ..., `$9' in
536 .Ar inpattern .
537 Use `\\' to prevent this special treatment of the `$' character.
538 All other characters are treated literally, and are used to determine the
539 .Ic nmap
540 .Op Ar inpattern
541 variable values.
542 For example, given
543 .Ar inpattern
544 $1.$2 and the remote file name "mydata.data", $1 would have the value
545 "mydata", and $2 would have the value "data".
546 The
547 .Ar outpattern
548 determines the resulting mapped filename.
549 The sequences `$1', `$2', ...., `$9' are replaced by any value resulting
550 from the
551 .Ar inpattern
552 template.
553 The sequence `$0' is replace by the original filename.
554 Additionally, the sequence
555 .Ql Op Ar seq1 , Ar seq2
556 is replaced by
557 .Op Ar seq1
558 if
559 .Ar seq1
560 is not a null string; otherwise it is replaced by
561 .Ar seq2 .
562 For example, the command
563 .Pp
564 .Bd -literal -offset indent -compact
565 nmap $1.$2.$3 [$1,$2].[$2,file]
566 .Ed
567 .Pp
568 would yield
569 the output filename "myfile.data" for input filenames "myfile.data" and
570 "myfile.data.old", "myfile.file" for the input filename "myfile", and
571 "myfile.myfile" for the input filename ".myfile".
572 Spaces may be included in
573 .Ar outpattern ,
574 as in the example: `nmap $1 sed "s/ *$//" > $1' .
575 Use the `\e' character to prevent special treatment
576 of the `$','[','[', and `,' characters.
577 .It Ic ntrans Op Ar inchars Op Ar outchars
578 Set or unset the filename character translation mechanism.
579 If no arguments are specified, the filename character
580 translation mechanism is unset.
581 If arguments are specified, characters in
582 remote filenames are translated during
583 .Ic mput
584 commands and
585 .Ic put
586 commands issued without a specified remote target filename.
587 If arguments are specified, characters in
588 local filenames are translated during
589 .Ic mget
590 commands and
591 .Ic get
592 commands issued without a specified local target filename.
593 This command is useful when connecting to a
594 .No non\- Ns Ux
595 remote computer
596 with different file naming conventions or practices.
597 Characters in a filename matching a character in
598 .Ar inchars
599 are replaced with the corresponding character in
600 .Ar outchars .
601 If the character's position in
602 .Ar inchars
603 is longer than the length of
604 .Ar outchars ,
605 the character is deleted from the file name.
606 .It Ic open Ar host Op Ar port
607 Establish a connection to the specified
608 .Ar host
609 .Tn FTP
610 server.
611 An optional port number may be supplied,
612 in which case,
613 .Nm ftp
614 will attempt to contact an
615 .Tn FTP
616 server at that port.
617 If the
618 .Ic auto-login
619 option is on (default),
620 .Nm ftp
621 will also attempt to automatically log the user in to
622 the
623 .Tn FTP
624 server (see below).
625 .It Ic prompt
626 Toggle interactive prompting.
627 Interactive prompting
628 occurs during multiple file transfers to allow the
629 user to selectively retrieve or store files.
630 If prompting is turned off (default is on), any
631 .Ic mget
632 or
633 .Ic mput
634 will transfer all files, and any
635 .Ic mdelete
636 will delete all files.
637 .It Ic proxy Ar ftp-command
638 Execute an ftp command on a secondary control connection.
639 This command allows simultaneous connection to two remote ftp
640 servers for transferring files between the two servers.
641 The first
642 .Ic proxy
643 command should be an
644 .Ic open ,
645 to establish the secondary control connection.
646 Enter the command "proxy ?" to see other ftp commands executable on the
647 secondary connection.
648 The following commands behave differently when prefaced by
649 .Ic proxy :
650 .Ic open
651 will not define new macros during the auto-login process,
652 .Ic close
653 will not erase existing macro definitions,
654 .Ic get
655 and
656 .Ic mget
657 transfer files from the host on the primary control connection
658 to the host on the secondary control connection, and
659 .Ic put ,
660 .Ic mput ,
661 and
662 .Ic append
663 transfer files from the host on the secondary control connection
664 to the host on the primary control connection.
665 Third party file transfers depend upon support of the ftp protocol
666 .Dv PASV
667 command by the server on the secondary control connection.
668 .It Ic put Ar local-file Op Ar remote-file
669 Store a local file on the remote machine.
670 If
671 .Ar remote-file
672 is left unspecified, the local file name is used
673 after processing according to any
674 .Ic ntrans
675 or
676 .Ic nmap
677 settings
678 in naming the remote file.
679 File transfer uses the
680 current settings for
681 .Ic type ,
682 .Ic format ,
683 .Ic mode ,
684 and
685 .Ic structure .
686 .It Ic pwd
687 Print the name of the current working directory on the remote
688 machine.
689 .It Ic quit
690 A synonym for
691 .Ic bye .
692 .It Ic quote Ar arg1 arg2 ...
693 The arguments specified are sent, verbatim, to the remote
694 .Tn FTP
695 server.
696 .It Ic recv Ar remote-file Op Ar local-file
697 A synonym for get.
698 .It Ic reget Ar remote-file Op Ar local-file
699 Reget acts like get, except that if
700 .Ar local-file
701 exists and is
702 smaller than
703 .Ar remote-file ,
704 .Ar local-file
705 is presumed to be
706 a partially transferred copy of
707 .Ar remote-file
708 and the transfer
709 is continued from the apparent point of failure.
710 This command
711 is useful when transferring very large files over networks that
712 are prone to dropping connections.
713 .It Ic remotehelp Op Ar command-name
714 Request help from the remote
715 .Tn FTP
716 server.
717 If a
718 .Ar command-name
719 is specified it is supplied to the server as well.
720 .It Ic remotestatus Op Ar file-name
721 With no arguments, show status of remote machine.
722 If
723 .Ar file-name
724 is specified, show status of
725 .Ar file-name
726 on remote machine.
727 .It Xo
728 .Ic rename
729 .Op Ar from
730 .Op Ar to
731 .Xc
732 Rename the file
733 .Ar from
734 on the remote machine, to the file
735 .Ar to .
736 .It Ic reset
737 Clear reply queue.
738 This command re-synchronizes command/reply sequencing with the remote
739 ftp server.
740 Resynchronization may be necessary following a violation of the ftp protocol
741 by the remote server.
742 .It Ic restart Ar marker
743 Restart the immediately following
744 .Ic get
745 or
746 .Ic put
747 at the
748 indicated
749 .Ar marker .
750 On
751 .Ux
752 systems, marker is usually a byte
753 offset into the file.
754 .It Ic rmdir Ar directory-name
755 Delete a directory on the remote machine.
756 .It Ic runique
757 Toggle storing of files on the local system with unique filenames.
758 If a file already exists with a name equal to the target
759 local filename for a
760 .Ic get
761 or
762 .Ic mget
763 command, a ".1" is appended to the name.
764 If the resulting name matches another existing file,
765 a ".2" is appended to the original name.
766 If this process continues up to ".99", an error
767 message is printed, and the transfer does not take place.
768 The generated unique filename will be reported.
769 Note that
770 .Ic runique
771 will not affect local files generated from a shell command
772 (see below).
773 The default value is off.
774 .It Ic send Ar local-file Op Ar remote-file
775 A synonym for put.
776 .It Ic sendport
777 Toggle the use of
778 .Dv PORT
779 commands.
780 By default,
781 .Nm ftp
782 will attempt to use a
783 .Dv PORT
784 command when establishing
785 a connection for each data transfer.
786 The use of
787 .Dv PORT
788 commands can prevent delays
789 when performing multiple file transfers.
790 If the
791 .Dv PORT
792 command fails,
793 .Nm ftp
794 will use the default data port.
795 When the use of
796 .Dv PORT
797 commands is disabled, no attempt will be made to use
798 .Dv PORT
799 commands for each data transfer.
800 This is useful
801 for certain
802 .Tn FTP
803 implementations which do ignore
804 .Dv PORT
805 commands but, incorrectly, indicate they've been accepted.
806 .It Ic site Ar arg1 arg2 ...
807 The arguments specified are sent, verbatim, to the remote
808 .Tn FTP
809 server as a
810 .Dv SITE
811 command.
812 .It Ic size Ar file-name
813 Return size of
814 .Ar file-name
815 on remote machine.
816 .It Ic status
817 Show the current status of
818 .Nm ftp .
819 .It Ic struct Op Ar struct-name
820 Set the file transfer
821 .Ar structure
822 to
823 .Ar struct-name .
824 By default \*(Lqstream\*(Rq structure is used.
825 .It Ic sunique
826 Toggle storing of files on remote machine under unique file names.
827 Remote ftp server must support ftp protocol
828 .Dv STOU
829 command for
830 successful completion.
831 The remote server will report unique name.
832 Default value is off.
833 .It Ic system
834 Show the type of operating system running on the remote machine.
835 .It Ic tenex
836 Set the file transfer type to that needed to
837 talk to
838 .Tn TENEX
839 machines.
840 .It Ic trace
841 Toggle packet tracing.
842 .It Ic type Op Ar type-name
843 Set the file transfer
844 .Ic type
845 to
846 .Ar type-name .
847 If no type is specified, the current type
848 is printed.
849 The default type is network
850 .Tn ASCII .
851 .It Ic umask Op Ar newmask
852 Set the default umask on the remote server to
853 .Ar newmask .
854 If
855 .Ar newmask
856 is omitted, the current umask is printed.
857 .It Xo
858 .Ic user Ar user-name
859 .Op Ar password
860 .Op Ar account
861 .Xc
862 Identify yourself to the remote
863 .Tn FTP
864 server.
865 If the
866 .Ar password
867 is not specified and the server requires it,
868 .Nm ftp
869 will prompt the user for it (after disabling local echo).
870 If an
871 .Ar account
872 field is not specified, and the
873 .Tn FTP
874 server
875 requires it, the user will be prompted for it.
876 If an
877 .Ar account
878 field is specified, an account command will
879 be relayed to the remote server after the login sequence
880 is completed if the remote server did not require it
881 for logging in.
882 Unless
883 .Nm ftp
884 is invoked with \*(Lqauto-login\*(Rq disabled, this
885 process is done automatically on initial connection to
886 the
887 .Tn FTP
888 server.
889 .It Ic verbose
890 Toggle verbose mode.
891 In verbose mode, all responses from
892 the
893 .Tn FTP
894 server are displayed to the user.
895 In addition,
896 if verbose is on, when a file transfer completes, statistics
897 regarding the efficiency of the transfer are reported.
898 By default,
899 verbose is on.
900 .It Ic ? Op Ar command
901 A synonym for help.
902 .El
903 .Pp
904 Command arguments which have embedded spaces may be quoted with
905 quote `"' marks.
906 .Sh ABORTING A FILE TRANSFER
907 To abort a file transfer, use the terminal interrupt key
908 (usually Ctrl-C).
909 Sending transfers will be immediately halted.
910 Receiving transfers will be halted by sending a ftp protocol
911 .Dv ABOR
912 command to the remote server, and discarding any further data received.
913 The speed at which this is accomplished depends upon the remote
914 server's support for
915 .Dv ABOR
916 processing.
917 If the remote server does not support the
918 .Dv ABOR
919 command, an
920 .Ql ftp>
921 prompt will not appear until the remote server has completed
922 sending the requested file.
923 .Pp
924 The terminal interrupt key sequence will be ignored when
925 .Nm ftp
926 has completed any local processing and is awaiting a reply
927 from the remote server.
928 A long delay in this mode may result from the ABOR processing described
929 above, or from unexpected behavior by the remote server, including
930 violations of the ftp protocol.
931 If the delay results from unexpected remote server behavior, the local
932 .Nm ftp
933 program must be killed by hand.
934 .Sh FILE NAMING CONVENTIONS
935 Files specified as arguments to
936 .Nm ftp
937 commands are processed according to the following rules.
938 .Bl -enum
939 .It
940 If the file name
941 .Sq Fl
942 is specified, the
943 .Ar stdin
944 (for reading) or
945 .Ar stdout
946 (for writing) is used.
947 .It
948 If the first character of the file name is
949 .Sq \&| ,
950 the
951 remainder of the argument is interpreted as a shell command.
952 .Nm Ftp
953 then forks a shell, using
954 .Xr popen 3
955 with the argument supplied, and reads (writes) from the stdout
956 (stdin).
957 If the shell command includes spaces, the argument
958 must be quoted; e.g.
959 \*(Lq" ls -lt"\*(Rq.
960 A particularly
961 useful example of this mechanism is: \*(Lqdir more\*(Rq.
962 .It
963 Failing the above checks, if ``globbing'' is enabled,
964 local file names are expanded
965 according to the rules used in the
966 .Xr csh 1 ;
967 c.f. the
968 .Ic glob
969 command.
970 If the
971 .Nm ftp
972 command expects a single local file (.e.g.
973 .Ic put ) ,
974 only the first filename generated by the "globbing" operation is used.
975 .It
976 For
977 .Ic mget
978 commands and
979 .Ic get
980 commands with unspecified local file names, the local filename is
981 the remote filename, which may be altered by a
982 .Ic case ,
983 .Ic ntrans ,
984 or
985 .Ic nmap
986 setting.
987 The resulting filename may then be altered if
988 .Ic runique
989 is on.
990 .It
991 For
992 .Ic mput
993 commands and
994 .Ic put
995 commands with unspecified remote file names, the remote filename is
996 the local filename, which may be altered by a
997 .Ic ntrans
998 or
999 .Ic nmap
1000 setting.
1001 The resulting filename may then be altered by the remote server if
1002 .Ic sunique
1003 is on.
1004 .El
1005 .Sh FILE TRANSFER PARAMETERS
1006 The FTP specification specifies many parameters which may
1007 affect a file transfer.
1008 The
1009 .Ic type
1010 may be one of \*(Lqascii\*(Rq, \*(Lqimage\*(Rq (binary),
1011 \*(Lqebcdic\*(Rq, and \*(Lqlocal byte size\*(Rq (for
1012 .Tn PDP Ns -10's
1013 and
1014 .Tn PDP Ns -20's
1015 mostly).
1016 .Nm Ftp
1017 supports the ascii and image types of file transfer,
1018 plus local byte size 8 for
1019 .Ic tenex
1020 mode transfers.
1021 .Pp
1022 .Nm Ftp
1023 supports only the default values for the remaining
1024 file transfer parameters:
1025 .Ic mode ,
1026 .Ic form ,
1027 and
1028 .Ic struct .
1029 .Sh ENVIRONMENT
1030 .Nm Ftp
1031 utilizes the following environment variables.
1032 .Bl -tag -width Fl
1033 .It Ev HOME
1034 For default location of a
1035 .Pa .netrc
1036 file, if one exists.
1037 .It Ev SHELL
1038 For default shell.
1039 .El
1040 .Sh SEE ALSO
1041 .Xr ftpd 8 ,
1042 RFC 959
1043 .Sh HISTORY
1044 The
1045 .Nm ftp
1046 command appeared in
1047 .Bx 4.2 .
1048 .Sh BUGS
1049 Correct execution of many commands depends upon proper behavior
1050 by the remote server.
1051 .Pp
1052 An error in the treatment of carriage returns
1053 in the
1054 .Bx 4.2
1055 ascii-mode transfer code
1056 has been corrected.
1057 This correction may result in incorrect transfers of binary files
1058 to and from
1059 .Bx 4.2
1060 servers using the ascii type.
1061 Avoid this problem by using the binary image type.