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