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