Debian Codegraph @

upstream/debian-unstable/man1/inetutils-ftp.1

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