1FTP(1) BSD General Commands Manual FTP(1)
2
4 ftp — Internet file transfer program
5
7 ftp [-pinegvd] [host]
8 pftp [-inegvd] [host]
9
11 Ftp is the user interface to the Internet standard File Transfer Proto‐
12 col. The program allows a user to transfer files to and from a remote
13 network site.
14 Options may be specified at the command line, or to the command inter‐
16 preter.
17 -A Use active mode for data transfers. This is useful for transmis‐
19 sions to servers which do not support passive connections (for
20 whatever reason.)
21 -p Use passive mode for data transfers. Allows use of ftp in environ‐
23 ments where a firewall prevents connections from the outside world
24 back to the client machine. Requires that the ftp server support
25 the PASV command. This is the default now for all clients (ftp and
26 pftp) due to security concerns using the PORT transfer mode. The
27 flag is kept for compatibility only and has no effect anymore.
28 -i Turns off interactive prompting during multiple file transfers.
30 -n Restrains ftp from attempting “auto-login” upon initial connection.
32 If auto-login is enabled, ftp will check the .netrc (see netrc(5))
33 file in the user's home directory for an entry describing an
34 account on the remote machine. If no entry exists, ftp will prompt
35 for the remote machine login name (default is the user identity on
36 the local machine), and, if necessary, prompt for a password and an
37 account with which to login.
38 -e Disables command editing and history support, if it was compiled
40 into the ftp executable. Otherwise, does nothing.
41 -g Disables file name globbing.
43 -m The default requires that ftp explicitly binds to the same inter‐
45 face for the data channel as the control channel in passive mode.
46 Useful on multi-homed clients. This option disables this behavior.
47 -v Verbose option forces ftp to show all responses from the remote
49 server, as well as report on data transfer statistics.
50 -d Enables debugging.
52 The client host with which ftp is to communicate may be specified on the
54 command line. If this is done, ftp will immediately attempt to establish
55 a connection to an FTP server on that host; otherwise, ftp will enter its
56 command interpreter and await instructions from the user. When ftp is
57 awaiting commands from the user the prompt ‘ftp>’ is provided to the
58 user. The following commands are recognized by ftp:
59 ! [command [args]]
61 Invoke an interactive shell on the local machine. If there
62 are arguments, the first is taken to be a command to execute
63 directly, with the rest of the arguments as its arguments.
64 $ macro-name [args]
66 Execute the macro macro-name that was defined with the macdef
67 command. Arguments are passed to the macro unglobbed.
68 account [passwd]
70 Supply a supplemental password required by a remote system
71 for access to resources once a login has been successfully
72 completed. If no argument is included, the user will be
73 prompted for an account password in a non-echoing input mode.
74 append local-file [remote-file]
76 Append a local file to a file on the remote machine. If
77 remote-file is left unspecified, the local file name is used
78 in naming the remote file after being altered by any ntrans
79 or nmap setting. File transfer uses the current settings for
80 type, format, mode, and structure.
81 ascii Set the file transfer type to network ASCII. This is the
83 default type.
84 bell Arrange that a bell be sounded after each file transfer com‐
86 mand is completed.
87 binary Set the file transfer type to support binary image transfer.
89 bye Terminate the FTP session with the remote server and exit
91 ftp. An end of file will also terminate the session and
92 exit.
93 case Toggle remote computer file name case mapping during mget
95 commands. When case is on (default is off), remote computer
96 file names with all letters in upper case are written in the
97 local directory with the letters mapped to lower case.
98 cd remote-directory
100 Change the working directory on the remote machine to
101 remote-directory.
102 cdup Change the remote machine working directory to the parent of
104 the current remote machine working directory.
105 chmod mode file-name
107 Change the permission modes of the file file-name on the
108 remote system to mode.
109 close Terminate the FTP session with the remote server, and return
111 to the command interpreter. Any defined macros are erased.
112 cr Toggle carriage return stripping during ascii type file
114 retrieval. Records are denoted by a carriage return/linefeed
115 sequence during ascii type file transfer. When cr is on (the
116 default), carriage returns are stripped from this sequence to
117 conform with the UNIX single linefeed record delimiter.
118 Records on non-UNIX remote systems may contain single line‐
119 feeds; when an ascii type transfer is made, these linefeeds
120 may be distinguished from a record delimiter only when cr is
121 off.
122 delete remote-file
124 Delete the file remote-file on the remote machine.
125 debug [debug-value]
127 Toggle debugging mode. If an optional debug-value is speci‐
128 fied it is used to set the debugging level. When debugging
129 is on, ftp prints each command sent to the remote machine,
130 preceded by the string ‘-->’
131 dir [remote-directory] [local-file]
133 Print a listing of the directory contents in the directory,
134 remote-directory, and, optionally, placing the output in
135 local-file. If interactive prompting is on, ftp will prompt
136 the user to verify that the last argument is indeed the tar‐
137 get local file for receiving dir output. If no directory is
138 specified, the current working directory on the remote
139 machine is used. If no local file is specified, or
140 local-file is -, output comes to the terminal.
141 disconnect A synonym for close.
143 form format
145 Set the file transfer form to format. The default format is
146 “file”.
147 get remote-file [local-file]
149 Retrieve the remote-file and store it on the local machine.
150 If the local file name is not specified, it is given the same
151 name it has on the remote machine, subject to alteration by
152 the current case, ntrans, and nmap settings. The current
153 settings for type, form, mode, and structure are used while
154 transferring the file.
155 glob Toggle filename expansion for mdelete, mget and mput. If
157 globbing is turned off with glob, the file name arguments are
158 taken literally and not expanded. Globbing for mput is done
159 as in csh(1). For mdelete and mget, each remote file name is
160 expanded separately on the remote machine and the lists are
161 not merged. Expansion of a directory name is likely to be
162 different from expansion of the name of an ordinary file: the
163 exact result depends on the foreign operating system and ftp
164 server, and can be previewed by doing ‘mls remote-files -’
165 Note: mget and mput are not meant to transfer entire direc‐
166 tory subtrees of files. That can be done by transferring a
167 tar(1) archive of the subtree (in binary mode).
168 hash Toggle hash-sign (``#'') printing for each data block trans‐
170 ferred. The size of a data block is 1024 bytes.
171 help [command]
173 Print an informative message about the meaning of command.
174 If no argument is given, ftp prints a list of the known com‐
175 mands.
176 idle [seconds]
178 Set the inactivity timer on the remote server to seconds sec‐
179 onds. If seconds is omitted, the current inactivity timer is
180 printed.
181 lcd [directory]
183 Change the working directory on the local machine. If no
184 directory is specified, the user's home directory is used.
185 ls [remote-directory] [local-file]
187 Print a listing of the contents of a directory on the remote
188 machine. The listing includes any system-dependent informa‐
189 tion that the server chooses to include; for example, most
190 UNIX systems will produce output from the command ‘ls -l’.
191 (See also nlist.) If remote-directory is left unspecified,
192 the current working directory is used. If interactive
193 prompting is on, ftp will prompt the user to verify that the
194 last argument is indeed the target local file for receiving
195 ls output. If no local file is specified, or if local-file
196 is ‘-’, the output is sent to the terminal.
197 macdef macro-name
199 Define a macro. Subsequent lines are stored as the macro
200 macro-name; a null line (consecutive newline characters in a
201 file or carriage returns from the terminal) terminates macro
202 input mode. There is a limit of 16 macros and 4096 total
203 characters in all defined macros. Macros remain defined
204 until a close command is executed. The macro processor
205 interprets `$' and `\' as special characters. A `$' followed
206 by a number (or numbers) is replaced by the corresponding
207 argument on the macro invocation command line. A `$' fol‐
208 lowed by an `i' signals that macro processor that the execut‐
209 ing macro is to be looped. On the first pass `$i' is
210 replaced by the first argument on the macro invocation com‐
211 mand line, on the second pass it is replaced by the second
212 argument, and so on. A `\' followed by any character is
213 replaced by that character. Use the `\' to prevent special
214 treatment of the `$'.
215 mdelete [remote-files]
217 Delete the remote-files on the remote machine.
218 mdir remote-files local-file
220 Like dir, except multiple remote files may be specified. If
221 interactive prompting is on, ftp will prompt the user to ver‐
222 ify that the last argument is indeed the target local file
223 for receiving mdir output.
224 mget remote-files
226 Expand the remote-files on the remote machine and do a get
227 for each file name thus produced. See glob for details on
228 the filename expansion. Resulting file names will then be
229 processed according to case, ntrans, and nmap settings.
230 Files are transferred into the local working directory, which
231 can be changed with ‘lcd directory’; new local directories
232 can be created with ‘! mkdir directory’.
233 mkdir directory-name
235 Make a directory on the remote machine.
236 mls remote-files local-file
238 Like nlist, except multiple remote files may be specified,
239 and the local-file must be specified. If interactive prompt‐
240 ing is on, ftp will prompt the user to verify that the last
241 argument is indeed the target local file for receiving mls
242 output.
243 mode [mode-name]
245 Set the file transfer mode to mode-name. The default mode is
246 “stream” mode.
247 modtime file-name
249 Show the last modification time of the file on the remote
250 machine.
251 mput local-files
253 Expand wild cards in the list of local files given as argu‐
254 ments and do a put for each file in the resulting list. See
255 glob for details of filename expansion. Resulting file names
256 will then be processed according to ntrans and nmap settings.
257 newer file-name [local-file]
259 Get the file only if the modification time of the remote file
260 is more recent that the file on the current system. If the
261 file does not exist on the current system, the remote file is
262 considered newer. Otherwise, this command is identical to
263 get.
264 nlist [remote-directory] [local-file]
266 Print a list of the files in a directory on the remote
267 machine. If remote-directory is left unspecified, the cur‐
268 rent working directory is used. If interactive prompting is
269 on, ftp will prompt the user to verify that the last argument
270 is indeed the target local file for receiving nlist output.
271 If no local file is specified, or if local-file is -, the
272 output is sent to the terminal.
273 nmap [inpattern outpattern]
275 Set or unset the filename mapping mechanism. If no arguments
276 are specified, the filename mapping mechanism is unset. If
277 arguments are specified, remote filenames are mapped during
278 mput commands and put commands issued without a specified
279 remote target filename. If arguments are specified, local
280 filenames are mapped during mget commands and get commands
281 issued without a specified local target filename. This com‐
282 mand is useful when connecting to a non-UNIX remote computer
283 with different file naming conventions or practices. The
284 mapping follows the pattern set by inpattern and outpattern.
285 [Inpattern] is a template for incoming filenames (which may
286 have already been processed according to the ntrans and case
287 settings). Variable templating is accomplished by including
288 the sequences `$1', `$2', ..., `$9' in inpattern. Use `\' to
289 prevent this special treatment of the `$' character. All
290 other characters are treated literally, and are used to
291 determine the nmap [inpattern] variable values. For example,
292 given inpattern $1.$2 and the remote file name "mydata.data",
293 $1 would have the value "mydata", and $2 would have the value
294 "data". The outpattern determines the resulting mapped file‐
295 name. The sequences `$1', `$2', ...., `$9' are replaced by
296 any value resulting from the inpattern template. The
297 sequence `$0' is replace by the original filename. Addition‐
298 ally, the sequence ‘[seq1, seq2]’ is replaced by [seq1] if
299 seq1 is not a null string; otherwise it is replaced by seq2.
300 For example, the command
301 nmap $1.$2.$3 [$1,$2].[$2,file]
303 would yield the output filename "myfile.data" for input file‐
305 names "myfile.data" and "myfile.data.old", "myfile.file" for
306 the input filename "myfile", and "myfile.myfile" for the
307 input filename ".myfile". Spaces may be included in
308 outpattern, as in the example: `nmap $1 sed "s/ *$//" > $1'
309 . Use the `\' character to prevent special treatment of the
310 `$','[','[', and `,' characters.
311 ntrans [inchars [outchars]]
313 Set or unset the filename character translation mechanism.
314 If no arguments are specified, the filename character trans‐
315 lation mechanism is unset. If arguments are specified, char‐
316 acters in remote filenames are translated during mput com‐
317 mands and put commands issued without a specified remote tar‐
318 get filename. If arguments are specified, characters in
319 local filenames are translated during mget commands and get
320 commands issued without a specified local target filename.
321 This command is useful when connecting to a non-UNIX remote
322 computer with different file naming conventions or practices.
323 Characters in a filename matching a character in inchars are
324 replaced with the corresponding character in outchars. If
325 the character's position in inchars is longer than the length
326 of outchars, the character is deleted from the file name.
327 open host [port]
329 Establish a connection to the specified host FTP server. An
330 optional port number may be supplied, in which case, ftp will
331 attempt to contact an FTP server at that port. If the
332 auto-login option is on (default), ftp will also attempt to
333 automatically log the user in to the FTP server (see below).
334 prompt Toggle interactive prompting. Interactive prompting occurs
336 during multiple file transfers to allow the user to selec‐
337 tively retrieve or store files. If prompting is turned off
338 (default is on), any mget or mput will transfer all files,
339 and any mdelete will delete all files.
340 proxy ftp-command
342 Execute an ftp command on a secondary control connection.
343 This command allows simultaneous connection to two remote ftp
344 servers for transferring files between the two servers. The
345 first proxy command should be an open, to establish the sec‐
346 ondary control connection. Enter the command "proxy ?" to
347 see other ftp commands executable on the secondary connec‐
348 tion. The following commands behave differently when pref‐
349 aced by proxy: open will not define new macros during the
350 auto-login process, close will not erase existing macro defi‐
351 nitions, get and mget transfer files from the host on the
352 primary control connection to the host on the secondary con‐
353 trol connection, and put, mput, and append transfer files
354 from the host on the secondary control connection to the host
355 on the primary control connection. Third party file trans‐
356 fers depend upon support of the ftp protocol PASV command by
357 the server on the secondary control connection.
358 put local-file [remote-file]
360 Store a local file on the remote machine. If remote-file is
361 left unspecified, the local file name is used after process‐
362 ing according to any ntrans or nmap settings in naming the
363 remote file. File transfer uses the current settings for
364 type, format, mode, and structure.
365 pwd Print the name of the current working directory on the remote
367 machine.
368 quit A synonym for bye.
370 quote arg1 arg2 ...
372 The arguments specified are sent, verbatim, to the remote FTP
373 server.
374 recv remote-file [local-file]
376 A synonym for get.
377 reget remote-file [local-file]
379 Reget acts like get, except that if local-file exists and is
380 smaller than remote-file, local-file is presumed to be a par‐
381 tially transferred copy of remote-file and the transfer is
382 continued from the apparent point of failure. This command
383 is useful when transferring very large files over networks
384 that are prone to dropping connections.
385 remotehelp [command-name]
387 Request help from the remote FTP server. If a command-name
388 is specified it is supplied to the server as well.
389 remotestatus [file-name]
391 With no arguments, show status of remote machine. If
392 file-name is specified, show status of file-name on remote
393 machine.
394 rename [from] [to]
396 Rename the file from on the remote machine, to the file to.
397 reset Clear reply queue. This command re-synchronizes com‐
399 mand/reply sequencing with the remote ftp server. Resynchro‐
400 nization may be necessary following a violation of the ftp
401 protocol by the remote server.
402 restart marker
404 Restart the immediately following get or put at the indicated
405 marker. On UNIX systems, marker is usually a byte offset
406 into the file.
407 rmdir directory-name
409 Delete a directory on the remote machine.
410 runique Toggle storing of files on the local system with unique file‐
412 names. If a file already exists with a name equal to the
413 target local filename for a get or mget command, a ".1" is
414 appended to the name. If the resulting name matches another
415 existing file, a ".2" is appended to the original name. If
416 this process continues up to ".99", an error message is
417 printed, and the transfer does not take place. The generated
418 unique filename will be reported. Note that runique will not
419 affect local files generated from a shell command (see
420 below). The default value is off.
421 send local-file [remote-file]
423 A synonym for put.
424 sendport Toggle the use of PORT commands. By default, ftp will
426 attempt to use a PORT command when establishing a connection
427 for each data transfer. The use of PORT commands can prevent
428 delays when performing multiple file transfers. If the PORT
429 command fails, ftp will use the default data port. When the
430 use of PORT commands is disabled, no attempt will be made to
431 use PORT commands for each data transfer. This is useful for
432 certain FTP implementations which do ignore PORT commands
433 but, incorrectly, indicate they've been accepted.
434 site arg1 arg2 ...
436 The arguments specified are sent, verbatim, to the remote FTP
437 server as a SITE command.
438 size file-name
440 Return size of file-name on remote machine.
441 status Show the current status of ftp.
443 struct [struct-name]
445 Set the file transfer structure to struct-name. By default
446 “stream” structure is used.
447 sunique Toggle storing of files on remote machine under unique file
449 names. Remote ftp server must support ftp protocol STOU com‐
450 mand for successful completion. The remote server will
451 report unique name. Default value is off.
452 system Show the type of operating system running on the remote
454 machine.
455 tenex Set the file transfer type to that needed to talk to TENEX
457 machines.
458 trace Toggle packet tracing.
460 type [type-name]
462 Set the file transfer type to type-name. If no type is spec‐
463 ified, the current type is printed. The default type is net‐
464 work ASCII.
465 umask [newmask]
467 Set the default umask on the remote server to newmask. If
468 newmask is omitted, the current umask is printed.
469 user user-name [password] [account]
471 Identify yourself to the remote FTP server. If the password
472 is not specified and the server requires it, ftp will prompt
473 the user for it (after disabling local echo). If an account
474 field is not specified, and the FTP server requires it, the
475 user will be prompted for it. If an account field is speci‐
476 fied, an account command will be relayed to the remote server
477 after the login sequence is completed if the remote server
478 did not require it for logging in. Unless ftp is invoked
479 with “auto-login” disabled, this process is done automati‐
480 cally on initial connection to the FTP server.
481 verbose Toggle verbose mode. In verbose mode, all responses from the
483 FTP server are displayed to the user. In addition, if ver‐
484 bose is on, when a file transfer completes, statistics
485 regarding the efficiency of the transfer are reported. By
486 default, verbose is on.
487 ? [command]
489 A synonym for help.
490 Command arguments which have embedded spaces may be quoted with quote `"'
492 marks.
493
495 To abort a file transfer, use the terminal interrupt key (usually Ctrl-
496 C). Sending transfers will be immediately halted. Receiving transfers
497 will be halted by sending a ftp protocol ABOR command to the remote
498 server, and discarding any further data received. The speed at which
499 this is accomplished depends upon the remote server's support for ABOR
500 processing. If the remote server does not support the ABOR command, an
501 ‘ftp>’ prompt will not appear until the remote server has completed send‐
502 ing the requested file.
503 The terminal interrupt key sequence will be ignored when ftp has com‐
505 pleted any local processing and is awaiting a reply from the remote
506 server. A long delay in this mode may result from the ABOR processing
507 described above, or from unexpected behavior by the remote server,
508 including violations of the ftp protocol. If the delay results from
509 unexpected remote server behavior, the local ftp program must be killed
510 by hand.
511
513 Files specified as arguments to ftp commands are processed according to
514 the following rules.
515 1. If the file name ‘-’ is specified, the stdin (for reading) or stdout
517 (for writing) is used.
518 2. If the first character of the file name is ‘|’, the remainder of the
520 argument is interpreted as a shell command. Ftp then forks a shell,
521 using popen(3) with the argument supplied, and reads (writes) from
522 the stdout (stdin). If the shell command includes spaces, the argu‐
523 ment must be quoted; e.g. “" ls -lt"”. A particularly useful exam‐
524 ple of this mechanism is: “dir more”.
525 3. Failing the above checks, if ``globbing'' is enabled, local file
527 names are expanded according to the rules used in the csh(1); c.f.
528 the glob command. If the ftp command expects a single local file
529 (.e.g. put), only the first filename generated by the "globbing"
530 operation is used.
531 4. For mget commands and get commands with unspecified local file
533 names, the local filename is the remote filename, which may be
534 altered by a case, ntrans, or nmap setting. The resulting filename
535 may then be altered if runique is on.
536 5. For mput commands and put commands with unspecified remote file
538 names, the remote filename is the local filename, which may be
539 altered by a ntrans or nmap setting. The resulting filename may
540 then be altered by the remote server if sunique is on.
541
543 The FTP specification specifies many parameters which may affect a file
544 transfer. The type may be one of “ascii”, “image” (binary), “ebcdic”,
545 and “local byte size” (for PDP-10's and PDP-20's mostly). Ftp supports
546 the ascii and image types of file transfer, plus local byte size 8 for
547 tenex mode transfers.
548 Ftp supports only the default values for the remaining file transfer
550 parameters: mode, form, and struct.
551
553 Ftp utilizes the following environment variables.
554 HOME For default location of a .netrc file, if one exists.
556 SHELL For default shell.
558
560 ftpd(8), RFC 959
561
563 The ftp command appeared in 4.2BSD.
564
566 Correct execution of many commands depends upon proper behavior by the
567 remote server.
568 An error in the treatment of carriage returns in the 4.2BSD ascii-mode
570 transfer code has been corrected. This correction may result in incor‐
571 rect transfers of binary files to and from 4.2BSD servers using the ascii
572 type. Avoid this problem by using the binary image type.
573Linux NetKit (0.17) August 15, 1999 Linux NetKit (0.17)