1.\" $NetBSD: ftp.1,v 1.105 2004/12/01 12:03:55 wiz 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 October 7, 2004 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 be 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 . 1749Note that if a 1750.Tn HTTP 1751redirect is received, the fetch is retried using the new target URL 1752supplied by the server, with a corresponding new 1753.Ar path . 1754Using an explicit 1755.Fl o Ar output 1756is recommended, to avoid writing to unexpected file names. 1757.Pp 1758If a classic format or an 1759.Tn FTP 1760URL format has a trailing 1761.Sq / 1762or an empty 1763.Ar path 1764component, then 1765.Nm 1766will connect to the site and 1767.Ic cd 1768to the directory given as the path, and leave the user in interactive 1769mode ready for further input. 1770This will not work if 1771.Ic "set ftp_proxy" 1772is being used. 1773.Pp 1774Direct 1775.Tn HTTP 1776transfers use HTTP 1.1. 1777Proxied 1778.Tn FTP 1779and 1780.Tn HTTP 1781transfers use HTTP 1.0. 1782.Pp 1783If 1784.Fl R 1785is given, all auto-fetches that don't go via the 1786.Tn FTP 1787or 1788.Tn HTTP 1789proxies will be restarted. 1790For 1791.Tn FTP , 1792this is implemented by using 1793.Nm reget 1794instead of 1795.Nm get . 1796For 1797.Tn HTTP , 1798this is implemented by using the 1799.Sq "Range: bytes=" 1800.Tn "HTTP/1.1" 1801directive. 1802.Pp 1803If WWW or proxy WWW authentication is required, you will be prompted 1804to enter a username and password to authenticate with. 1805.Pp 1806When specifying IPv6 numeric addresses in a URL, you need to 1807surround the address in square brackets. 1808E.g.: 1809.Dq ftp://[::1]:21/ . 1810This is because colons are used in IPv6 numeric address as well as 1811being the separator for the port number. 1812.Sh ABORTING A FILE TRANSFER 1813To abort a file transfer, use the terminal interrupt key 1814(usually Ctrl-C). 1815Sending transfers will be immediately halted. 1816Receiving transfers will be halted by sending an 1817.Tn FTP 1818protocol 1819.Dv ABOR 1820command to the remote server, and discarding any further data received. 1821The speed at which this is accomplished depends upon the remote 1822server's support for 1823.Dv ABOR 1824processing. 1825If the remote server does not support the 1826.Dv ABOR 1827command, the prompt will not appear until the remote server has completed 1828sending the requested file. 1829.Pp 1830If the terminal interrupt key sequence is used whilst 1831.Nm 1832is awaiting a reply from the remote server for the ABOR processing, 1833then the connection will be closed. 1834This is different from the traditional behaviour (which ignores the 1835terminal interrupt during this phase), but is considered more useful. 1836.Sh FILE NAMING CONVENTIONS 1837Files specified as arguments to 1838.Nm 1839commands are processed according to the following rules. 1840.Bl -enum 1841.It 1842If the file name 1843.Sq Fl 1844is specified, the 1845.Ar stdin 1846(for reading) or 1847.Ar stdout 1848(for writing) is used. 1849.It 1850If the first character of the file name is 1851.Sq \&| , 1852the 1853remainder of the argument is interpreted as a shell command. 1854.Nm 1855then forks a shell, using 1856.Xr popen 3 1857with the argument supplied, and reads (writes) from the stdout 1858(stdin). 1859If the shell command includes spaces, the argument 1860must be quoted; e.g. 1861.Dq Qq Li \&| ls\ \-lt . 1862A particularly 1863useful example of this mechanism is: 1864.Dq Li dir \&"\&" \&|more . 1865.It 1866Failing the above checks, if ``globbing'' is enabled, 1867local file names are expanded 1868according to the rules used in the 1869.Xr csh 1 ; 1870c.f. the 1871.Ic glob 1872command. 1873If the 1874.Nm 1875command expects a single local file (e.g. 1876.Ic put ) , 1877only the first filename generated by the "globbing" operation is used. 1878.It 1879For 1880.Ic mget 1881commands and 1882.Ic get 1883commands with unspecified local file names, the local filename is 1884the remote filename, which may be altered by a 1885.Ic case , 1886.Ic ntrans , 1887or 1888.Ic nmap 1889setting. 1890The resulting filename may then be altered if 1891.Ic runique 1892is on. 1893.It 1894For 1895.Ic mput 1896commands and 1897.Ic put 1898commands with unspecified remote file names, the remote filename is 1899the local filename, which may be altered by a 1900.Ic ntrans 1901or 1902.Ic nmap 1903setting. 1904The resulting filename may then be altered by the remote server if 1905.Ic sunique 1906is on. 1907.El 1908.Sh FILE TRANSFER PARAMETERS 1909The 1910.Tn FTP 1911specification specifies many parameters which may affect a file transfer. 1912The 1913.Ic type 1914may be one of 1915.Dq ascii , 1916.Dq image 1917(binary), 1918.Dq ebcdic , 1919and 1920.Dq local byte size 1921(for 1922.Tn PDP Ns -10's 1923and 1924.Tn PDP Ns -20's 1925mostly). 1926.Nm 1927supports the ascii and image types of file transfer, 1928plus local byte size 8 for 1929.Ic tenex 1930mode transfers. 1931.Pp 1932.Nm 1933supports only the default values for the remaining 1934file transfer parameters: 1935.Ic mode , 1936.Ic form , 1937and 1938.Ic struct . 1939.Sh THE .netrc FILE 1940The 1941.Pa .netrc 1942file contains login and initialization information 1943used by the auto-login process. 1944It resides in the user's home directory, 1945unless overridden with the 1946.Fl N Ar netrc 1947option, or specified in the 1948.Ev NETRC 1949environment variable. 1950The following tokens are recognized; they may be separated by spaces, 1951tabs, or new-lines: 1952.Bl -tag -width password 1953.It Ic machine Ar name 1954Identify a remote machine 1955.Ar name . 1956The auto-login process searches the 1957.Pa .netrc 1958file for a 1959.Ic machine 1960token that matches the remote machine specified on the 1961.Nm 1962command line or as an 1963.Ic open 1964command argument. 1965Once a match is made, the subsequent 1966.Pa .netrc 1967tokens are processed, 1968stopping when the end of file is reached or another 1969.Ic machine 1970or a 1971.Ic default 1972token is encountered. 1973.It Ic default 1974This is the same as 1975.Ic machine 1976.Ar name 1977except that 1978.Ic default 1979matches any name. 1980There can be only one 1981.Ic default 1982token, and it must be after all 1983.Ic machine 1984tokens. 1985This is normally used as: 1986.Pp 1987.Dl default login anonymous password user@site 1988.Pp 1989thereby giving the user an automatic anonymous 1990.Tn FTP 1991login to 1992machines not specified in 1993.Pa .netrc . 1994This can be overridden 1995by using the 1996.Fl n 1997flag to disable auto-login. 1998.It Ic login Ar name 1999Identify a user on the remote machine. 2000If this token is present, the auto-login process will initiate 2001a login using the specified 2002.Ar name . 2003.It Ic password Ar string 2004Supply a password. 2005If this token is present, the auto-login process will supply the 2006specified string if the remote server requires a password as part 2007of the login process. 2008Note that if this token is present in the 2009.Pa .netrc 2010file for any user other 2011than 2012.Ar anonymous , 2013.Nm 2014will abort the auto-login process if the 2015.Pa .netrc 2016is readable by 2017anyone besides the user. 2018.It Ic account Ar string 2019Supply an additional account password. 2020If this token is present, the auto-login process will supply the 2021specified string if the remote server requires an additional 2022account password, or the auto-login process will initiate an 2023.Dv ACCT 2024command if it does not. 2025.It Ic macdef Ar name 2026Define a macro. 2027This token functions like the 2028.Nm 2029.Ic macdef 2030command functions. 2031A macro is defined with the specified name; its contents begin with the 2032next 2033.Pa .netrc 2034line and continue until a blank line (consecutive new-line 2035characters) is encountered. 2036If a macro named 2037.Ic init 2038is defined, it is automatically executed as the last step in the 2039auto-login process. 2040For example, 2041.Bd -literal -offset indent 2042default 2043macdef init 2044epsv4 off 2045.Ed 2046.Pp 2047followed by a blank line. 2048.El 2049.Sh COMMAND LINE EDITING 2050.Nm 2051supports interactive command line editing, via the 2052.Xr editline 3 2053library. 2054It is enabled with the 2055.Ic edit 2056command, and is enabled by default if input is from a tty. 2057Previous lines can be recalled and edited with the arrow keys, 2058and other GNU Emacs-style editing keys may be used as well. 2059.Pp 2060The 2061.Xr editline 3 2062library is configured with a 2063.Pa .editrc 2064file - refer to 2065.Xr editrc 5 2066for more information. 2067.Pp 2068An extra key binding is available to 2069.Nm 2070to provide context sensitive command and filename completion 2071(including remote file completion). 2072To use this, bind a key to the 2073.Xr editline 3 2074command 2075.Ic ftp-complete . 2076By default, this is bound to the TAB key. 2077.Sh COMMAND LINE PROMPT 2078By default, 2079.Nm 2080displays a command line prompt of 2081.Dq "ftp\*[Gt] " 2082to the user. 2083This can be changed with the 2084.Ic "set prompt" 2085command. 2086.Pp 2087A prompt can be displayed on the right side of the screen (after the 2088command input) with the 2089.Ic "set rprompt" 2090command. 2091.Pp 2092The following formatting sequences are replaced by the given 2093information: 2094.Bl -tag -width "%% " -offset indent 2095.It Li \&%/ 2096The current remote working directory. 2097.\" %c[[0]n], %.[[0]n] 2098.It Xo 2099.Sm off 2100.Li \&%c 2101.Op Oo Li 0 Oc Ar n Ns , 2102.Li \&%. 2103.Op Oo Li 0 Oc Ar n 2104.Sm on 2105.Xc 2106The trailing component of the current remote working directory, or 2107.Em n 2108trailing components if a digit 2109.Em n 2110is given. 2111If 2112.Em n 2113begins with 2114.Sq 0 , 2115the number of skipped components precede the trailing component(s) in 2116the format 2117.\" ``/<number>trailing'' 2118.Do 2119.Sm off 2120.Li / Li \*[Lt] Va number Li \*[Gt] 2121.Va trailing 2122.Sm on 2123.Dc 2124(for 2125.Sq \&%c ) 2126or 2127.\" ``...trailing'' 2128.Dq Li \&... Ns Va trailing 2129(for 2130.Sq \&%. ) . 2131.It Li \&%M 2132The remote host name. 2133.It Li \&%m 2134The remote host name, up to the first 2135.Sq \&. . 2136.It Li \&%n 2137The remote user name. 2138.It Li \&%% 2139A single 2140.Sq % . 2141.El 2142.Sh ENVIRONMENT 2143.Nm 2144uses the following environment variables. 2145.Bl -tag -width "FTPSERVERPORT" 2146.It Ev FTPANONPASS 2147Password to send in an anonymous 2148.Tn FTP 2149transfer. 2150Defaults to 2151.Dq Li `whoami`@ . 2152.It Ev FTPMODE 2153Overrides the default operation mode. 2154Support values are: 2155.Bl -tag -width "passive" 2156.It Cm active 2157active mode 2158.Tn FTP 2159only 2160.It Cm auto 2161automatic determination of passive or active (this is the default) 2162.It Cm gate 2163gate-ftp mode 2164.It Cm passive 2165passive mode 2166.Tn FTP 2167only 2168.El 2169.It Ev FTPPROMPT 2170Command-line prompt to use. 2171Defaults to 2172.Dq "ftp\*[Gt] " . 2173Refer to 2174.Sx COMMAND LINE PROMPT 2175for more information. 2176.It Ev FTPRPROMPT 2177Command-line right side prompt to use. 2178Defaults to 2179.Dq "" . 2180Refer to 2181.Sx COMMAND LINE PROMPT 2182for more information. 2183.It Ev FTPSERVER 2184Host to use as gate-ftp server when 2185.Ic gate 2186is enabled. 2187.It Ev FTPSERVERPORT 2188Port to use when connecting to gate-ftp server when 2189.Ic gate 2190is enabled. 2191Default is port returned by a 2192.Fn getservbyname 2193lookup of 2194.Dq ftpgate/tcp . 2195.It Ev FTPUSERAGENT 2196The value to send for the 2197.Tn HTTP 2198User-Agent 2199header. 2200.It Ev HOME 2201For default location of a 2202.Pa .netrc 2203file, if one exists. 2204.It Ev NETRC 2205An alternate location of the 2206.Pa .netrc 2207file. 2208.It Ev PAGER 2209Used by various commands to display files. 2210Defaults to 2211.Xr more 1 2212if empty or not set. 2213.It Ev SHELL 2214For default shell. 2215.It Ev ftp_proxy 2216URL of 2217.Tn FTP 2218proxy to use when making 2219.Tn FTP 2220URL requests 2221(if not defined, use the standard 2222.Tn FTP 2223protocol). 2224.Pp 2225.Em NOTE : 2226this is not used for interactive sessions, only for command-line 2227fetches. 2228.It Ev http_proxy 2229URL of 2230.Tn HTTP 2231proxy to use when making 2232.Tn HTTP 2233URL requests. 2234If proxy authentication is required and there is a username and 2235password in this URL, they will automatically be used in the first 2236attempt to authenticate to the proxy. 2237.Pp 2238Note that the use of a username and password in 2239.Ev ftp_proxy 2240and 2241.Ev http_proxy 2242may be incompatible with other programs that use it 2243(such as 2244.Xr lynx 1 ) . 2245.Pp 2246.Em NOTE : 2247this is not used for interactive sessions, only for command-line 2248fetches. 2249.It Ev no_proxy 2250A space or comma separated list of hosts (or domains) for which 2251proxying is not to be used. 2252Each entry may have an optional trailing ":port", which restricts 2253the matching to connections to that port. 2254.El 2255.Sh EXTENDED PASSIVE MODE AND FIREWALLS 2256Some firewall configurations do not allow 2257.Nm 2258to use extended passive mode. 2259If you find that even a simple 2260.Ic ls 2261appears to hang after printing a message such as this: 2262.Pp 2263.Dl 229 Entering Extended Passive Mode (|||58551|) 2264.Pp 2265then you will need to disable extended passive mode with 2266.Ic epsv4 off . 2267See the above section 2268.Sx The .netrc File 2269for an example of how to make this automatic. 2270.Sh SEE ALSO 2271.Xr getservbyname 3 , 2272.Xr editrc 5 , 2273.Xr services 5 , 2274.Xr ftpd 8 2275.Sh STANDARDS 2276.Nm 2277attempts to be compliant with 2278.Cm RFC 959 , 2279.Cm RFC 1123 , 2280.Cm RFC 1738 , 2281.Cm RFC 2068 , 2282.Cm RFC 2389 , 2283.Cm RFC 2428 , 2284.Cm RFC 2732 , 2285and 2286.Cm draft-ietf-ftpext-mlst-11 . 2287.Sh HISTORY 2288The 2289.Nm 2290command appeared in 2291.Bx 4.2 . 2292.Pp 2293Various features such as command line editing, context sensitive 2294command and file completion, dynamic progress bar, automatic 2295fetching of files and URLs, modification time preservation, 2296transfer rate throttling, configurable command line prompt, 2297and other enhancements over the standard 2298.Bx 2299.Nm 2300were implemented in 2301.Nx 1.3 2302and later releases 2303by 2304.An Luke Mewburn 2305.Aq lukem@NetBSD.org . 2306.Pp 2307IPv6 support was added by the WIDE/KAME project 2308(but may not be present in all non-NetBSD versions of this program, depending 2309if the operating system supports IPv6 in a similar manner to KAME). 2310.Sh BUGS 2311Correct execution of many commands depends upon proper behavior 2312by the remote server. 2313.Pp 2314An error in the treatment of carriage returns 2315in the 2316.Bx 4.2 2317ascii-mode transfer code 2318has been corrected. 2319This correction may result in incorrect transfers of binary files 2320to and from 2321.Bx 4.2 2322servers using the ascii type. 2323Avoid this problem by using the binary image type. 2324.Pp 2325.Nm 2326assumes that all IPv4 mapped addresses 2327.Po 2328IPv6 addresses with a form like 2329.Li ::ffff:10.1.1.1 2330.Pc 2331indicate IPv4 destinations which can be handled by 2332.Dv AF_INET 2333sockets. 2334However, in certain IPv6 network configurations, this assumption is not true. 2335In such an environment, IPv4 mapped addresses must be passed to 2336.Dv AF_INET6 2337sockets directly. 2338For example, if your site uses a SIIT translator for IPv6-to-IPv4 translation, 2339.Nm 2340is unable to support your configuration. 2341