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