1.\" $NetBSD: ftp.1,v 1.101 2003/12/19 03:46:02 lukem Exp $ 2.\" 3.\" Copyright (c) 1996-2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" 38.\" Copyright (c) 1985, 1989, 1990, 1993 39.\" The Regents of the University of California. All rights reserved. 40.\" 41.\" Redistribution and use in source and binary forms, with or without 42.\" modification, are permitted provided that the following conditions 43.\" are met: 44.\" 1. Redistributions of source code must retain the above copyright 45.\" notice, this list of conditions and the following disclaimer. 46.\" 2. Redistributions in binary form must reproduce the above copyright 47.\" notice, this list of conditions and the following disclaimer in the 48.\" documentation and/or other materials provided with the distribution. 49.\" 3. Neither the name of the University nor the names of its contributors 50.\" may be used to endorse or promote products derived from this software 51.\" without specific prior written permission. 52.\" 53.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 54.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 55.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 56.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 57.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 58.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 59.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 60.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 61.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 62.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 63.\" SUCH DAMAGE. 64.\" 65.\" @(#)ftp.1 8.3 (Berkeley) 10/9/94 66.\" 67.Dd December 19, 2003 68.Dt FTP 1 69.Os 70.Sh NAME 71.Nm ftp 72.Nd 73Internet file transfer program 74.Sh SYNOPSIS 75.Nm 76.Op Fl 46AadefginpRtvV 77.Bk -words 78.Op Fl N Ar netrc 79.Ek 80.Bk -words 81.Op Fl o Ar output 82.Ek 83.Bk -words 84.Op Fl P Ar port 85.Ek 86.Bk -words 87.Op Fl q Ar quittime 88.Ek 89.Bk -words 90.Op Fl r Ar retry 91.Ek 92.Bk -words 93.\" [-T dir,max[,inc]] 94.Oo 95.Fl T Xo 96.Sm off 97.Ar dir , 98.Ar max 99.Op , Ar inc 100.Sm on 101.Xc 102.Oc 103.Ek 104.Bk -words 105.\" [[user@]host [port]] 106.Oo 107.Oo Ar user Ns Li \&@ Oc Ns Ar host 108.Op Ar port 109.Oc 110.Ek 111.Bk -words 112.\" [[user@]host:[path][/]] 113.Sm off 114.Oo 115.Op Ar user Li \&@ 116.Ar host Li \&: 117.Op Ar path 118.Op Li / 119.Oc 120.Sm on 121.Ek 122.Bk -words 123.\" [file:///path] 124.Sm off 125.Oo 126.Li file:/// Ar path 127.Oc 128.Sm on 129.Ek 130.Bk -words 131.\" [ftp://[user[:password]@]host[:port]/path[/]] 132.Sm off 133.Oo 134.Li ftp:// 135.Oo Ar user 136.Op Li \&: Ar password 137.Li \&@ Oc 138.Ar host Oo Li \&: Ar port Oc 139.Li / Ar path 140.Op Li / 141.Op Li ;type= Ar X 142.Oc 143.Sm on 144.Ek 145.Bk -words 146.\" [http://[user[:password]@]host[:port]/path] 147.Sm off 148.Oo 149.Li http:// 150.Oo Ar user 151.Op Li \&: Ar password 152.Li \&@ Oc 153.Ar host Oo Li \&: Ar port Oc 154.Li / Ar path 155.Oc 156.Sm on 157.Ek 158.Op Ar \&.\&.\&. 159.Nm 160.Bk -words 161.Fl u Ar URL Ar file 162.Ek 163.Op Ar \&.\&.\&. 164.Sh DESCRIPTION 165.Nm 166is the user interface to the Internet standard File Transfer Protocol. 167The program allows a user to transfer files to and from a 168remote network site. 169.Pp 170The last five arguments will fetch a file using the 171.Tn FTP 172or 173.Tn HTTP 174protocols, or by direct copying, into the current directory. 175This is ideal for scripts. 176Refer to 177.Sx AUTO-FETCHING FILES 178below for more information. 179.Pp 180Options may be specified at the command line, or to the 181command interpreter. 182.Bl -tag -width "port " 183.It Fl 4 184Forces 185.Nm 186to only use IPv4 addresses. 187.It Fl 6 188Forces 189.Nm 190to only use IPv6 addresses. 191.It Fl A 192Force active mode ftp. 193By default, 194.Nm 195will try to use passive mode ftp and fall back to active mode 196if passive is not supported by the server. 197This option causes 198.Nm 199to always use an active connection. 200It is only useful for connecting to very old servers that do not 201implement passive mode properly. 202.It Fl a 203Causes 204.Nm 205to bypass normal login procedure, and use an anonymous login instead. 206.It Fl d 207Enables debugging. 208.It Fl e 209Disables command line editing. 210This is useful for Emacs ange-ftp mode. 211.It Fl f 212Forces a cache reload for transfers that go through the 213.Tn FTP 214or 215.Tn HTTP 216proxies. 217.It Fl g 218Disables file name globbing. 219.It Fl i 220Turns off interactive prompting during 221multiple file transfers. 222.It Fl n 223Restrains 224.Nm 225from attempting 226.Dq auto-login 227upon initial connection for non auto-fetch transfers. 228If auto-login is enabled, 229.Nm 230will check the 231.Pa .netrc 232(see below) file in the user's home directory for an entry describing 233an account on the remote machine. 234If no entry exists, 235.Nm 236will prompt for the remote machine login name (default is the user 237identity on the local machine), and, if necessary, prompt for a password 238and an account with which to login. 239To override the auto-login for auto-fetch transfers, specify the 240username (and optionally, password) as appropriate. 241.It Fl N Ar netrc 242Use 243.Ar netrc 244instead of 245.Pa ~/.netrc . 246Refer to 247.Sx THE .netrc FILE 248for more information. 249.It Fl o Ar output 250When auto-fetching files, save the contents in 251.Ar output . 252.Ar output 253is parsed according to the 254.Sx FILE NAMING CONVENTIONS 255below. 256If 257.Ar output 258is not 259.Sq - 260or doesn't start with 261.Sq \&| , 262then only the first file specified will be retrieved into 263.Ar output ; 264all other files will be retrieved into the basename of their 265remote name. 266.It Fl p 267Enable passive mode operation for use behind connection filtering firewalls. 268This option has been deprecated as 269.Nm 270now tries to use passive mode by default, falling back to active mode 271if the server does not support passive connections. 272.It Fl P Ar port 273Sets the port number to 274.Ar port . 275.It Fl r Ar wait 276Retry the connection attempt if it failed, pausing for 277.Ar wait 278seconds. 279.It Fl q Ar quittime 280Quit if the connection has stalled for 281.Ar quittime 282seconds. 283.It Fl R 284Restart all non-proxied auto-fetches. 285.It Fl t 286Enables packet tracing. 287.It Xo 288.Fl T 289.Sm off 290.Ar direction , 291.Ar maximum 292.Op , Ar increment 293.Sm on 294.Xc 295Set the maximum transfer rate for 296.Ar direction 297to 298.Ar maximum 299bytes/second, 300and if specified, the increment to 301.Ar increment 302bytes/second. 303Refer to 304.Ic rate 305for more information. 306.It Fl u Ar URL file Op \&.\&.\&. 307Upload files on the command line to 308.Ar URL 309where 310.Ar URL 311is one of the ftp URL types as supported by auto-fetch 312(with an optional target filename for single file uploads), and 313.Ar file 314is one or more local files to be uploaded. 315.It Fl v 316Enable 317.Ic verbose 318and 319.Ic progress . 320This is the default if output is to a terminal (and in the case of 321.Ic progress , 322.Nm 323is the foreground process). 324Forces 325.Nm 326to show all responses from the remote server, as well 327as report on data transfer statistics. 328.It Fl V 329Disable 330.Ic verbose 331and 332.Ic progress , 333overriding the default of enabled when output is to a terminal. 334.El 335.Pp 336The client host with which 337.Nm 338is to communicate may be specified on the command line. 339If this is done, 340.Nm 341will immediately attempt to establish a connection to an 342.Tn FTP 343server on that host; otherwise, 344.Nm 345will enter its command interpreter and await instructions 346from the user. 347When 348.Nm 349is awaiting commands from the user the prompt 350.Ql ftp\*[Gt] 351is provided to the user. 352The following commands are recognized 353by 354.Nm ftp : 355.Bl -tag -width Fl 356.It Ic \&! Op Ar command Op Ar args 357Invoke an interactive shell on the local machine. 358If there are arguments, the first is taken to be a command to execute 359directly, with the rest of the arguments as its arguments. 360.It Ic \&$ Ar macro-name Op Ar args 361Execute the macro 362.Ar macro-name 363that was defined with the 364.Ic macdef 365command. 366Arguments are passed to the macro unglobbed. 367.It Ic account Op Ar passwd 368Supply a supplemental password required by a remote system for access 369to resources once a login has been successfully completed. 370If no argument is included, the user will be prompted for an account 371password in a non-echoing input mode. 372.It Ic append Ar local-file Op Ar remote-file 373Append a local file to a file on the remote machine. 374If 375.Ar remote-file 376is left unspecified, the local file name is used in naming the 377remote file after being altered by any 378.Ic ntrans 379or 380.Ic nmap 381setting. 382File transfer uses the current settings for 383.Ic type , 384.Ic format , 385.Ic mode , 386and 387.Ic structure . 388.It Ic ascii 389Set the file transfer 390.Ic type 391to network 392.Tn ASCII . 393This is the default type. 394.It Ic bell 395Arrange that a bell be sounded after each file transfer 396command is completed. 397.It Ic binary 398Set the file transfer 399.Ic type 400to support binary image transfer. 401.It Ic bye 402Terminate the 403.Tn FTP 404session with the remote server 405and exit 406.Nm ftp . 407An end of file will also terminate the session and exit. 408.It Ic case 409Toggle remote computer file name case mapping during 410.Ic get , 411.Ic mget 412and 413.Ic mput 414commands. 415When 416.Ic case 417is on (default is off), remote computer file names with all letters in 418upper case are written in the local directory with the letters mapped 419to lower case. 420.It Ic \&cd Ar remote-directory 421Change the working directory on the remote machine 422to 423.Ar remote-directory . 424.It Ic cdup 425Change the remote machine working directory to the parent of the 426current remote machine working directory. 427.It Ic chmod Ar mode remote-file 428Change the permission modes of the file 429.Ar remote-file 430on the remote 431system to 432.Ar mode . 433.It Ic close 434Terminate the 435.Tn FTP 436session with the remote server, and 437return to the command interpreter. 438Any defined macros are erased. 439.It Ic \&cr 440Toggle carriage return stripping during 441ascii type file retrieval. 442Records are denoted by a carriage return/linefeed sequence 443during ascii type file transfer. 444When 445.Ic \&cr 446is on (the default), carriage returns are stripped from this 447sequence to conform with the 448.Ux 449single linefeed record 450delimiter. 451Records on 452.Pf non\- Ns Ux 453remote systems may contain single linefeeds; 454when an ascii type transfer is made, these linefeeds may be 455distinguished from a record delimiter only when 456.Ic \&cr 457is off. 458.It Ic debug Op Ar debug-value 459Toggle debugging mode. 460If an optional 461.Ar debug-value 462is specified it is used to set the debugging level. 463When debugging is on, 464.Nm 465prints each command sent to the remote machine, preceded 466by the string 467.Ql \-\-\*[Gt] 468.It Ic delete Ar remote-file 469Delete the file 470.Ar remote-file 471on the remote machine. 472.It Ic dir Op Ar remote-path Op Ar local-file 473Print a listing of the contents of a 474directory on the remote machine. 475The listing includes any system-dependent information that the server 476chooses to include; for example, most 477.Ux 478systems will produce 479output from the command 480.Ql ls \-l . 481If 482.Ar remote-path 483is left unspecified, the current working directory is used. 484If interactive prompting is on, 485.Nm 486will prompt the user to verify that the last argument is indeed the 487target local file for receiving 488.Ic dir 489output. 490If no local file is specified, or if 491.Ar local-file 492is 493.Sq Fl , 494the output is sent to the terminal. 495.It Ic disconnect 496A synonym for 497.Ic close . 498.It Ic edit 499Toggle command line editing, and context sensitive command and file 500completion. 501This is automatically enabled if input is from a terminal, and 502disabled otherwise. 503.It Ic epsv4 504Toggle the use of the extended 505.Dv EPSV 506and 507.Dv EPRT 508commands on IPv4 connections; first try 509.Dv EPSV / 510.Dv EPRT , 511and then 512.Dv PASV / 513.Dv PORT . 514This is enabled by default. 515If an extended command fails then this option will be temporarily 516disabled for the duration of the current connection, or until 517.Ic epsv4 518is executed again. 519.It Ic exit 520A synonym for 521.Ic bye . 522.It Ic features 523Display what features the remote server supports (using the 524.Dv FEAT 525command). 526.It Ic fget Ar localfile 527Retrieve the files listed in 528.Ar localfile , 529which has one line per filename. 530.It Ic form Ar format 531Set the file transfer 532.Ic form 533to 534.Ar format . 535The default (and only supported) 536format is 537.Dq non-print . 538.It Ic ftp Ar host Op Ar port 539A synonym for 540.Ic open . 541.It Ic gate Op Ar host Op Ar port 542Toggle gate-ftp mode, which used to connect through the 543TIS FWTK and Gauntlet ftp proxies. 544This will not be permitted if the gate-ftp server hasn't been set 545(either explicitly by the user, or from the 546.Ev FTPSERVER 547environment variable). 548If 549.Ar host 550is given, 551then gate-ftp mode will be enabled, and the gate-ftp server will be set to 552.Ar host . 553If 554.Ar port 555is also given, that will be used as the port to connect to on the 556gate-ftp server. 557.It Ic get Ar remote-file Op Ar local-file 558Retrieve the 559.Ar remote-file 560and store it on the local machine. 561If the local 562file name is not specified, it is given the same 563name it has on the remote machine, subject to 564alteration by the current 565.Ic case , 566.Ic ntrans , 567and 568.Ic nmap 569settings. 570The current settings for 571.Ic type , 572.Ic form , 573.Ic mode , 574and 575.Ic structure 576are used while transferring the file. 577.It Ic glob 578Toggle filename expansion for 579.Ic mdelete , 580.Ic mget , 581.Ic mput , 582and 583.Ic mreget . 584If globbing is turned off with 585.Ic glob , 586the file name arguments 587are taken literally and not expanded. 588Globbing for 589.Ic mput 590is done as in 591.Xr csh 1 . 592For 593.Ic mdelete , 594.Ic mget , 595and 596.Ic mreget , 597each remote file name is expanded 598separately on the remote machine and the lists are not merged. 599Expansion of a directory name is likely to be 600different from expansion of the name of an ordinary file: 601the exact result depends on the foreign operating system and ftp server, 602and can be previewed by doing 603.Ql mls remote-files \- 604Note: 605.Ic mget , 606.Ic mput 607and 608.Ic mreget 609are not meant to transfer 610entire directory subtrees of files. 611That can be done by 612transferring a 613.Xr tar 1 614archive of the subtree (in binary mode). 615.It Ic hash Op Ar size 616Toggle hash-sign (``#'') printing for each data block 617transferred. 618The size of a data block defaults to 1024 bytes. 619This can be changed by specifying 620.Ar size 621in bytes. 622Enabling 623.Ic hash 624disables 625.Ic progress . 626.It Ic help Op Ar command 627Print an informative message about the meaning of 628.Ar command . 629If no argument is given, 630.Nm 631prints a list of the known commands. 632.It Ic idle Op Ar seconds 633Set the inactivity timer on the remote server to 634.Ar seconds 635seconds. 636If 637.Ar seconds 638is omitted, the current inactivity timer is printed. 639.It Ic image 640A synonym for 641.Ic binary . 642.It Ic lcd Op Ar directory 643Change the working directory on the local machine. 644If 645no 646.Ar directory 647is specified, the user's home directory is used. 648.It Ic less Ar file 649A synonym for 650.Ic page . 651.It Ic lpage Ar local-file 652Display 653.Ar local-file 654with the program specified by the 655.Ic "set pager" 656option. 657.It Ic lpwd 658Print the working directory on the local machine. 659.It Ic \&ls Op Ar remote-path Op Ar local-file 660A synonym for 661.Ic dir . 662.It Ic macdef Ar macro-name 663Define a macro. 664Subsequent lines are stored as the macro 665.Ar macro-name ; 666a null line (consecutive newline characters 667in a file or 668carriage returns from the terminal) terminates macro input mode. 669There is a limit of 16 macros and 4096 total characters in all 670defined macros. 671Macros remain defined until a 672.Ic close 673command is executed. 674The macro processor interprets `$' and `\e' as special characters. 675A `$' followed by a number (or numbers) is replaced by the 676corresponding argument on the macro invocation command line. 677A `$' followed by an `i' signals that macro processor that the 678executing macro is to be looped. 679On the first pass `$i' is 680replaced by the first argument on the macro invocation command line, 681on the second pass it is replaced by the second argument, and so on. 682A `\e' followed by any character is replaced by that character. 683Use the `\e' to prevent special treatment of the `$'. 684.It Ic mdelete Op Ar remote-files 685Delete the 686.Ar remote-files 687on the remote machine. 688.It Ic mdir Ar remote-files local-file 689Like 690.Ic dir , 691except multiple remote files may be specified. 692If interactive prompting is on, 693.Nm 694will prompt the user to verify that the last argument is indeed the 695target local file for receiving 696.Ic mdir 697output. 698.It Ic mget Ar remote-files 699Expand the 700.Ar remote-files 701on the remote machine 702and do a 703.Ic get 704for each file name thus produced. 705See 706.Ic glob 707for details on the filename expansion. 708Resulting file names will then be processed according to 709.Ic case , 710.Ic ntrans , 711and 712.Ic nmap 713settings. 714Files are transferred into the local working directory, 715which can be changed with 716.Ql lcd directory ; 717new local directories can be created with 718.Ql "\&! mkdir directory" . 719.It Ic mkdir Ar directory-name 720Make a directory on the remote machine. 721.It Ic mls Ar remote-files local-file 722Like 723.Ic ls , 724except multiple remote files may be specified, 725and the 726.Ar local-file 727must be specified. 728If interactive prompting is on, 729.Nm 730will prompt the user to verify that the last argument is indeed the 731target local file for receiving 732.Ic mls 733output. 734.It Ic mlsd Op Ar remote-path 735Display the contents of 736.Ar remote-path 737(which should default to the current directory if not given) 738in a machine-parsable form, using 739.Dv MLSD . 740The format of display can be changed with 741.Sq "remopts mlst ..." . 742.It Ic mlst Op Ar remote-path 743Display the details about 744.Ar remote-path 745(which should default to the current directory if not given) 746in a machine-parsable form, using 747.Dv MLST . 748The format of display can be changed with 749.Sq "remopts mlst ..." . 750.It Ic mode Ar mode-name 751Set the file transfer 752.Ic mode 753to 754.Ar mode-name . 755The default (and only supported) 756mode is 757.Dq stream . 758.It Ic modtime Ar remote-file 759Show the last modification time of the file on the remote machine. 760.It Ic more Ar file 761A synonym for 762.Ic page . 763.It Ic mput Ar local-files 764Expand wild cards in the list of local files given as arguments 765and do a 766.Ic put 767for each file in the resulting list. 768See 769.Ic glob 770for details of filename expansion. 771Resulting file names will then be processed according to 772.Ic ntrans 773and 774.Ic nmap 775settings. 776.It Ic mreget Ar remote-files 777As per 778.Ic mget , 779but performs a 780.Ic reget 781instead of 782.Ic get . 783.It Ic msend Ar local-files 784A synonym for 785.Ic mput . 786.It Ic newer Ar remote-file Op Ar local-file 787Get the file only if the modification time of the remote file is more 788recent that the file on the current system. 789If the file does not 790exist on the current system, the remote file is considered 791.Ic newer . 792Otherwise, this command is identical to 793.Ar get . 794.It Ic nlist Op Ar remote-path Op Ar local-file 795A synonym for 796.Ic ls . 797.It Ic nmap Op Ar inpattern outpattern 798Set or unset the filename mapping mechanism. 799If no arguments are specified, the filename mapping mechanism is unset. 800If arguments are specified, remote filenames are mapped during 801.Ic mput 802commands and 803.Ic put 804commands issued without a specified remote target filename. 805If arguments are specified, local filenames are mapped during 806.Ic mget 807commands and 808.Ic get 809commands issued without a specified local target filename. 810This command is useful when connecting to a 811.No non\- Ns Ux 812remote computer 813with different file naming conventions or practices. 814The mapping follows the pattern set by 815.Ar inpattern 816and 817.Ar outpattern . 818.Op Ar Inpattern 819is a template for incoming filenames (which may have already been 820processed according to the 821.Ic ntrans 822and 823.Ic case 824settings). 825Variable templating is accomplished by including the 826sequences `$1', `$2', ..., `$9' in 827.Ar inpattern . 828Use `\\' to prevent this special treatment of the `$' character. 829All other characters are treated literally, and are used to determine the 830.Ic nmap 831.Op Ar inpattern 832variable values. 833For example, given 834.Ar inpattern 835$1.$2 and the remote file name "mydata.data", $1 would have the value 836"mydata", and $2 would have the value "data". 837The 838.Ar outpattern 839determines the resulting mapped filename. 840The sequences `$1', `$2', ...., `$9' are replaced by any value resulting 841from the 842.Ar inpattern 843template. 844The sequence `$0' is replace by the original filename. 845Additionally, the sequence 846.Ql Op Ar seq1 , Ar seq2 847is replaced by 848.Op Ar seq1 849if 850.Ar seq1 851is not a null string; otherwise it is replaced by 852.Ar seq2 . 853For example, the command 854.Pp 855.Bd -literal -offset indent -compact 856nmap $1.$2.$3 [$1,$2].[$2,file] 857.Ed 858.Pp 859would yield 860the output filename "myfile.data" for input filenames "myfile.data" and 861"myfile.data.old", "myfile.file" for the input filename "myfile", and 862"myfile.myfile" for the input filename ".myfile". 863Spaces may be included in 864.Ar outpattern , 865as in the example: `nmap $1 sed "s/ *$//" \*[Gt] $1' . 866Use the `\e' character to prevent special treatment 867of the `$','[',']', and `,' characters. 868.It Ic ntrans Op Ar inchars Op Ar outchars 869Set or unset the filename character translation mechanism. 870If no arguments are specified, the filename character 871translation mechanism is unset. 872If arguments are specified, characters in 873remote filenames are translated during 874.Ic mput 875commands and 876.Ic put 877commands issued without a specified remote target filename. 878If arguments are specified, characters in 879local filenames are translated during 880.Ic mget 881commands and 882.Ic get 883commands issued without a specified local target filename. 884This command is useful when connecting to a 885.No non\- Ns Ux 886remote computer 887with different file naming conventions or practices. 888Characters in a filename matching a character in 889.Ar inchars 890are replaced with the corresponding character in 891.Ar outchars . 892If the character's position in 893.Ar inchars 894is longer than the length of 895.Ar outchars , 896the character is deleted from the file name. 897.It Ic open Ar host Op Ar port 898Establish a connection to the specified 899.Ar host 900.Tn FTP 901server. 902An optional port number may be supplied, 903in which case, 904.Nm 905will attempt to contact an 906.Tn FTP 907server at that port. 908If the 909.Ic "set auto-login" 910option is on (default), 911.Nm 912will also attempt to automatically log the user in to 913the 914.Tn FTP 915server (see below). 916.It Ic page Ar file 917Retrieve 918.Ic file 919and display with the program specified by the 920.Ic "set pager" 921option. 922.It Ic passive Op Cm auto 923Toggle passive mode (if no arguments are given). 924If 925.Cm auto 926is given, act as if 927.Ev FTPMODE 928is set to 929.Sq auto . 930If passive mode is turned on (default), 931.Nm 932will send a 933.Dv PASV 934command for all data connections instead of a 935.Dv PORT 936command. 937The 938.Dv PASV 939command requests that the remote server open a port for the data connection 940and return the address of that port. 941The remote server listens on that port and the client connects to it. 942When using the more traditional 943.Dv PORT 944command, the client listens on a port and sends that address to the remote 945server, who connects back to it. 946Passive mode is useful when using 947.Nm 948through a gateway router or host that controls the directionality of 949traffic. 950(Note that though 951.Tn FTP 952servers are required to support the 953.Dv PASV 954command by RFC 1123, some do not.) 955.It Ic pdir Op Ar remote-path 956Perform 957.Ic dir 958.Op Ar remote-path , 959and display the result with the program specified by the 960.Ic "set pager" 961option. 962.It Ic pls Op Ar remote-path 963Perform 964.Ic ls 965.Op Ar remote-path , 966and display the result with the program specified by the 967.Ic "set pager" 968option. 969.It Ic pmlsd Op Ar remote-path 970Perform 971.Ic mlsd 972.Op Ar remote-path , 973and display the result with the program specified by the 974.Ic "set pager" 975option. 976.It Ic preserve 977Toggle preservation of modification times on retrieved files. 978.It Ic progress 979Toggle display of transfer progress bar. 980The progress bar will be disabled for a transfer that has 981.Ar local-file 982as 983.Sq Fl 984or a command that starts with 985.Sq \&| . 986Refer to 987.Sx FILE NAMING CONVENTIONS 988for more information. 989Enabling 990.Ic progress 991disables 992.Ic hash . 993.It Ic prompt 994Toggle interactive prompting. 995Interactive prompting 996occurs during multiple file transfers to allow the 997user to selectively retrieve or store files. 998If prompting is turned off (default is on), any 999.Ic mget 1000or 1001.Ic mput 1002will transfer all files, and any 1003.Ic mdelete 1004will delete all files. 1005.Pp 1006When prompting is on, the following commands are available at a prompt: 1007.Bl -tag -width 2n -offset indent 1008.It Cm a 1009Answer 1010.Sq yes 1011to the current file, and automatically answer 1012.Sq yes 1013to any remaining files for the current command. 1014.It Cm n 1015Answer 1016.Sq no , 1017and do not transfer the file. 1018.It Cm p 1019Answer 1020.Sq yes 1021to the current file, and turn off prompt mode 1022(as is 1023.Dq prompt off 1024had been given). 1025.It Cm q 1026Terminate the current operation. 1027.It Cm y 1028Answer 1029.Sq yes , 1030and transfer the file. 1031.It Cm \&? 1032Display a help message. 1033.El 1034.Pp 1035Any other response will answer 1036.Sq yes 1037to the current file. 1038.It Ic proxy Ar ftp-command 1039Execute an ftp command on a secondary control connection. 1040This command allows simultaneous connection to two remote 1041.Tn FTP 1042servers for transferring files between the two servers. 1043The first 1044.Ic proxy 1045command should be an 1046.Ic open , 1047to establish the secondary control connection. 1048Enter the command "proxy ?" to see other 1049.Tn FTP 1050commands executable on the secondary connection. 1051The following commands behave differently when prefaced by 1052.Ic proxy : 1053.Ic open 1054will not define new macros during the auto-login process, 1055.Ic close 1056will not erase existing macro definitions, 1057.Ic get 1058and 1059.Ic mget 1060transfer files from the host on the primary control connection 1061to the host on the secondary control connection, and 1062.Ic put , 1063.Ic mput , 1064and 1065.Ic append 1066transfer files from the host on the secondary control connection 1067to the host on the primary control connection. 1068Third party file transfers depend upon support of the 1069.Tn FTP 1070protocol 1071.Dv PASV 1072command by the server on the secondary control connection. 1073.It Ic put Ar local-file Op Ar remote-file 1074Store a local file on the remote machine. 1075If 1076.Ar remote-file 1077is left unspecified, the local file name is used 1078after processing according to any 1079.Ic ntrans 1080or 1081.Ic nmap 1082settings 1083in naming the remote file. 1084File transfer uses the 1085current settings for 1086.Ic type , 1087.Ic format , 1088.Ic mode , 1089and 1090.Ic structure . 1091.It Ic pwd 1092Print the name of the current working directory on the remote 1093machine. 1094.It Ic quit 1095A synonym for 1096.Ic bye . 1097.It Ic quote Ar arg1 arg2 ... 1098The arguments specified are sent, verbatim, to the remote 1099.Tn FTP 1100server. 1101.It Xo 1102.Ic rate Ar direction 1103.Op Ar maximum Op Ar increment 1104.Xc 1105Throttle the maximum transfer rate to 1106.Ar maximum 1107bytes/second. 1108If 1109.Ar maximum 1110is 0, disable the throttle. 1111.Pp 1112.Ar direction 1113may be one of: 1114.Bl -tag -width "all" -offset indent -compact 1115.It Cm all 1116Both directions. 1117.It Cm get 1118Incoming transfers. 1119.It Cm put 1120Outgoing transfers. 1121.El 1122.Pp 1123.Ar maximum 1124can by modified on the fly by 1125.Ar increment 1126bytes (default: 1024) each time a given signal is received: 1127.B 1128.Bl -tag -width "SIGUSR1" -offset indent 1129.It Dv SIGUSR1 1130Increment 1131.Ar maximum 1132by 1133.Ar increment 1134bytes. 1135.It Dv SIGUSR2 1136Decrement 1137.Ar maximum 1138by 1139.Ar increment 1140bytes. 1141The result must be a positive number. 1142.El 1143.Pp 1144If 1145.Ar maximum 1146is not supplied, the current throttle rates are displayed. 1147.Pp 1148Note: 1149.Ic rate 1150is not yet implemented for ascii mode transfers. 1151.It Ic rcvbuf Ar size 1152Set the size of the socket receive buffer to 1153.Ar size . 1154.It Ic recv Ar remote-file Op Ar local-file 1155A synonym for 1156.Ic get . 1157.It Ic reget Ar remote-file Op Ar local-file 1158.Ic reget 1159acts like 1160.Ic get , 1161except that if 1162.Ar local-file 1163exists and is 1164smaller than 1165.Ar remote-file , 1166.Ar local-file 1167is presumed to be 1168a partially transferred copy of 1169.Ar remote-file 1170and the transfer 1171is continued from the apparent point of failure. 1172This command 1173is useful when transferring very large files over networks that 1174are prone to dropping connections. 1175.It Ic remopts Ar command Op Ar command-options 1176Set options on the remote 1177.Tn FTP 1178server for 1179.Ar command 1180to 1181.Ar command-options 1182(whose absence is handled on a command-specific basis). 1183Remote 1184.Tn FTP 1185commands known to support options include: 1186.Sq MLST 1187(used for 1188.Dv MLSD 1189and 1190.Dv MLST ) . 1191.It Ic rename Op Ar from Op Ar to 1192Rename the file 1193.Ar from 1194on the remote machine, to the file 1195.Ar to . 1196.It Ic reset 1197Clear reply queue. 1198This command re-synchronizes command/reply sequencing with the remote 1199.Tn FTP 1200server. 1201Resynchronization may be necessary following a violation of the 1202.Tn FTP 1203protocol by the remote server. 1204.It Ic restart Ar marker 1205Restart the immediately following 1206.Ic get 1207or 1208.Ic put 1209at the 1210indicated 1211.Ar marker . 1212On 1213.Ux 1214systems, marker is usually a byte 1215offset into the file. 1216.It Ic rhelp Op Ar command-name 1217Request help from the remote 1218.Tn FTP 1219server. 1220If a 1221.Ar command-name 1222is specified it is supplied to the server as well. 1223.It Ic rmdir Ar directory-name 1224Delete a directory on the remote machine. 1225.It Ic rstatus Op Ar remote-file 1226With no arguments, show status of remote machine. 1227If 1228.Ar remote-file 1229is specified, show status of 1230.Ar remote-file 1231on remote machine. 1232.It Ic runique 1233Toggle storing of files on the local system with unique filenames. 1234If a file already exists with a name equal to the target 1235local filename for a 1236.Ic get 1237or 1238.Ic mget 1239command, a ".1" is appended to the name. 1240If the resulting name matches another existing file, 1241a ".2" is appended to the original name. 1242If this process continues up to ".99", an error 1243message is printed, and the transfer does not take place. 1244The generated unique filename will be reported. 1245Note that 1246.Ic runique 1247will not affect local files generated from a shell command 1248(see below). 1249The default value is off. 1250.It Ic send Ar local-file Op Ar remote-file 1251A synonym for 1252.Ic put . 1253.It Ic sendport 1254Toggle the use of 1255.Dv PORT 1256commands. 1257By default, 1258.Nm 1259will attempt to use a 1260.Dv PORT 1261command when establishing 1262a connection for each data transfer. 1263The use of 1264.Dv PORT 1265commands can prevent delays 1266when performing multiple file transfers. 1267If the 1268.Dv PORT 1269command fails, 1270.Nm 1271will use the default data port. 1272When the use of 1273.Dv PORT 1274commands is disabled, no attempt will be made to use 1275.Dv PORT 1276commands for each data transfer. 1277This is useful 1278for certain 1279.Tn FTP 1280implementations which do ignore 1281.Dv PORT 1282commands but, incorrectly, indicate they've been accepted. 1283.It Ic set Op Ar option Ar value 1284Set 1285.Ar option 1286to 1287.Ar value . 1288If 1289.Ar option 1290and 1291.Ar value 1292are not given, display all of the options and their values. 1293The currently supported options are: 1294.Bl -tag -width "http_proxy" -offset indent 1295.It Cm anonpass 1296Defaults to 1297.Ev $FTPANONPASS 1298.It Cm ftp_proxy 1299Defaults to 1300.Ev $ftp_proxy . 1301.It Cm http_proxy 1302Defaults to 1303.Ev $http_proxy . 1304.It Cm no_proxy 1305Defaults to 1306.Ev $no_proxy . 1307.It Cm pager 1308Defaults to 1309.Ev $PAGER . 1310.It Cm prompt 1311Defaults to 1312.Ev $FTPPROMPT . 1313.It Cm rprompt 1314Defaults to 1315.Ev $FTPRPROMPT . 1316.El 1317.It Ic site Ar arg1 arg2 ... 1318The arguments specified are sent, verbatim, to the remote 1319.Tn FTP 1320server as a 1321.Dv SITE 1322command. 1323.It Ic size Ar remote-file 1324Return size of 1325.Ar remote-file 1326on remote machine. 1327.It Ic sndbuf Ar size 1328Set the size of the socket send buffer to 1329.Ar size . 1330.It Ic status 1331Show the current status of 1332.Nm ftp . 1333.It Ic struct Ar struct-name 1334Set the file transfer 1335.Ar structure 1336to 1337.Ar struct-name . 1338The default (and only supported) 1339structure is 1340.Dq file . 1341.It Ic sunique 1342Toggle storing of files on remote machine under unique file names. 1343The remote 1344.Tn FTP 1345server must support 1346.Tn FTP 1347protocol 1348.Dv STOU 1349command for 1350successful completion. 1351The remote server will report unique name. 1352Default value is off. 1353.It Ic system 1354Show the type of operating system running on the remote machine. 1355.It Ic tenex 1356Set the file transfer type to that needed to 1357talk to 1358.Tn TENEX 1359machines. 1360.It Ic throttle 1361A synonym for 1362.Ic rate . 1363.It Ic trace 1364Toggle packet tracing. 1365.It Ic type Op Ar type-name 1366Set the file transfer 1367.Ic type 1368to 1369.Ar type-name . 1370If no type is specified, the current type 1371is printed. 1372The default type is network 1373.Tn ASCII . 1374.It Ic umask Op Ar newmask 1375Set the default umask on the remote server to 1376.Ar newmask . 1377If 1378.Ar newmask 1379is omitted, the current umask is printed. 1380.It Ic unset Ar option 1381Unset 1382.Ar option . 1383Refer to 1384.Ic set 1385for more information. 1386.It Ic usage Ar command 1387Print the usage message for 1388.Ar command . 1389.It Xo 1390.Ic user Ar user-name 1391.Op Ar password Op Ar account 1392.Xc 1393Identify yourself to the remote 1394.Tn FTP 1395server. 1396If the 1397.Ar password 1398is not specified and the server requires it, 1399.Nm 1400will prompt the user for it (after disabling local echo). 1401If an 1402.Ar account 1403field is not specified, and the 1404.Tn FTP 1405server 1406requires it, the user will be prompted for it. 1407If an 1408.Ar account 1409field is specified, an account command will 1410be relayed to the remote server after the login sequence 1411is completed if the remote server did not require it 1412for logging in. 1413Unless 1414.Nm 1415is invoked with 1416.Dq auto-login 1417disabled, this process is done automatically on initial connection to the 1418.Tn FTP 1419server. 1420.It Ic verbose 1421Toggle verbose mode. 1422In verbose mode, all responses from 1423the 1424.Tn FTP 1425server are displayed to the user. 1426In addition, 1427if verbose is on, when a file transfer completes, statistics 1428regarding the efficiency of the transfer are reported. 1429By default, 1430verbose is on. 1431.It Ic xferbuf Ar size 1432Set the size of the socket send and receive buffers to 1433.Ar size . 1434.It Ic \&? Op Ar command 1435A synonym for 1436.Ic help . 1437.El 1438.Pp 1439Command arguments which have embedded spaces may be quoted with 1440quote `"' marks. 1441.Pp 1442Commands which toggle settings can take an explicit 1443.Ic on 1444or 1445.Ic off 1446argument to force the setting appropriately. 1447.Pp 1448Commands which take a byte count as an argument 1449(e.g., 1450.Ic hash , 1451.Ic rate , 1452and 1453.Ic xferbuf ) 1454support an optional suffix on the argument which changes the 1455interpretation of the argument. 1456Supported suffixes are: 1457.Bl -tag -width 3n -offset indent -compact 1458.It Li b 1459Causes no modification. 1460(Optional) 1461.It Li k 1462Kilo; multiply the argument by 1024 1463.It Li m 1464Mega; multiply the argument by 1048576 1465.It Li g 1466Giga; multiply the argument by 1073741824 1467.El 1468.Pp 1469If 1470.Nm 1471receives a 1472.Dv SIGINFO 1473(see the 1474.Dq status 1475argument of 1476.Xr stty 1 ) 1477or 1478.Dv SIGQUIT 1479signal whilst a transfer is in progress, the current transfer rate 1480statistics will be written to the standard error output, in the 1481same format as the standard completion message. 1482.Sh AUTO-FETCHING FILES 1483In addition to standard commands, this version of 1484.Nm 1485supports an auto-fetch feature. 1486To enable auto-fetch, simply pass the list of hostnames/files 1487on the command line. 1488.Pp 1489The following formats are valid syntax for an auto-fetch element: 1490.Bl -tag -width "FOO " 1491.\" [user@]host:[path][/] 1492.It Xo 1493.Sm off 1494.Op Ar user Li \&@ 1495.Ar host Li \&: 1496.Op Ar path 1497.Op Li / 1498.Sm on 1499.Xc 1500.Dq Classic 1501.Tn FTP 1502format. 1503.Pp 1504If 1505.Ar path 1506contains a glob character and globbing is enabled, 1507(see 1508.Ic glob ) , 1509then the equivalent of 1510.Ql mget path 1511is performed. 1512.Pp 1513If the directory component of 1514.Ar path 1515contains no globbing characters, 1516it is stored locally with the name basename (see 1517.Xr basename 1 ) 1518of 1519.Ic path , 1520in the current directory. 1521Otherwise, the full remote name is used as the local name, 1522relative to the local root directory. 1523.\" ftp://[user[:password]@]host[:port]/path[/][;type=X] 1524.It Xo 1525.Sm off 1526.Li ftp:// 1527.Oo Ar user 1528.Op Li \&: Ar password 1529.Li \&@ Oc 1530.Ar host Oo Li \&: Ar port Oc 1531.Li / Ar path 1532.Op Li / 1533.Op Li ;type= Ar X 1534.Sm on 1535.Xc 1536An 1537.Tn FTP 1538URL, retrieved using the 1539.Tn FTP 1540protocol if 1541.Ic "set ftp_proxy" 1542isn't defined. 1543Otherwise, transfer the URL using 1544.Tn HTTP 1545via the proxy defined in 1546.Ic "set ftp_proxy" . 1547If 1548.Ic "set ftp_proxy" 1549isn't defined and 1550.Ar user 1551is given, login as 1552.Ar user . 1553In this case, use 1554.Ar password 1555if supplied, otherwise prompt the user for one. 1556.Pp 1557If a suffix of 1558.Sq ;type=A 1559or 1560.Sq ;type=I 1561is supplied, then the transfer type will take place as 1562ascii or binary (respectively). 1563The default transfer type is binary. 1564.Pp 1565In order to be compliant with 1566.Cm RFC 1738 , 1567.Nm 1568interprets the 1569.Ar path 1570part of an 1571.Dq ftp:// 1572auto-fetch URL as follows: 1573.Bl -bullet 1574.It 1575The 1576.Sq Li / 1577immediately after the 1578.Ar host Ns Oo Li \&: Ns Ar port Oc 1579is interpreted as a separator before the 1580.Ar path , 1581and not as part of the 1582.Ar path 1583itself. 1584.It 1585The 1586.Ar path 1587is interpreted as a 1588.So Li / Sc Ns -separated 1589list of name components. 1590For all but the last such component, 1591.Nm 1592performs the equivalent of a 1593.Ic cd 1594command. 1595For the last path component, 1596.Nm 1597performs the equivalent of a 1598.Ic get 1599command. 1600.It 1601Empty name components, 1602which result from 1603.Sq Li // 1604within the 1605.Ar path , 1606or from an extra 1607.Sq Li / 1608at the beginning of the 1609.Ar path , 1610will cause the equivalent of a 1611.Ic cd 1612command without a directory name. 1613This is unlikely to be useful. 1614.It 1615Any 1616.Sq Li \&% Ns Ar XX 1617codes within the path components are decoded, with 1618.Ar XX 1619representing a character code in hexadecimal. 1620This decoding takes place after the 1621.Ar path 1622has been split into components, 1623but before each component is used in the equivalent of a 1624.Ic cd 1625or 1626.Ic get 1627command. 1628Some often-used codes are 1629.Sq Li \&%2F 1630(which represents 1631.Sq Li / ) 1632and 1633.Sq Li \&%7E 1634(which represents 1635.Sq Li ~ ) . 1636.El 1637.Pp 1638The above interpretation has the following consequences: 1639.Bl -bullet 1640.It 1641The path is interpreted relative to the 1642default login directory of the specified user or of the 1643.Sq anonymous 1644user. 1645If the 1646.Pa / 1647directory is required, use a leading path of 1648.Dq %2F . 1649If a user's home directory is required (and the remote server supports 1650the syntax), use a leading path of 1651.Dq %7Euser/ . 1652For example, to retrieve 1653.Pa /etc/motd 1654from 1655.Sq localhost 1656as the user 1657.Sq myname 1658with the password 1659.Sq mypass , 1660use 1661.Dq ftp://myname:mypass@localhost/%2fetc/motd 1662.It 1663The exact 1664.Ic cd 1665and 1666.Ic get 1667commands can be controlled by careful choice of 1668where to use 1669.Sq / 1670and where to use 1671.Sq %2F 1672(or 1673.Sq %2f ) . 1674For example, the following URLs correspond to the 1675equivalents of the indicated commands: 1676.Bl -tag -width "ftp://host/%2Fdir1%2Fdir2%2Ffile" 1677.It ftp://host/dir1/dir2/file 1678.Dq "cd dir1" , 1679.Dq "cd dir2" , 1680.Dq "get file" . 1681.It ftp://host/%2Fdir1/dir2/file 1682.Dq "cd /dir1" , 1683.Dq "cd dir2" , 1684.Dq "get file" . 1685.It ftp://host/dir1%2Fdir2/file 1686.Dq "cd dir1/dir2" , 1687.Dq "get file" . 1688.It ftp://host/%2Fdir1%2Fdir2/file 1689.Dq "cd /dir1/dir2" , 1690.Dq "get file" . 1691.It ftp://host/dir1%2Fdir2%2Ffile 1692.Dq "get dir1/dir2/file" . 1693.It ftp://host/%2Fdir1%2Fdir2%2Ffile 1694.Dq "get /dir1/dir2/file" . 1695.El 1696.It 1697You must have appropriate access permission for each of the 1698intermediate directories that is used in the equivalent of a 1699.Ic cd 1700command. 1701.El 1702.\" http://[user[:password]@]host[:port]/path 1703.It Xo 1704.Sm off 1705.Li http:// 1706.Oo Ar user 1707.Op Li \&: Ar password 1708.Li \&@ Oc 1709.Ar host Oo Li \&: Ar port Oc 1710.Li / Ar path 1711.Sm on 1712.Xc 1713An 1714.Tn HTTP 1715URL, retrieved using the 1716.Tn HTTP 1717protocol. 1718If 1719.Ic "set http_proxy" 1720is defined, it is used as a URL to an 1721.Tn HTTP 1722proxy server. 1723If 1724.Tn HTTP 1725authorization is required to retrieve 1726.Ar path , 1727and 1728.Sq user 1729(and optionally 1730.Sq password ) 1731is in the URL, use them for the first attempt to authenticate. 1732.\" file:///path 1733.It Xo 1734.Sm off 1735.Li file:/// Ar path 1736.Sm on 1737.Xc 1738A local URL, copied from 1739.Pa / Ns Ar path 1740on the local host. 1741.El 1742.Pp 1743Unless noted otherwise above, and 1744.Fl o Ar output 1745is not given, the file is stored in the current directory as the 1746.Xr basename 1 1747of 1748.Ar path . 1749.Pp 1750If a classic format or an 1751.Tn FTP 1752URL format has a trailing 1753.Sq / 1754or an empty 1755.Ar path 1756component, then 1757.Nm 1758will connect to the site and 1759.Ic cd 1760to the directory given as the path, and leave the user in interactive 1761mode ready for further input. 1762This will not work if 1763.Ic "set ftp_proxy" 1764is being used. 1765.Pp 1766Direct 1767.Tn HTTP 1768transfers use HTTP 1.1. 1769Proxied 1770.Tn FTP 1771and 1772.Tn HTTP 1773transfers use HTTP 1.0. 1774.Pp 1775If 1776.Fl R 1777is given, all auto-fetches that don't go via the 1778.Tn FTP 1779or 1780.Tn HTTP 1781proxies will be restarted. 1782For 1783.Tn FTP , 1784this is implemented by using 1785.Nm reget 1786instead of 1787.Nm get . 1788For 1789.Tn HTTP , 1790this is implemented by using the 1791.Sq "Range: bytes=" 1792.Tn "HTTP/1.1" 1793directive. 1794.Pp 1795If WWW or proxy WWW authentication is required, you will be prompted 1796to enter a username and password to authenticate with. 1797.Pp 1798When specifying IPv6 numeric addresses in a URL, you need to 1799surround the address in square brackets. 1800E.g.: 1801.Dq ftp://[::1]:21/ . 1802This is because colons are used in IPv6 numeric address as well as 1803being the separator for the port number. 1804.Sh ABORTING A FILE TRANSFER 1805To abort a file transfer, use the terminal interrupt key 1806(usually Ctrl-C). 1807Sending transfers will be immediately halted. 1808Receiving transfers will be halted by sending an 1809.Tn FTP 1810protocol 1811.Dv ABOR 1812command to the remote server, and discarding any further data received. 1813The speed at which this is accomplished depends upon the remote 1814server's support for 1815.Dv ABOR 1816processing. 1817If the remote server does not support the 1818.Dv ABOR 1819command, the prompt will not appear until the remote server has completed 1820sending the requested file. 1821.Pp 1822If the terminal interrupt key sequence is used whilst 1823.Nm 1824is awaiting a reply from the remote server for the ABOR processing, 1825then the connection will be closed. 1826This is different from the traditional behaviour (which ignores the 1827terminal interrupt during this phase), but is considered more useful. 1828.Sh FILE NAMING CONVENTIONS 1829Files specified as arguments to 1830.Nm 1831commands are processed according to the following rules. 1832.Bl -enum 1833.It 1834If the file name 1835.Sq Fl 1836is specified, the 1837.Ar stdin 1838(for reading) or 1839.Ar stdout 1840(for writing) is used. 1841.It 1842If the first character of the file name is 1843.Sq \&| , 1844the 1845remainder of the argument is interpreted as a shell command. 1846.Nm 1847then forks a shell, using 1848.Xr popen 3 1849with the argument supplied, and reads (writes) from the stdout 1850(stdin). 1851If the shell command includes spaces, the argument 1852must be quoted; e.g. 1853.Dq Qq Li \&| ls\ \-lt . 1854A particularly 1855useful example of this mechanism is: 1856.Dq Li dir \&"\&" \&|more . 1857.It 1858Failing the above checks, if ``globbing'' is enabled, 1859local file names are expanded 1860according to the rules used in the 1861.Xr csh 1 ; 1862c.f. the 1863.Ic glob 1864command. 1865If the 1866.Nm 1867command expects a single local file (e.g. 1868.Ic put ) , 1869only the first filename generated by the "globbing" operation is used. 1870.It 1871For 1872.Ic mget 1873commands and 1874.Ic get 1875commands with unspecified local file names, the local filename is 1876the remote filename, which may be altered by a 1877.Ic case , 1878.Ic ntrans , 1879or 1880.Ic nmap 1881setting. 1882The resulting filename may then be altered if 1883.Ic runique 1884is on. 1885.It 1886For 1887.Ic mput 1888commands and 1889.Ic put 1890commands with unspecified remote file names, the remote filename is 1891the local filename, which may be altered by a 1892.Ic ntrans 1893or 1894.Ic nmap 1895setting. 1896The resulting filename may then be altered by the remote server if 1897.Ic sunique 1898is on. 1899.El 1900.Sh FILE TRANSFER PARAMETERS 1901The 1902.Tn FTP 1903specification specifies many parameters which may affect a file transfer. 1904The 1905.Ic type 1906may be one of 1907.Dq ascii , 1908.Dq image 1909(binary), 1910.Dq ebcdic , 1911and 1912.Dq local byte size 1913(for 1914.Tn PDP Ns -10's 1915and 1916.Tn PDP Ns -20's 1917mostly). 1918.Nm 1919supports the ascii and image types of file transfer, 1920plus local byte size 8 for 1921.Ic tenex 1922mode transfers. 1923.Pp 1924.Nm 1925supports only the default values for the remaining 1926file transfer parameters: 1927.Ic mode , 1928.Ic form , 1929and 1930.Ic struct . 1931.Sh THE .netrc FILE 1932The 1933.Pa .netrc 1934file contains login and initialization information 1935used by the auto-login process. 1936It resides in the user's home directory, 1937unless overridden with the 1938.Fl N Ar netrc 1939option, or specified in the 1940.Ev NETRC 1941environment variable. 1942The following tokens are recognized; they may be separated by spaces, 1943tabs, or new-lines: 1944.Bl -tag -width password 1945.It Ic machine Ar name 1946Identify a remote machine 1947.Ar name . 1948The auto-login process searches the 1949.Pa .netrc 1950file for a 1951.Ic machine 1952token that matches the remote machine specified on the 1953.Nm 1954command line or as an 1955.Ic open 1956command argument. 1957Once a match is made, the subsequent 1958.Pa .netrc 1959tokens are processed, 1960stopping when the end of file is reached or another 1961.Ic machine 1962or a 1963.Ic default 1964token is encountered. 1965.It Ic default 1966This is the same as 1967.Ic machine 1968.Ar name 1969except that 1970.Ic default 1971matches any name. 1972There can be only one 1973.Ic default 1974token, and it must be after all 1975.Ic machine 1976tokens. 1977This is normally used as: 1978.Pp 1979.Dl default login anonymous password user@site 1980.Pp 1981thereby giving the user an automatic anonymous 1982.Tn FTP 1983login to 1984machines not specified in 1985.Pa .netrc . 1986This can be overridden 1987by using the 1988.Fl n 1989flag to disable auto-login. 1990.It Ic login Ar name 1991Identify a user on the remote machine. 1992If this token is present, the auto-login process will initiate 1993a login using the specified 1994.Ar name . 1995.It Ic password Ar string 1996Supply a password. 1997If this token is present, the auto-login process will supply the 1998specified string if the remote server requires a password as part 1999of the login process. 2000Note that if this token is present in the 2001.Pa .netrc 2002file for any user other 2003than 2004.Ar anonymous , 2005.Nm 2006will abort the auto-login process if the 2007.Pa .netrc 2008is readable by 2009anyone besides the user. 2010.It Ic account Ar string 2011Supply an additional account password. 2012If this token is present, the auto-login process will supply the 2013specified string if the remote server requires an additional 2014account password, or the auto-login process will initiate an 2015.Dv ACCT 2016command if it does not. 2017.It Ic macdef Ar name 2018Define a macro. 2019This token functions like the 2020.Nm 2021.Ic macdef 2022command functions. 2023A macro is defined with the specified name; its contents begin with the 2024next 2025.Pa .netrc 2026line and continue until a blank line (consecutive new-line 2027characters) is encountered. 2028If a macro named 2029.Ic init 2030is defined, it is automatically executed as the last step in the 2031auto-login process. 2032For example, 2033.Bd -literal -offset indent 2034default 2035macdef init 2036epsv4 off 2037.Ed 2038.Pp 2039followed by a blank line. 2040.El 2041.Sh COMMAND LINE EDITING 2042.Nm 2043supports interactive command line editing, via the 2044.Xr editline 3 2045library. 2046It is enabled with the 2047.Ic edit 2048command, and is enabled by default if input is from a tty. 2049Previous lines can be recalled and edited with the arrow keys, 2050and other GNU Emacs-style editing keys may be used as well. 2051.Pp 2052The 2053.Xr editline 3 2054library is configured with a 2055.Pa .editrc 2056file - refer to 2057.Xr editrc 5 2058for more information. 2059.Pp 2060An extra key binding is available to 2061.Nm 2062to provide context sensitive command and filename completion 2063(including remote file completion). 2064To use this, bind a key to the 2065.Xr editline 3 2066command 2067.Ic ftp-complete . 2068By default, this is bound to the TAB key. 2069.Sh COMMAND LINE PROMPT 2070By default, 2071.Nm 2072displays a command line prompt of 2073.Dq "ftp\*[Gt] " 2074to the user. 2075This can be changed with the 2076.Ic "set prompt" 2077command. 2078.Pp 2079A prompt can be displayed on the right side of the screen (after the 2080command input) with the 2081.Ic "set rprompt" 2082command. 2083.Pp 2084The following formatting sequences are replaced by the given 2085information: 2086.Bl -tag -width "%% " -offset indent 2087.It Li \&%/ 2088The current remote working directory. 2089.\" %c[[0]n], %.[[0]n] 2090.It Xo 2091.Sm off 2092.Li \&%c 2093.Op Oo Li 0 Oc Ar n Ns , 2094.Li \&%. 2095.Op Oo Li 0 Oc Ar n 2096.Sm on 2097.Xc 2098The trailing component of the current remote working directory, or 2099.Em n 2100trailing components if a digit 2101.Em n 2102is given. 2103If 2104.Em n 2105begins with 2106.Sq 0 , 2107the number of skipped components precede the trailing component(s) in 2108the format 2109.\" ``/<number>trailing'' 2110.Do 2111.Sm off 2112.Li / Li \*[Lt] Va number Li \*[Gt] 2113.Va trailing 2114.Sm on 2115.Dc 2116(for 2117.Sq \&%c ) 2118or 2119.\" ``...trailing'' 2120.Dq Li \&... Ns Va trailing 2121(for 2122.Sq \&%. ) . 2123.It Li \&%M 2124The remote host name. 2125.It Li \&%m 2126The remote host name, up to the first 2127.Sq \&. . 2128.It Li \&%n 2129The remote user name. 2130.It Li \&%% 2131A single 2132.Sq % . 2133.El 2134.Sh ENVIRONMENT 2135.Nm 2136uses the following environment variables. 2137.Bl -tag -width "FTPSERVERPORT" 2138.It Ev FTPANONPASS 2139Password to send in an anonymous 2140.Tn FTP 2141transfer. 2142Defaults to 2143.Dq Li `whoami`@ . 2144.It Ev FTPMODE 2145Overrides the default operation mode. 2146Support values are: 2147.Bl -tag -width "passive" 2148.It Cm active 2149active mode 2150.Tn FTP 2151only 2152.It Cm auto 2153automatic determination of passive or active (this is the default) 2154.It Cm gate 2155gate-ftp mode 2156.It Cm passive 2157passive mode 2158.Tn FTP 2159only 2160.El 2161.It Ev FTPPROMPT 2162Command-line prompt to use. 2163Defaults to 2164.Dq "ftp\*[Gt] " . 2165Refer to 2166.Sx COMMAND LINE PROMPT 2167for more information. 2168.It Ev FTPRPROMPT 2169Command-line right side prompt to use. 2170Defaults to 2171.Dq "" . 2172Refer to 2173.Sx COMMAND LINE PROMPT 2174for more information. 2175.It Ev FTPSERVER 2176Host to use as gate-ftp server when 2177.Ic gate 2178is enabled. 2179.It Ev FTPSERVERPORT 2180Port to use when connecting to gate-ftp server when 2181.Ic gate 2182is enabled. 2183Default is port returned by a 2184.Fn getservbyname 2185lookup of 2186.Dq ftpgate/tcp . 2187.It Ev FTPUSERAGENT 2188The value to send for the 2189.Tn HTTP 2190User-Agent 2191header. 2192.It Ev HOME 2193For default location of a 2194.Pa .netrc 2195file, if one exists. 2196.It Ev NETRC 2197An alternate location of the 2198.Pa .netrc 2199file. 2200.It Ev PAGER 2201Used by various commands to display files. 2202Defaults to 2203.Xr more 1 2204if empty or not set. 2205.It Ev SHELL 2206For default shell. 2207.It Ev ftp_proxy 2208URL of 2209.Tn FTP 2210proxy to use when making 2211.Tn FTP 2212URL requests 2213(if not defined, use the standard 2214.Tn FTP 2215protocol). 2216.Pp 2217.Em NOTE : 2218this is not used for interactive sessions, only for command-line 2219fetches. 2220.It Ev http_proxy 2221URL of 2222.Tn HTTP 2223proxy to use when making 2224.Tn HTTP 2225URL requests. 2226If proxy authentication is required and there is a username and 2227password in this URL, they will automatically be used in the first 2228attempt to authenticate to the proxy. 2229.Pp 2230Note that the use of a username and password in 2231.Ev ftp_proxy 2232and 2233.Ev http_proxy 2234may be incompatible with other programs that use it 2235(such as 2236.Xr lynx 1 ) . 2237.Pp 2238.Em NOTE : 2239this is not used for interactive sessions, only for command-line 2240fetches. 2241.It Ev no_proxy 2242A space or comma separated list of hosts (or domains) for which 2243proxying is not to be used. 2244Each entry may have an optional trailing ":port", which restricts 2245the matching to connections to that port. 2246.El 2247.Sh EXTENDED PASSIVE MODE AND FIREWALLS 2248Some firewall configurations do not allow 2249.Nm 2250to use extended passive mode. 2251If you find that even a simple 2252.Ic ls 2253appears to hang after printing a message such as this: 2254.Pp 2255.Dl 229 Entering Extended Passive Mode (|||58551|) 2256.Pp 2257then you will need to disable extended passive mode with 2258.Ic epsv4 off . 2259See the above section 2260.Sx The .netrc File 2261for an example of how to make this automatic. 2262.Sh SEE ALSO 2263.Xr getservbyname 3 , 2264.Xr editrc 5 , 2265.Xr services 5 , 2266.Xr ftpd 8 2267.Sh STANDARDS 2268.Nm 2269attempts to be compliant with 2270.Cm RFC 959 , 2271.Cm RFC 1123 , 2272.Cm RFC 1738 , 2273.Cm RFC 2068 , 2274.Cm RFC 2389 , 2275.Cm RFC 2428 , 2276.Cm RFC 2732 , 2277and 2278.Cm draft-ietf-ftpext-mlst-11 . 2279.Sh HISTORY 2280The 2281.Nm 2282command appeared in 2283.Bx 4.2 . 2284.Pp 2285Various features such as command line editing, context sensitive 2286command and file completion, dynamic progress bar, automatic 2287fetching of files and URLs, modification time preservation, 2288transfer rate throttling, configurable command line prompt, 2289and other enhancements over the standard 2290.Bx 2291.Nm 2292were implemented in 2293.Nx 1.3 2294and later releases 2295by 2296.An Luke Mewburn 2297.Aq lukem@NetBSD.org . 2298.Pp 2299IPv6 support was added by the WIDE/KAME project 2300(but may not be present in all non-NetBSD versions of this program, depending 2301if the operating system supports IPv6 in a similar manner to KAME). 2302.Sh BUGS 2303Correct execution of many commands depends upon proper behavior 2304by the remote server. 2305.Pp 2306An error in the treatment of carriage returns 2307in the 2308.Bx 4.2 2309ascii-mode transfer code 2310has been corrected. 2311This correction may result in incorrect transfers of binary files 2312to and from 2313.Bx 4.2 2314servers using the ascii type. 2315Avoid this problem by using the binary image type. 2316.Pp 2317.Nm 2318assumes that all IPv4 mapped addresses 2319.Po 2320IPv6 addresses with a form like 2321.Li ::ffff:10.1.1.1 2322.Pc 2323indicate IPv4 destinations which can be handled by 2324.Dv AF_INET 2325sockets. 2326However, in certain IPv6 network configurations, this assumption is not true. 2327In such an environment, IPv4 mapped addresses must be passed to 2328.Dv AF_INET6 2329sockets directly. 2330For example, if your site uses a SIIT translator for IPv6-to-IPv4 translation, 2331.Nm 2332is unable to support your configuration. 2333