| blob | 91da03286c73363d075ea4665de92a27a25fcd55 |
1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH FTP 1 "Jun 6, 2006"
8 .SH NAME
9 ftp \- file transfer program
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBftp\fR [\fB-adfginpstvx\fR] [\fB-m\fR \fIGSS Mech\fR] [\fB-T\fR \fItimeout\fR]
14 [\fIhostname\fR [\fIport\fR]]
15 .fi
17 .SH DESCRIPTION
18 .LP
19 The \fBftp\fR command is the user interface to the \fBInternet\fR standard File
20 Transfer Protocol (\fBFTP\fR). \fBftp\fR transfers files to and from a remote
21 network site.
22 .sp
23 .LP
24 The host and optional port with which \fBftp\fR is to communicate can be
25 specified on the command line. If this is done, \fBftp\fR immediately attempts
26 to establish a connection to an \fBFTP\fR server on that host. Otherwise,
27 \fBftp\fR enters its command interpreter and awaits instructions from the user.
28 When \fBftp\fR is awaiting commands from the user, it displays the prompt
29 \fBftp>\fR.
30 .SH OPTIONS
31 .LP
32 The following options can be specified at the command line, or to the command
33 interpreter:
34 .sp
35 .ne 2
36 .na
37 \fB\fB-a\fR\fR
38 .ad
39 .RS 14n
40 Uses \fBGSSAPI\fR authentication \fBonly\fR. If the authentication fails, this
41 option closes the connection.
42 .RE
44 .sp
45 .ne 2
46 .na
47 \fB\fB-d\fR\fR
48 .ad
49 .RS 14n
50 Enables debugging.
51 .RE
53 .sp
54 .ne 2
55 .na
56 \fB\fB-f\fR\fR
57 .ad
58 .RS 14n
59 Forwards local security credentials to the remote server.
60 .RE
62 .sp
63 .ne 2
64 .na
65 \fB\fB-g\fR\fR
66 .ad
67 .RS 14n
68 Disables filename "globbing".
69 .RE
71 .sp
72 .ne 2
73 .na
74 \fB\fB-i\fR\fR
75 .ad
76 .RS 14n
77 Turns off interactive prompting during multiple file transfers.
78 .RE
80 .sp
81 .ne 2
82 .na
83 \fB\fB-m\fR\fR
84 .ad
85 .RS 14n
86 Specifies the \fBGSS\fR-\fBAPI\fR mechanism to use. The default is to use the
87 kerberos_v5 mechanism. Supported alternatives are defined in
88 \fB/etc/gss/mech\fR (see \fBmech\fR(4)).
89 .RE
91 .sp
92 .ne 2
93 .na
94 \fB\fB-n\fR\fR
95 .ad
96 .RS 14n
97 Does not attempt "auto-login" upon initial connection. If auto-login is not
98 disabled, \fBftp\fR checks the \fB\&.netrc\fR file in the user's home directory
99 for an entry describing an account on the remote machine. If no entry exists,
100 \fBftp\fR prompts for the login name of the account on the remote machine (the
101 default is the login name on the local machine), and, if necessary, prompts for
102 a password and an account with which to login.
103 .RE
105 .sp
106 .ne 2
107 .na
108 \fB\fB-p\fR\fR
109 .ad
110 .RS 14n
111 Enables passive mode for data transfers. This command is useful when connecting
112 to a remote host from behind a connection filtering firewall.
113 .RE
115 .sp
116 .ne 2
117 .na
118 \fB\fB-s\fR\fR
119 .ad
120 .RS 14n
121 Skips the \fBSYST\fR command that is sent by default to all remote servers upon
122 connection. The system command is what enables the automatic use of binary mode
123 rather than the protocol default ascii mode.
124 .sp
125 As some older servers cannot handle the \fBftp\fR command, this directive is
126 provided to allow inter-operability with these servers.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fB\fB-t\fR\fR
133 .ad
134 .RS 14n
135 Enables packet tracing (unimplemented).
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fB-T\fR \fItimeout\fR\fR
142 .ad
143 .RS 14n
144 Enables global connection timer, specified in seconds (decimal). There is a
145 timer for the control connection that is reset when anything is sent to the
146 server and disabled while the client is prompting for user input. Another
147 independent timer is used to monitor incoming or outgoing data connections.
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fB\fB-v\fR\fR
154 .ad
155 .RS 14n
156 Shows all responses from the remote server, as well as report on data transfer
157 statistics. This is turned on by default if \fBftp\fR is running interactively
158 with its input coming from the user's terminal.
159 .RE
161 .sp
162 .ne 2
163 .na
164 \fB\fB-x\fR\fR
165 .ad
166 .RS 14n
167 Attempts to use \fBGSSAPI\fR for authentication and encryption. Data and
168 Command channel protection is set to "\fBprivate\fR".
169 .RE
171 .sp
172 .LP
173 The following commands can be specified to the command interpreter:
174 .sp
175 .ne 2
176 .na
177 \fB\fB!\fR\fR
178 .ad
179 .sp .6
180 .RS 4n
181 [ \fIcommand\fR ] Runs \fIcommand\fR as a shell command on the local machine.
182 If no \fIcommand\fR is given, invokes an interactive shell.
183 .RE
185 .sp
186 .ne 2
187 .na
188 \fB\fB$\fR \fImacro-name\fR [ \fIargs\fR ]\fR
189 .ad
190 .sp .6
191 .RS 4n
192 Executes the macro \fImacro-name\fR that was defined with the \fBmacdef\fR
193 command. Arguments are passed to the macro unglobbed.
194 .RE
196 .sp
197 .ne 2
198 .na
199 \fB\fBaccount\fR [ \fIpasswd\fR ]\fR
200 .ad
201 .sp .6
202 .RS 4n
203 Supplies a supplemental password required by a remote system for access to
204 resources once a login has been successfully completed. If no argument is
205 included, the user is prompted for an account password in a non-echoing input
206 mode.
207 .RE
209 .sp
210 .ne 2
211 .na
212 \fB\fBappend\fR \fIlocal-file\fR [ \fIremote-file\fR ]\fR
213 .ad
214 .sp .6
215 .RS 4n
216 Appends a local file to a file on the remote machine. If \fIremote-file\fR is
217 not specified, the local file name is used, subject to alteration by any
218 \fBntrans\fR or \fBnmap\fR settings. File transfer uses the current settings
219 for "representation type", "file structure", and "transfer mode".
220 .RE
222 .sp
223 .ne 2
224 .na
225 \fB\fBascii\fR\fR
226 .ad
227 .sp .6
228 .RS 4n
229 Sets the "representation type" to "network \fBASCII\fR". This is the default
230 type.
231 .RE
233 .sp
234 .ne 2
235 .na
236 \fB\fBbell\fR\fR
237 .ad
238 .sp .6
239 .RS 4n
240 Sounds a bell after each file transfer command is completed.
241 .RE
243 .sp
244 .ne 2
245 .na
246 \fB\fBbinary\fR\fR
247 .ad
248 .sp .6
249 .RS 4n
250 Sets the "representation type" to "image".
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBbye\fR\fR
257 .ad
258 .sp .6
259 .RS 4n
260 Terminates the \fBFTP\fR session with the remote server and exit \fBftp\fR. An
261 \fBEOF\fR also terminates the session and exit.
262 .RE
264 .sp
265 .ne 2
266 .na
267 \fB\fBcase\fR\fR
268 .ad
269 .sp .6
270 .RS 4n
271 Toggles remote computer file name case mapping during \fBmget\fR commands. When
272 \fBcase\fR is on (default is off), remote computer file names with all letters
273 in upper case are written in the local directory with the letters mapped to
274 lower case.
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fBcd\fR \fIremote-directory\fR\fR
281 .ad
282 .sp .6
283 .RS 4n
284 Changes the working directory on the remote machine to \fIremote-directory\fR.
285 .RE
287 .sp
288 .ne 2
289 .na
290 \fB\fBcdup\fR\fR
291 .ad
292 .sp .6
293 .RS 4n
294 Changes the remote machine working directory to the parent of the current
295 remote machine working directory.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fBclear\fR\fR
302 .ad
303 .sp .6
304 .RS 4n
305 Sets the protection level on data transfers to "\fBclear\fR". If no \fBADAT\fR
306 command succeeded, then this is the default protection level.
307 .RE
309 .sp
310 .ne 2
311 .na
312 \fB\fBclose\fR\fR
313 .ad
314 .sp .6
315 .RS 4n
316 Terminates the \fBFTP\fR session with the remote server, and return to the
317 command interpreter. Any defined macros are erased.
318 .RE
320 .sp
321 .ne 2
322 .na
323 \fB\fBcr\fR\fR
324 .ad
325 .sp .6
326 .RS 4n
327 Toggles RETURN stripping during "network \fBASCII\fR" type file retrieval.
328 Records are denoted by a RETURN/\fBLINEFEED\fR sequence during "network
329 \fBASCII\fR" type file transfer. When \fBcr\fR is on (the default), RETURN
330 characters are stripped from this sequence to conform with the UNIX system
331 single \fBLINEFEED\fR record delimiter. Records on non-UNIX-system remote hosts
332 can contain single \fBLINEFEED\fR characters; when an "network \fBASCII\fR"
333 type transfer is made, these \fBLINEFEED\fR characters can be distinguished
334 from a record delimiter only when \fBcr\fR is off.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fB\fBdelete\fR \fIremote-file\fR\fR
341 .ad
342 .sp .6
343 .RS 4n
344 Deletes the file \fIremote-file\fR on the remote machine.
345 .RE
347 .sp
348 .ne 2
349 .na
350 \fB\fBdebug\fR\fR
351 .ad
352 .sp .6
353 .RS 4n
354 Toggles debugging mode. When debugging is on, \fBftp\fR prints each command
355 sent to the remote machine, preceded by the string \fB->\fR\&.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fBdir\fR [ \fIremote-directory\fR [ \fIlocal-file\fR ]]\fR
362 .ad
363 .sp .6
364 .RS 4n
365 Prints a listing of the directory contents in the directory,
366 \fIremote-directory\fR, and, optionally, placing the output in
367 \fIlocal-file\fR. If no directory is specified, the current working directory
368 on the remote machine is used. If no local file is specified, or
369 \fIlocal-file\fR is \fB\(mi\fR, output is sent to the terminal.
370 .RE
372 .sp
373 .ne 2
374 .na
375 \fB\fBdisconnect\fR\fR
376 .ad
377 .sp .6
378 .RS 4n
379 A synonym for \fBclose\fR.
380 .RE
382 .sp
383 .ne 2
384 .na
385 \fB\fBform\fR [ \fIformat-name\fR ]\fR
386 .ad
387 .sp .6
388 .RS 4n
389 Sets the carriage control format subtype of the "representation type" to
390 \fIformat-name\fR. The only valid \fIformat-name\fR is \fBnon-print\fR, which
391 corresponds to the default "non-print" subtype.
392 .RE
394 .sp
395 .ne 2
396 .na
397 \fB\fBget\fR \fIremote-file\fR [ \fIlocal-file\fR ]\fR
398 .ad
399 .sp .6
400 .RS 4n
401 Retrieves the \fIremote-file\fR and store it on the local machine. If the local
402 file name is not specified, it is given the same name it has on the remote
403 machine, subject to alteration by the current \fBcase\fR, \fBntrans\fR, and
404 \fBnmap\fR settings. The current settings for "representation type", "file
405 structure", and "transfer mode" are used while transferring the file.
406 .RE
408 .sp
409 .ne 2
410 .na
411 \fB\fBglob\fR\fR
412 .ad
413 .sp .6
414 .RS 4n
415 Toggles filename expansion, or "globbing", for \fBmdelete\fR, \fBmget\fR and
416 \fBmput\fR. If globbing is turned off, filenames are taken literally.
417 .sp
418 Globbing for \fBmput\fR is done as in \fBsh\fR(1). For \fBmdelete\fR and
419 \fBmget\fR, each remote file name is expanded separately on the remote machine,
420 and the lists are not merged.
421 .sp
422 Expansion of a directory name is likely to be radically different from
423 expansion of the name of an ordinary file: the exact result depends on the
424 remote operating system and \fBFTP\fR server, and can be previewed with the
425 command, \fBmls\fR \fIremote-files\fR \(mi.
426 .sp
427 \fBmget\fR and \fBmput\fR are not meant to transfer entire directory subtrees
428 of files. You can do this by transferring a \fBtar\fR(1) archive of the subtree
429 (using a "representation type" of "image" as set by the \fBbinary\fR command).
430 .RE
432 .sp
433 .ne 2
434 .na
435 \fB\fBhash\fR\fR
436 .ad
437 .sp .6
438 .RS 4n
439 Toggles hash-sign (\fB#\fR) printing for each data block transferred. The size
440 of a data block is 8192 bytes.
441 .RE
443 .sp
444 .ne 2
445 .na
446 \fB\fBhelp\fR [ \fIcommand\fR ]\fR
447 .ad
448 .sp .6
449 .RS 4n
450 Prints an informative message about the meaning of \fIcommand\fR. If no
451 argument is given, \fBftp\fR prints a list of the known commands.
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB\fBlcd\fR [ \fIdirectory\fR ]\fR
458 .ad
459 .sp .6
460 .RS 4n
461 Changes the working directory on the local machine. If no \fIdirectory\fR is
462 specified, the user's home directory is used.
463 .RE
465 .sp
466 .ne 2
467 .na
468 \fB\fBls\fR [ \fB-al\fR | \fIremote-directory\fR [ \fIlocal-file\fR ]]\fR
469 .ad
470 .sp .6
471 .RS 4n
472 By default, prints an abbreviated listing of the contents of a directory on the
473 remote machine. This default behavior can be changed to make \fBls\fR a synonym
474 of the \fBdir\fR command. This change can be achieved by setting
475 \fBFTP_LS_SENDS_NLST\fR to '\fBno\fR' in \fB/etc/default/ftp\fR or in the
476 environment. See \fBftp\fR(4) for details.
477 .sp
478 The \fB-a\fR option lists all entries, including those that begin with a dot
479 (\fB\&.\fR), which are normally not listed. The \fB-l\fR option lists files in
480 long format, giving mode, number of links, owner, group, size in bytes, and
481 time of last modification for each file. If the file is a special file, the
482 size field instead contains the major and minor device numbers rather than a
483 size. If the file is a symbolic link, the filename is printed followed by
484 "\fB\(->\fR" and the pathname of the referenced file.
485 .sp
486 If \fIremote-directory\fR is left unspecified, the current working directory is
487 used.
488 .sp
489 If no local file is specified, or if \fIlocal-file\fR is \fB\(mi\fR, the output
490 is sent to the terminal.
491 .RE
493 .sp
494 .ne 2
495 .na
496 \fB\fBmacdef\fR \fImacro-name\fR\fR
497 .ad
498 .sp .6
499 .RS 4n
500 Defines a macro. Subsequent lines are stored as the macro \fImacro-name\fR. A
501 null line (consecutive \fBNEWLINE\fR characters in a file or RETURN characters
502 from the terminal) terminates macro input mode. There is a limit of 16 macros
503 and 4096 total characters in all defined macros. Macros remain defined until a
504 \fBclose\fR command is executed.
505 .sp
506 The macro processor interprets \fB$\fR and \fB\e\fR as special characters. A
507 \fB$\fR followed by a number (or numbers) is replaced by the corresponding
508 argument on the macro invocation command line. A \fB$\fR followed by an \fBi\fR
509 signals that macro processor that the executing macro is to be looped. On the
510 first pass, \fB$i\fR is replaced by the first argument on the macro invocation
511 command line; on the second pass, it is replaced by the second argument, and so
512 on. A \fB\e\fR followed by any character is replaced by that character. Use the
513 \fB\e\fR to prevent special treatment of the \fB$\fR.
514 .RE
516 .sp
517 .ne 2
518 .na
519 \fB\fBmdelete\fR \fIremote-files\fR\fR
520 .ad
521 .sp .6
522 .RS 4n
523 Deletes the \fIremote-files\fR on the remote machine.
524 .RE
526 .sp
527 .ne 2
528 .na
529 \fB\fBmdir\fR \fIremote-files local-file\fR\fR
530 .ad
531 .sp .6
532 .RS 4n
533 Like \fBdir\fR, except multiple remote files can be specified. If interactive
534 prompting is on, \fBftp\fR prompts the user to verify that the last argument is
535 indeed the target local file for receiving \fBmdir\fR output.
536 .RE
538 .sp
539 .ne 2
540 .na
541 \fB\fBmget\fR \fIremote-files\fR\fR
542 .ad
543 .sp .6
544 .RS 4n
545 Expands the \fIremote-files\fR on the remote machine and do a \fBget\fR for
546 each file name thus produced. See \fBglob\fR for details on the filename
547 expansion. Resulting file names are processed according to \fBcase\fR,
548 \fBntrans\fR, and \fBnmap\fR settings. Files are transferred into the local
549 working directory, which can be changed with \fBlcd\fR \fIdirectory\fR. New
550 local directories can be created with \fB! mkdir\fR \fIdirectory\fR.
551 .RE
553 .sp
554 .ne 2
555 .na
556 \fB\fBmkdir\fR \fIdirectory-name\fR\fR
557 .ad
558 .sp .6
559 .RS 4n
560 Makes a directory on the remote machine.
561 .RE
563 .sp
564 .ne 2
565 .na
566 \fB\fBmls\fR \fIremote-files local-file\fR\fR
567 .ad
568 .sp .6
569 .RS 4n
570 Like \fBls\fR(1), except multiple remote files can be specified. If interactive
571 prompting is on, \fBftp\fR prompts the user to verify that the last argument is
572 indeed the target local file for receiving \fBmls\fR output.
573 .RE
575 .sp
576 .ne 2
577 .na
578 \fB\fBmode\fR [ \fImode-name\fR ]\fR
579 .ad
580 .sp .6
581 .RS 4n
582 Sets the "transfer mode" to \fImode-name\fR. The only valid \fImode-name\fR is
583 \fBstream\fR, which corresponds to the default "stream" mode. This
584 implementation only supports \fBstream\fR, and requires that it be specified.
585 .RE
587 .sp
588 .ne 2
589 .na
590 \fB\fBmput\fR \fIlocal-files\fR\fR
591 .ad
592 .sp .6
593 .RS 4n
594 Expands wild cards in the list of local files given as arguments and do a
595 \fBput\fR for each file in the resulting list. See \fBglob\fR for details of
596 filename expansion. Resulting file names are processed according to
597 \fBntrans\fR and \fBnmap\fR settings.
598 .RE
600 .sp
601 .ne 2
602 .na
603 \fB\fBnlist\fR [ \fB-al\fR | \fIremote-directory\fR [ \fIlocal-file\fR ]]\fR
604 .ad
605 .sp .6
606 .RS 4n
607 Prints an abbreviated listing of the contents of a directory on the remote
608 machine, listing only those files that can be retrieved by the \fBget\fR
609 command, unless the \fB-a\fR or \fB-l\fR option is used. If
610 \fIremote-directory\fR is left unspecified, the current working directory is
611 used.
612 .sp
613 The \fB-a\fR option lists all entries, including those that begin with a dot
614 (\fB\&.\fR), which are normally not listed. The \fB-l\fR option lists files in
615 long format the same way it does when used with the \fBls\fR command.
616 .RE
618 .sp
619 .ne 2
620 .na
621 \fB\fBnmap\fR [ \fIinpattern outpattern\fR ]\fR
622 .ad
623 .sp .6
624 .RS 4n
625 Sets or unsets the filename mapping mechanism. If no arguments are specified,
626 the filename mapping mechanism is unset. If arguments are specified, remote
627 filenames are mapped during \fBmput\fR commands and \fBput\fR commands issued
628 without a specified remote target filename. If arguments are specified, local
629 filenames are mapped during \fBmget\fR commands and \fBget\fR commands issued
630 without a specified local target filename.
631 .sp
632 This command is useful when connecting to a non-UNIX-system remote host with
633 different file naming conventions or practices. The mapping follows the pattern
634 set by \fIinpattern\fR and \fIoutpattern\fR. \fIinpattern\fR is a template for
635 incoming filenames (which can have already been processed according to the
636 \fBntrans\fR and \fBcase\fR settings). Variable templating is accomplished by
637 including the sequences \fB$1\fR, \fB$2\fR, .\|.\|.\|, \fB$9\fR in
638 \fIinpattern\fR. Use \fB\e\fR to prevent this special treatment of the \fB$\fR
639 character. All other characters are treated literally, and are used to
640 determine the \fBnmap\fR \fIinpattern\fR variable values.
641 .sp
642 For example, given \fIinpattern\fR \fB$1.$2\fR and the remote file name
643 \fBmydata.data\fR, \fB$1\fR would have the value \fBmydata\fR, and \fB$2\fR
644 would have the value \fBdata\fR.
645 .sp
646 The \fIoutpattern\fR determines the resulting mapped filename. The sequences
647 \fB$1\fR, \fB$2\fR, .\|.\|.\|, \fB$9\fR are replaced by any value resulting
648 from the \fIinpattern\fR template. The sequence \fB$0\fR is replaced by the
649 original filename. Additionally, the sequence [\fI\|seq1\|\fR,\fI\|seq2\|\fR]
650 is replaced by \fIseq1\fR if \fIseq1\fR is not a null string; otherwise it is
651 replaced by \fIseq2\fR.
652 .sp
653 For example, the command \fBnmap $1.$2.$3 [$1,$2].[$2,file]\fR would yield the
654 output filename \fBmyfile.data\fR for input filenames \fBmyfile.data\fR and
655 \fBmyfile.data.old\fR, \fBmyfile.file\fR for the input filename \fBmyfile\fR,
656 and \fBmyfile.myfile\fR for the input filename \fB\&.myfile\fR. \fBSPACE\fR
657 characters can be included in \fIoutpattern\fR, as in the example \fBnmap $1 |
658 sed "s/ *$//" > $1\fR. Use the \fB\e\fR character to prevent special treatment
659 of the \fB$\fR, \fB[\fR, \fB]\fR, and \fB,\fR, characters.
660 .RE
662 .sp
663 .ne 2
664 .na
665 \fB\fBntrans\fR [ \fIinchars\fR [ \fIoutchars\fR ] ]\fR
666 .ad
667 .sp .6
668 .RS 4n
669 Sets or unsets the filename character translation mechanism. If no arguments
670 are specified, the filename character translation mechanism is unset. If
671 arguments are specified, characters in remote filenames are translated during
672 \fBmput\fR commands and \fBput\fR commands issued without a specified remote
673 target filename, and characters in local filenames are translated during
674 \fBmget\fR commands and \fBget\fR commands issued without a specified local
675 target filename.
676 .sp
677 This command is useful when connecting to a non-UNIX-system remote host with
678 different file naming conventions or practices. Characters in a filename
679 matching a character in \fIinchars\fR are replaced with the corresponding
680 character in \fIoutchars\fR. If the character's position in \fIinchars\fR is
681 longer than the length of \fIoutchars\fR, the character is deleted from the
682 file name.
683 .sp
684 Only 16 characters can be translated when using the \fBntrans\fR command under
685 \fBftp\fR. Use \fBcase\fR (described above) if needing to convert the entire
686 alphabet.
687 .RE
689 .sp
690 .ne 2
691 .na
692 \fB\fBopen\fR \fIhost\fR [ \fIport\fR ]\fR
693 .ad
694 .sp .6
695 .RS 4n
696 Establishes a connection to the specified \fIhost\fR \fBFTP\fR server. An
697 optional port number can be supplied, in which case, \fBftp\fR attempts to
698 contact an \fBFTP\fR server at that port. If the \fIauto-login\fR option is on
699 (default setting), \fBftp\fR also attempts to automatically log the user in to
700 the \fBFTP\fR server.
701 .RE
703 .sp
704 .ne 2
705 .na
706 \fB\fBpassive\fR\fR
707 .ad
708 .sp .6
709 .RS 4n
710 Toggles passive mode. When passive mode is turned on, the ftp client sends the
711 \fBPASV\fR command requesting that the \fBFTP\fR server open a port for the
712 data connection and return the address of that port. The remote server listens
713 on that port and the client connects to it. When passive mode is turned off,
714 the ftp client sends the \fBPORT\fR command to the server specifying an address
715 for the remote server to connect back to. Passive mode is useful when the
716 connections to the ftp client are controlled, for example, when behind a
717 firewall. When connecting to an IPv6-enabled \fBFTP\fR server, \fBEPSV\fR can
718 be used in place of \fBPASV\fR and \fBEPRT\fR in place of \fBPORT\fR.
719 .RE
721 .sp
722 .ne 2
723 .na
724 \fB\fBprivate\fR\fR
725 .ad
726 .sp .6
727 .RS 4n
728 Sets the protection level on data transfers to "\fBprivate\fR". Data
729 transmissions are confidentiality\(em and integrity\(emprotected by encryption.
730 If no \fBADAT\fR command succeeded, then the only possible level is "clear".
731 .RE
733 .sp
734 .ne 2
735 .na
736 \fB\fBprompt\fR\fR
737 .ad
738 .sp .6
739 .RS 4n
740 Toggles interactive prompting. Interactive prompting occurs during multiple
741 file transfers to allow the user to selectively retrieve or store files. By
742 default, prompting is turned on. If prompting is turned off, any \fBmget\fR or
743 \fBmput\fR transfers all files, and any \fBmdelete\fR deletes all files.
744 .RE
746 .sp
747 .ne 2
748 .na
749 \fB\fBprotect\fR \fIprotection-level\fR\fR
750 .ad
751 .sp .6
752 .RS 4n
753 Sets the protection level on data transfers to \fIprotection-level\fR. The
754 valid protection levels are "\fBclear\fR" for unprotected data transmissions,
755 "\fBsafe\fR" for data transmissions that are integrity-protected by
756 cryptographic checksum, and "\fBprivate\fR" for data transmissions that are
757 confidentiality\(em and integrity\(em protected by encryption. If no \fBADAT\fR
758 command succeeded, then the only possible level is "\fBclear\fR". If no level
759 is specified, the current level is printed. The default protection level is
760 "\fBclear\fR".
761 .RE
763 .sp
764 .ne 2
765 .na
766 \fB\fBproxy\fR \fIftp-command\fR\fR
767 .ad
768 .sp .6
769 .RS 4n
770 Executes an \fBFTP\fR command on a secondary control connection. This command
771 allows simultaneous connection to two remote \fBFTP\fR servers for transferring
772 files between the two servers. The first \fBproxy\fR command should be an
773 \fBopen\fR, to establish the secondary control connection. Enter the command
774 \fBproxy\fR \fB?\fR to see other \fBFTP\fR commands executable on the secondary
775 connection.
776 .sp
777 The following commands behave differently when prefaced by \fBproxy\fR:
778 \fBopen\fR does not define new macros during the auto-login process,
779 \fBclose\fR does not erase existing macro definitions, \fBget\fR and \fBmget\fR
780 transfer files from the host on the primary control connection to the host on
781 the secondary control connection, and \fBput\fR, \fBmputd\fR, and \fBappend\fR
782 transfer files from the host on the secondary control connection to the host on
783 the primary control connection.
784 .sp
785 Third party file transfers depend upon support of the \fBPASV\fR command by the
786 server on the secondary control connection.
787 .RE
789 .sp
790 .ne 2
791 .na
792 \fB\fBput\fR \fIlocal-file\fR [ \fIremote-file\fR ]\fR
793 .ad
794 .sp .6
795 .RS 4n
796 Stores a local file on the remote machine. If \fIremote-file\fR is left
797 unspecified, the local file name is used after processing according to any
798 \fBntrans\fR or \fBnmap\fR settings in naming the remote file. File transfer
799 uses the current settings for "representation type", "file structure", and
800 "transfer mode".
801 .RE
803 .sp
804 .ne 2
805 .na
806 \fB\fBpwd\fR\fR
807 .ad
808 .sp .6
809 .RS 4n
810 Prints the name of the current working directory on the remote machine.
811 .RE
813 .sp
814 .ne 2
815 .na
816 \fB\fBquit\fR\fR
817 .ad
818 .sp .6
819 .RS 4n
820 A synonym for \fBbye\fR.
821 .RE
823 .sp
824 .ne 2
825 .na
826 \fB\fBquote\fR \fIarg1 arg2\fR ...\fR
827 .ad
828 .sp .6
829 .RS 4n
830 Sends the arguments specified, verbatim, to the remote \fBFTP\fR server. A
831 single \fBFTP\fR reply code is expected in return. (The \fBremotehelp\fR
832 command displays a list of valid arguments.)
833 .sp
834 \fBquote\fR should be used only by experienced users who are familiar with the
835 FTP protocol.
836 .RE
838 .sp
839 .ne 2
840 .na
841 \fB\fBrecv\fR \fIremote-file\fR [ \fIlocal-file\fR ]\fR
842 .ad
843 .sp .6
844 .RS 4n
845 A synonym for \fBget\fR.
846 .RE
848 .sp
849 .ne 2
850 .na
851 \fB\fBreget\fR \fIremote-file\fR [ \fIlocal-file\fR ]\fR
852 .ad
853 .sp .6
854 .RS 4n
855 The \fBreget\fR command acts like \fBget\fR, except that if \fIlocal-file\fR
856 exists and is smaller than \fIremote-file\fR, \fIlocal-file\fR is presumed to
857 be a partially transferred copy of \fIremote-file\fR and the transfer is
858 continued from the apparent point of failure. This command is useful when
859 transferring large files over networks that are prone to dropping connections.
860 .RE
862 .sp
863 .ne 2
864 .na
865 \fB\fBremotehelp\fR [ \fIcommand-name\fR ]\fR
866 .ad
867 .sp .6
868 .RS 4n
869 Requests help from the remote \fBFTP\fR server. If a \fIcommand-name\fR is
870 specified it is supplied to the server as well.
871 .RE
873 .sp
874 .ne 2
875 .na
876 \fB\fBrename\fR \fIfrom to\fR\fR
877 .ad
878 .sp .6
879 .RS 4n
880 Renames the file \fIfrom\fR on the remote machine to have the name \fIto\fR.
881 .RE
883 .sp
884 .ne 2
885 .na
886 \fB\fBreset\fR\fR
887 .ad
888 .sp .6
889 .RS 4n
890 Clears reply queue. This command re-synchronizes command/reply sequencing with
891 the remote \fBFTP\fR server. Resynchronization can be necessary following a
892 violation of the \fBFTP\fR protocol by the remote server.
893 .RE
895 .sp
896 .ne 2
897 .na
898 \fB\fBrestart\fR [ \fImarker\fR ]\fR
899 .ad
900 .sp .6
901 .RS 4n
902 Restarts the immediately following \fBget\fR or \fBput\fR at the indicated
903 marker. On UNIX systems, \fImarker\fR is usually a byte offset into the file.
904 When followed by an \fBmget\fR, the \fBrestart\fR applies to the first
905 \fBget\fR performed. Specifying a \fImarker\fR of \fB0\fR clears the restart
906 marker. If no argument is specified, the current restart status is displayed.
907 .RE
909 .sp
910 .ne 2
911 .na
912 \fB\fBrmdir\fR \fIdirectory-name\fR\fR
913 .ad
914 .sp .6
915 .RS 4n
916 Deletes a directory on the remote machine.
917 .RE
919 .sp
920 .ne 2
921 .na
922 \fB\fBrunique\fR\fR
923 .ad
924 .sp .6
925 .RS 4n
926 Toggles storing of files on the local system with unique filenames. If a file
927 already exists with a name equal to the target local filename for a \fBget\fR
928 or \fBmget\fR command, a \fB\&.1\fR is appended to the name. If the resulting
929 name matches another existing file, a \fB\&.2\fR is appended to the original
930 name. If this process continues up to \fB\&.99\fR, an error message is printed,
931 and the transfer does not take place. The generated unique filename is
932 reported. \fBrunique\fR does not affect local files generated from a shell
933 command. The default value is off.
934 .RE
936 .sp
937 .ne 2
938 .na
939 \fB\fBsafe\fR\fR
940 .ad
941 .sp .6
942 .RS 4n
943 Sets the protection level on data transfers to "\fBsafe\fR". Data transmissions
944 are integrity-protected by cryptographic checksum. If no \fBADAT\fR command
945 succeeded, then the only possible level is "\fBclear\fR".
946 .RE
948 .sp
949 .ne 2
950 .na
951 \fB\fBsend\fR \fIlocal-file\fR [ \fIremote-file\fR ]\fR
952 .ad
953 .sp .6
954 .RS 4n
955 A synonym for \fBput\fR.
956 .RE
958 .sp
959 .ne 2
960 .na
961 \fB\fBsendport\fR\fR
962 .ad
963 .sp .6
964 .RS 4n
965 Toggles the use of \fBPORT\fR commands. By default, \fBftp\fR attempts to use a
966 \fBPORT\fR command when establishing a connection for each data transfer. The
967 use of \fBPORT\fR commands can prevent delays when performing multiple file
968 transfers. If the \fBPORT\fR command fails, \fBftp\fR uses the default data
969 port. When the use of \fBPORT\fR commands is disabled, no attempt is made to
970 use \fBPORT\fR commands for each data transfer. This is useful when connected
971 to certain \fBFTP\fR implementations that ignore \fBPORT\fR commands but
972 incorrectly indicate they have been accepted.
973 .RE
975 .sp
976 .ne 2
977 .na
978 \fB\fBsite\fR \fIarg1\fR [ \fIarg2\fR ] ...\fR
979 .ad
980 .sp .6
981 .RS 4n
982 Sends the arguments specified, verbatim, to the remote \fBFTP\fR server as a
983 \fBSITE\fR command.
984 .RE
986 .sp
987 .ne 2
988 .na
989 \fB\fBstatus\fR\fR
990 .ad
991 .sp .6
992 .RS 4n
993 Show the current status of \fBftp\fR.
994 .RE
996 .sp
997 .ne 2
998 .na
999 \fB\fBstruct\fR [ \fIstruct-name\fR ]\fR
1000 .ad
1001 .sp .6
1002 .RS 4n
1003 Sets the file structure to \fIstruct-name\fR. The only valid \fIstruct-name\fR
1004 is \fBfile\fR, which corresponds to the default "file" structure. The
1005 implementation only supports \fBfile\fR, and requires that it be specified.
1006 .RE
1008 .sp
1009 .ne 2
1010 .na
1011 \fB\fBsunique\fR\fR
1012 .ad
1013 .sp .6
1014 .RS 4n
1015 Toggles storing of files on remote machine under unique file names. The remote
1016 \fBFTP\fR server must support the \fBSTOU\fR command for successful completion.
1017 The remote server reports the unique name. Default value is off.
1018 .RE
1020 .sp
1021 .ne 2
1022 .na
1023 \fB\fBtcpwindow\fR [ \fIsize\fR ]\fR
1024 .ad
1025 .sp .6
1026 .RS 4n
1027 Sets the \fBTCP\fR window size to be used for data connections. Specifying a
1028 size of \fB0\fR stops the explicit setting of the \fBTCP\fR window size on data
1029 connections. If no argument is specified, the current setting is displayed.
1030 .RE
1032 .sp
1033 .ne 2
1034 .na
1035 \fB\fBtenex\fR\fR
1036 .ad
1037 .sp .6
1038 .RS 4n
1039 Sets the "representation type" to that needed to talk to \fBTENEX\fR machines.
1040 .RE
1042 .sp
1043 .ne 2
1044 .na
1045 \fB\fBtrace\fR\fR
1046 .ad
1047 .sp .6
1048 .RS 4n
1049 Toggles packet tracing (unimplemented).
1050 .RE
1052 .sp
1053 .ne 2
1054 .na
1055 \fB\fBtype\fR [ \fItype-name\fR ]\fR
1056 .ad
1057 .sp .6
1058 .RS 4n
1059 Sets the "representation type" to \fItype-name\fR. The valid \fItype-name\fRs
1060 are \fBascii\fR for "network \fBASCII\fR", \fBbinary\fR or \fBimage\fR for
1061 "image", and \fBtenex\fR for "local byte size" with a byte size of 8 (used to
1062 talk to \fBTENEX\fR machines). If no type is specified, the current type is
1063 printed. The default type is "network \fBASCII\fR".
1064 .RE
1066 .sp
1067 .ne 2
1068 .na
1069 \fB\fBuser\fR \fIuser-name\fR [ \fIpassword\fR [ \fIaccount\fR ]]\fR
1070 .ad
1071 .sp .6
1072 .RS 4n
1073 Identify yourself to the remote \fBFTP\fR server. If the password is not
1074 specified and the server requires it, \fBftp\fR prompts the user for it (after
1075 disabling local echo). If an account field is not specified, and the \fBFTP\fR
1076 server requires it, the user is prompted for it. If an account field is
1077 specified, an account command is relayed to the remote server after the login
1078 sequence is completed if the remote server did not require it for logging in.
1079 Unless \fBftp\fR is invoked with "auto-login" disabled, this process is done
1080 automatically on initial connection to the \fBFTP\fR server.
1081 .RE
1083 .sp
1084 .ne 2
1085 .na
1086 \fB\fBverbose\fR\fR
1087 .ad
1088 .sp .6
1089 .RS 4n
1090 Toggles verbose mode. In verbose mode, all responses from the \fBFTP\fR server
1091 are displayed to the user. In addition, if verbose mode is on, when a file
1092 transfer completes, statistics regarding the efficiency of the transfer are
1093 reported. By default, verbose mode is on if \fBftp\fR's commands are coming
1094 from a terminal, and off otherwise.
1095 .RE
1097 .sp
1098 .ne 2
1099 .na
1100 \fB\fB?\fR [ \fIcommand\fR ]\fR
1101 .ad
1102 .sp .6
1103 .RS 4n
1104 A synonym for \fBhelp\fR.
1105 .RE
1107 .sp
1108 .LP
1109 Command arguments which have embedded spaces can be quoted with quote (\fB"\fR)
1110 marks.
1111 .sp
1112 .LP
1113 If any command argument which is not indicated as being optional is not
1114 specified, \fBftp\fR prompts for that argument.
1115 .SH ABORTING A FILE TRANSFER
1116 .LP
1117 To abort a file transfer, use the terminal interrupt key. Sending transfers is
1118 immediately halted. Receiving transfers are halted by sending an \fBFTP\fR
1119 protocol \fBABOR\fR command to the remote server, and discarding any further
1120 data received. The speed at which this is accomplished depends upon the remote
1121 server's support for \fBABOR\fR processing. If the remote server does not
1122 support the \fBABOR\fR command, an \fBftp>\fR prompt does not appear until the
1123 remote server has completed sending the requested file.
1124 .sp
1125 .LP
1126 The terminal interrupt key sequence is ignored when \fBftp\fR has completed any
1127 local processing and is awaiting a reply from the remote server. A long delay
1128 in this mode can result from the \fBABOR\fR processing described above, or from
1129 unexpected behavior by the remote server, including violations of the ftp
1130 protocol. If the delay results from unexpected remote server behavior, the
1131 local \fBftp\fR program must be killed by hand.
1132 .SH FILE NAMING CONVENTIONS
1133 .LP
1134 Local files specified as arguments to \fBftp\fR commands are processed
1135 according to the following rules.
1136 .sp
1137 .ne 2
1138 .na
1139 \fB1)\fR
1140 .ad
1141 .RS 6n
1142 If the file name \fB\(mi\fR is specified, the standard input (for reading) or
1143 standard output (for writing) is used.
1144 .RE
1146 .sp
1147 .ne 2
1148 .na
1149 \fB2)\fR
1150 .ad
1151 .RS 6n
1152 If the first character of the file name is \fB|\fR, the remainder of the
1153 argument is interpreted as a shell command. \fBftp\fR then forks a shell, using
1154 \fBpopen\fR(3C) with the argument supplied, and reads (writes) from the
1155 standard output (standard input) of that shell. If the shell command includes
1156 SPACE characters, the argument must be quoted; for example \fB"| ls
1157 \fR\fB-lt\fR\fB"\fR. A particularly useful example of this mechanism is:
1158 \fB"dir | more"\fR.
1159 .RE
1161 .sp
1162 .ne 2
1163 .na
1164 \fB3)\fR
1165 .ad
1166 .RS 6n
1167 Failing the above checks, if globbing is enabled, local file names are expanded
1168 according to the rules used in the \fBsh\fR(1); see the \fBglob\fR command. If
1169 the \fBftp\fR command expects a single local file (for example, \fBput\fR),
1170 only the first filename generated by the globbing operation is used.
1171 .RE
1173 .sp
1174 .ne 2
1175 .na
1176 \fB4)\fR
1177 .ad
1178 .RS 6n
1179 For \fBmget\fR commands and \fBget\fR commands with unspecified local file
1180 names, the local filename is the remote filename, which can be altered by a
1181 \fBcase\fR, \fBntrans\fR, or \fBnmap\fR setting. The resulting filename can
1182 then be altered if \fBrunique\fR is on.
1183 .RE
1185 .sp
1186 .ne 2
1187 .na
1188 \fB5)\fR
1189 .ad
1190 .RS 6n
1191 For \fBmput\fR commands and \fBput\fR commands with unspecified remote file
1192 names, the remote filename is the local filename, which can be altered by a
1193 \fBntrans\fR or \fBnmap\fR setting. The resulting filename can then be altered
1194 by the remote server if \fBsunique\fR is on.
1195 .RE
1197 .SH FILE TRANSFER PARAMETERS
1198 .LP
1199 The \fBFTP\fR specification specifies many parameters which can affect a file
1200 transfer.
1201 .sp
1202 .LP
1203 The "representation type" can be one of "network \fBASCII\fR", "\fBEBCDIC\fR",
1204 "image", or "local byte size" with a specified byte size (for PDP-10's and
1205 PDP-20's mostly). The "network \fBASCII\fR" and "\fBEBCDIC\fR" types have a
1206 further subtype which specifies whether vertical format control (\fBNEWLINE\fR
1207 characters, form feeds, and so on) are to be passed through ("non-print"),
1208 provided in \fBTELNET\fR format ("\fBTELNET\fR format controls"). \fBftp\fR
1209 supports the "network \fBASCII\fR" (subtype "non-print" only) and "image"
1210 types, plus "local byte size" with a byte size of 8 for communicating with
1211 \fBTENEX\fR machines.
1212 .sp
1213 .LP
1214 The "file structure" can be one of \fBfile\fR (no record structure),
1215 \fBrecord\fR, or \fBpage\fR. \fBftp\fR supports only the default value, which
1216 is \fBfile\fR.
1217 .sp
1218 .LP
1219 The "transfer mode" can be one of \fBstream\fR, \fBblock\fR, or
1220 \fBcompressed\fR. \fBftp\fR supports only the default value, which is
1221 \fBstream\fR.
1222 .sp
1223 .LP
1224 The \fBftp\fR command is IPv6-enabled. See \fBip6\fR(7P).
1225 .SH FILES
1226 .LP
1227 \fB~/.netrc\fR
1228 .SH ATTRIBUTES
1229 .LP
1230 See \fBattributes\fR(5) for descriptions of the following attributes:
1231 .sp
1233 .sp
1234 .TS
1235 box;
1236 c | c
1237 l | l .
1238 ATTRIBUTE TYPE ATTRIBUTE VALUE
1239 _
1240 CSI enabled
1241 .TE
1243 .SH SEE ALSO
1244 .LP
1245 \fBls\fR(1), \fBrcp\fR(1), \fBsh\fR(1), \fBtar\fR(1),
1246 \fBpopen\fR(3C), \fBftp\fR(4), \fBftpusers\fR(4), \fBmech\fR(4),
1247 \fBnetrc\fR(4), \fBattributes\fR(5), \fBip6\fR(7P)
1248 .sp
1249 .LP
1250 Allman, M., Ostermann, S., and Metz, C. \fIRFC 2428, FTP Extensions for IPv6
1251 and NATs\fR. The Internet Society. September 1998.
1252 .sp
1253 .LP
1254 Lunt, S. J. \fIRFC 2228, FTP Security Extensions\fR. Internet Draft. November
1255 1993.
1256 .sp
1257 .LP
1258 Postel, Jon, and Joyce Reynolds. \fIRFC 959, File Transfer Protocol (FTP )\fR.
1259 Network Information Center. October 1985.
1260 .sp
1261 .LP
1262 Piscitello, D. \fIRFC 1639, FTP Operation Over Big Address Records (FOOBAR)\fR.
1263 Network Working Group. June 1994.
1264 .SH NOTES
1265 .LP
1266 Failure to log in can arise from an explicit denial by the remote \fBFTP\fR
1267 server because the account is listed in \fB/etc/ftpusers\fR. See
1268 \fBftpusers\fR(4).
1269 .sp
1270 .LP
1271 Correct execution of many commands depends upon proper behavior by the remote
1272 server.
1273 .sp
1274 .LP
1275 An error in the treatment of carriage returns in the 4.2 \fBBSD\fR code
1276 handling transfers with a "representation type" of "network \fBASCII\fR" has
1277 been corrected. This correction can result in incorrect transfers of binary
1278 files to and from 4.2 \fBBSD\fR servers using a "representation type" of
1279 "network \fBASCII\fR". Avoid this problem by using the "image" type.