1.\" $NetBSD: ftp.1,v 1.108 2005/01/15 21:28:16 lukem Exp $ 2.\" 3.\" Copyright (c) 1996-2004 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 January 15, 2005 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 955.Cm RFC 1123 , 956some do not.) 957.It Ic pdir Op Ar remote-path 958Perform 959.Ic dir 960.Op Ar remote-path , 961and display the result with the program specified by the 962.Ic "set pager" 963option. 964.It Ic pls Op Ar remote-path 965Perform 966.Ic ls 967.Op Ar remote-path , 968and display the result with the program specified by the 969.Ic "set pager" 970option. 971.It Ic pmlsd Op Ar remote-path 972Perform 973.Ic mlsd 974.Op Ar remote-path , 975and display the result with the program specified by the 976.Ic "set pager" 977option. 978.It Ic preserve 979Toggle preservation of modification times on retrieved files. 980.It Ic progress 981Toggle display of transfer progress bar. 982The progress bar will be disabled for a transfer that has 983.Ar local-file 984as 985.Sq Fl 986or a command that starts with 987.Sq \&| . 988Refer to 989.Sx FILE NAMING CONVENTIONS 990for more information. 991Enabling 992.Ic progress 993disables 994.Ic hash . 995.It Ic prompt 996Toggle interactive prompting. 997Interactive prompting 998occurs during multiple file transfers to allow the 999user to selectively retrieve or store files. 1000If prompting is turned off (default is on), any 1001.Ic mget 1002or 1003.Ic mput 1004will transfer all files, and any 1005.Ic mdelete 1006will delete all files. 1007.Pp 1008When prompting is on, the following commands are available at a prompt: 1009.Bl -tag -width 2n -offset indent 1010.It Cm a 1011Answer 1012.Sq yes 1013to the current file, and automatically answer 1014.Sq yes 1015to any remaining files for the current command. 1016.It Cm n 1017Answer 1018.Sq no , 1019and do not transfer the file. 1020.It Cm p 1021Answer 1022.Sq yes 1023to the current file, and turn off prompt mode 1024(as is 1025.Dq prompt off 1026had been given). 1027.It Cm q 1028Terminate the current operation. 1029.It Cm y 1030Answer 1031.Sq yes , 1032and transfer the file. 1033.It Cm \&? 1034Display a help message. 1035.El 1036.Pp 1037Any other response will answer 1038.Sq yes 1039to the current file. 1040.It Ic proxy Ar ftp-command 1041Execute an ftp command on a secondary control connection. 1042This command allows simultaneous connection to two remote 1043.Tn FTP 1044servers for transferring files between the two servers. 1045The first 1046.Ic proxy 1047command should be an 1048.Ic open , 1049to establish the secondary control connection. 1050Enter the command "proxy ?" to see other 1051.Tn FTP 1052commands executable on the secondary connection. 1053The following commands behave differently when prefaced by 1054.Ic proxy : 1055.Ic open 1056will not define new macros during the auto-login process, 1057.Ic close 1058will not erase existing macro definitions, 1059.Ic get 1060and 1061.Ic mget 1062transfer files from the host on the primary control connection 1063to the host on the secondary control connection, and 1064.Ic put , 1065.Ic mput , 1066and 1067.Ic append 1068transfer files from the host on the secondary control connection 1069to the host on the primary control connection. 1070Third party file transfers depend upon support of the 1071.Tn FTP 1072protocol 1073.Dv PASV 1074command by the server on the secondary control connection. 1075.It Ic put Ar local-file Op Ar remote-file 1076Store a local file on the remote machine. 1077If 1078.Ar remote-file 1079is left unspecified, the local file name is used 1080after processing according to any 1081.Ic ntrans 1082or 1083.Ic nmap 1084settings 1085in naming the remote file. 1086File transfer uses the 1087current settings for 1088.Ic type , 1089.Ic format , 1090.Ic mode , 1091and 1092.Ic structure . 1093.It Ic pwd 1094Print the name of the current working directory on the remote 1095machine. 1096.It Ic quit 1097A synonym for 1098.Ic bye . 1099.It Ic quote Ar arg1 arg2 ... 1100The arguments specified are sent, verbatim, to the remote 1101.Tn FTP 1102server. 1103.It Xo 1104.Ic rate Ar direction 1105.Op Ar maximum Op Ar increment 1106.Xc 1107Throttle the maximum transfer rate to 1108.Ar maximum 1109bytes/second. 1110If 1111.Ar maximum 1112is 0, disable the throttle. 1113.Pp 1114.Ar direction 1115may be one of: 1116.Bl -tag -width "all" -offset indent -compact 1117.It Cm all 1118Both directions. 1119.It Cm get 1120Incoming transfers. 1121.It Cm put 1122Outgoing transfers. 1123.El 1124.Pp 1125.Ar maximum 1126can be modified on the fly by 1127.Ar increment 1128bytes (default: 1024) each time a given signal is received: 1129.B 1130.Bl -tag -width "SIGUSR1" -offset indent 1131.It Dv SIGUSR1 1132Increment 1133.Ar maximum 1134by 1135.Ar increment 1136bytes. 1137.It Dv SIGUSR2 1138Decrement 1139.Ar maximum 1140by 1141.Ar increment 1142bytes. 1143The result must be a positive number. 1144.El 1145.Pp 1146If 1147.Ar maximum 1148is not supplied, the current throttle rates are displayed. 1149.Pp 1150Note: 1151.Ic rate 1152is not yet implemented for ascii mode transfers. 1153.It Ic rcvbuf Ar size 1154Set the size of the socket receive buffer to 1155.Ar size . 1156.It Ic recv Ar remote-file Op Ar local-file 1157A synonym for 1158.Ic get . 1159.It Ic reget Ar remote-file Op Ar local-file 1160.Ic reget 1161acts like 1162.Ic get , 1163except that if 1164.Ar local-file 1165exists and is 1166smaller than 1167.Ar remote-file , 1168.Ar local-file 1169is presumed to be 1170a partially transferred copy of 1171.Ar remote-file 1172and the transfer 1173is continued from the apparent point of failure. 1174This command 1175is useful when transferring very large files over networks that 1176are prone to dropping connections. 1177.It Ic remopts Ar command Op Ar command-options 1178Set options on the remote 1179.Tn FTP 1180server for 1181.Ar command 1182to 1183.Ar command-options 1184(whose absence is handled on a command-specific basis). 1185Remote 1186.Tn FTP 1187commands known to support options include: 1188.Sq MLST 1189(used for 1190.Dv MLSD 1191and 1192.Dv MLST ) . 1193.It Ic rename Op Ar from Op Ar to 1194Rename the file 1195.Ar from 1196on the remote machine, to the file 1197.Ar to . 1198.It Ic reset 1199Clear reply queue. 1200This command re-synchronizes command/reply sequencing with the remote 1201.Tn FTP 1202server. 1203Resynchronization may be necessary following a violation of the 1204.Tn FTP 1205protocol by the remote server. 1206.It Ic restart Ar marker 1207Restart the immediately following 1208.Ic get 1209or 1210.Ic put 1211at the 1212indicated 1213.Ar marker . 1214On 1215.Ux 1216systems, marker is usually a byte 1217offset into the file. 1218.It Ic rhelp Op Ar command-name 1219Request help from the remote 1220.Tn FTP 1221server. 1222If a 1223.Ar command-name 1224is specified it is supplied to the server as well. 1225.It Ic rmdir Ar directory-name 1226Delete a directory on the remote machine. 1227.It Ic rstatus Op Ar remote-file 1228With no arguments, show status of remote machine. 1229If 1230.Ar remote-file 1231is specified, show status of 1232.Ar remote-file 1233on remote machine. 1234.It Ic runique 1235Toggle storing of files on the local system with unique filenames. 1236If a file already exists with a name equal to the target 1237local filename for a 1238.Ic get 1239or 1240.Ic mget 1241command, a ".1" is appended to the name. 1242If the resulting name matches another existing file, 1243a ".2" is appended to the original name. 1244If this process continues up to ".99", an error 1245message is printed, and the transfer does not take place. 1246The generated unique filename will be reported. 1247Note that 1248.Ic runique 1249will not affect local files generated from a shell command 1250(see below). 1251The default value is off. 1252.It Ic send Ar local-file Op Ar remote-file 1253A synonym for 1254.Ic put . 1255.It Ic sendport 1256Toggle the use of 1257.Dv PORT 1258commands. 1259By default, 1260.Nm 1261will attempt to use a 1262.Dv PORT 1263command when establishing 1264a connection for each data transfer. 1265The use of 1266.Dv PORT 1267commands can prevent delays 1268when performing multiple file transfers. 1269If the 1270.Dv PORT 1271command fails, 1272.Nm 1273will use the default data port. 1274When the use of 1275.Dv PORT 1276commands is disabled, no attempt will be made to use 1277.Dv PORT 1278commands for each data transfer. 1279This is useful 1280for certain 1281.Tn FTP 1282implementations which do ignore 1283.Dv PORT 1284commands but, incorrectly, indicate they've been accepted. 1285.It Ic set Op Ar option Ar value 1286Set 1287.Ar option 1288to 1289.Ar value . 1290If 1291.Ar option 1292and 1293.Ar value 1294are not given, display all of the options and their values. 1295The currently supported options are: 1296.Bl -tag -width "http_proxy" -offset indent 1297.It Cm anonpass 1298Defaults to 1299.Ev $FTPANONPASS 1300.It Cm ftp_proxy 1301Defaults to 1302.Ev $ftp_proxy . 1303.It Cm http_proxy 1304Defaults to 1305.Ev $http_proxy . 1306.It Cm no_proxy 1307Defaults to 1308.Ev $no_proxy . 1309.It Cm pager 1310Defaults to 1311.Ev $PAGER . 1312.It Cm prompt 1313Defaults to 1314.Ev $FTPPROMPT . 1315.It Cm rprompt 1316Defaults to 1317.Ev $FTPRPROMPT . 1318.El 1319.It Ic site Ar arg1 arg2 ... 1320The arguments specified are sent, verbatim, to the remote 1321.Tn FTP 1322server as a 1323.Dv SITE 1324command. 1325.It Ic size Ar remote-file 1326Return size of 1327.Ar remote-file 1328on remote machine. 1329.It Ic sndbuf Ar size 1330Set the size of the socket send buffer to 1331.Ar size . 1332.It Ic status 1333Show the current status of 1334.Nm ftp . 1335.It Ic struct Ar struct-name 1336Set the file transfer 1337.Ar structure 1338to 1339.Ar struct-name . 1340The default (and only supported) 1341structure is 1342.Dq file . 1343.It Ic sunique 1344Toggle storing of files on remote machine under unique file names. 1345The remote 1346.Tn FTP 1347server must support 1348.Tn FTP 1349protocol 1350.Dv STOU 1351command for 1352successful completion. 1353The remote server will report unique name. 1354Default value is off. 1355.It Ic system 1356Show the type of operating system running on the remote machine. 1357.It Ic tenex 1358Set the file transfer type to that needed to 1359talk to 1360.Tn TENEX 1361machines. 1362.It Ic throttle 1363A synonym for 1364.Ic rate . 1365.It Ic trace 1366Toggle packet tracing. 1367.It Ic type Op Ar type-name 1368Set the file transfer 1369.Ic type 1370to 1371.Ar type-name . 1372If no type is specified, the current type 1373is printed. 1374The default type is network 1375.Tn ASCII . 1376.It Ic umask Op Ar newmask 1377Set the default umask on the remote server to 1378.Ar newmask . 1379If 1380.Ar newmask 1381is omitted, the current umask is printed. 1382.It Ic unset Ar option 1383Unset 1384.Ar option . 1385Refer to 1386.Ic set 1387for more information. 1388.It Ic usage Ar command 1389Print the usage message for 1390.Ar command . 1391.It Xo 1392.Ic user Ar user-name 1393.Op Ar password Op Ar account 1394.Xc 1395Identify yourself to the remote 1396.Tn FTP 1397server. 1398If the 1399.Ar password 1400is not specified and the server requires it, 1401.Nm 1402will prompt the user for it (after disabling local echo). 1403If an 1404.Ar account 1405field is not specified, and the 1406.Tn FTP 1407server 1408requires it, the user will be prompted for it. 1409If an 1410.Ar account 1411field is specified, an account command will 1412be relayed to the remote server after the login sequence 1413is completed if the remote server did not require it 1414for logging in. 1415Unless 1416.Nm 1417is invoked with 1418.Dq auto-login 1419disabled, this process is done automatically on initial connection to the 1420.Tn FTP 1421server. 1422.It Ic verbose 1423Toggle verbose mode. 1424In verbose mode, all responses from 1425the 1426.Tn FTP 1427server are displayed to the user. 1428In addition, 1429if verbose is on, when a file transfer completes, statistics 1430regarding the efficiency of the transfer are reported. 1431By default, 1432verbose is on. 1433.It Ic xferbuf Ar size 1434Set the size of the socket send and receive buffers to 1435.Ar size . 1436.It Ic \&? Op Ar command 1437A synonym for 1438.Ic help . 1439.El 1440.Pp 1441Command arguments which have embedded spaces may be quoted with 1442quote `"' marks. 1443.Pp 1444Commands which toggle settings can take an explicit 1445.Ic on 1446or 1447.Ic off 1448argument to force the setting appropriately. 1449.Pp 1450Commands which take a byte count as an argument 1451(e.g., 1452.Ic hash , 1453.Ic rate , 1454and 1455.Ic xferbuf ) 1456support an optional suffix on the argument which changes the 1457interpretation of the argument. 1458Supported suffixes are: 1459.Bl -tag -width 3n -offset indent -compact 1460.It Li b 1461Causes no modification. 1462(Optional) 1463.It Li k 1464Kilo; multiply the argument by 1024 1465.It Li m 1466Mega; multiply the argument by 1048576 1467.It Li g 1468Giga; multiply the argument by 1073741824 1469.El 1470.Pp 1471If 1472.Nm 1473receives a 1474.Dv SIGINFO 1475(see the 1476.Dq status 1477argument of 1478.Xr stty 1 ) 1479or 1480.Dv SIGQUIT 1481signal whilst a transfer is in progress, the current transfer rate 1482statistics will be written to the standard error output, in the 1483same format as the standard completion message. 1484.Sh AUTO-FETCHING FILES 1485In addition to standard commands, this version of 1486.Nm 1487supports an auto-fetch feature. 1488To enable auto-fetch, simply pass the list of hostnames/files 1489on the command line. 1490.Pp 1491The following formats are valid syntax for an auto-fetch element: 1492.Bl -tag -width "FOO " 1493.\" [user@]host:[path][/] 1494.It Xo 1495.Sm off 1496.Op Ar user Li \&@ 1497.Ar host Li \&: 1498.Op Ar path 1499.Op Li / 1500.Sm on 1501.Xc 1502.Dq Classic 1503.Tn FTP 1504format. 1505.Pp 1506If 1507.Ar path 1508contains a glob character and globbing is enabled, 1509(see 1510.Ic glob ) , 1511then the equivalent of 1512.Ql mget path 1513is performed. 1514.Pp 1515If the directory component of 1516.Ar path 1517contains no globbing characters, 1518it is stored locally with the name basename (see 1519.Xr basename 1 ) 1520of 1521.Ic path , 1522in the current directory. 1523Otherwise, the full remote name is used as the local name, 1524relative to the local root directory. 1525.\" ftp://[user[:password]@]host[:port]/path[/][;type=X] 1526.It Xo 1527.Sm off 1528.Li ftp:// 1529.Oo Ar user 1530.Op Li \&: Ar password 1531.Li \&@ Oc 1532.Ar host Oo Li \&: Ar port Oc 1533.Li / Ar path 1534.Op Li / 1535.Op Li ;type= Ar X 1536.Sm on 1537.Xc 1538An 1539.Tn FTP 1540URL, retrieved using the 1541.Tn FTP 1542protocol if 1543.Ic "set ftp_proxy" 1544isn't defined. 1545Otherwise, transfer the URL using 1546.Tn HTTP 1547via the proxy defined in 1548.Ic "set ftp_proxy" . 1549If 1550.Ic "set ftp_proxy" 1551isn't defined and 1552.Ar user 1553is given, login as 1554.Ar user . 1555In this case, use 1556.Ar password 1557if supplied, otherwise prompt the user for one. 1558.Pp 1559If a suffix of 1560.Sq ;type=A 1561or 1562.Sq ;type=I 1563is supplied, then the transfer type will take place as 1564ascii or binary (respectively). 1565The default transfer type is binary. 1566.Pp 1567In order to be compliant with 1568.Cm RFC 1738 , 1569.Nm 1570interprets the 1571.Ar path 1572part of an 1573.Dq ftp:// 1574auto-fetch URL as follows: 1575.Bl -bullet 1576.It 1577The 1578.Sq Li / 1579immediately after the 1580.Ar host Ns Oo Li \&: Ns Ar port Oc 1581is interpreted as a separator before the 1582.Ar path , 1583and not as part of the 1584.Ar path 1585itself. 1586.It 1587The 1588.Ar path 1589is interpreted as a 1590.So Li / Sc Ns -separated 1591list of name components. 1592For all but the last such component, 1593.Nm 1594performs the equivalent of a 1595.Ic cd 1596command. 1597For the last path component, 1598.Nm 1599performs the equivalent of a 1600.Ic get 1601command. 1602.It 1603Empty name components, 1604which result from 1605.Sq Li // 1606within the 1607.Ar path , 1608or from an extra 1609.Sq Li / 1610at the beginning of the 1611.Ar path , 1612will cause the equivalent of a 1613.Ic cd 1614command without a directory name. 1615This is unlikely to be useful. 1616.It 1617Any 1618.Sq Li \&% Ns Ar XX 1619codes 1620(per 1621.Cm RFC 1738 ) 1622within the path components are decoded, with 1623.Ar XX 1624representing a character code in hexadecimal. 1625This decoding takes place after the 1626.Ar path 1627has been split into components, 1628but before each component is used in the equivalent of a 1629.Ic cd 1630or 1631.Ic get 1632command. 1633Some often-used codes are 1634.Sq Li \&%2F 1635(which represents 1636.Sq Li / ) 1637and 1638.Sq Li \&%7E 1639(which represents 1640.Sq Li ~ ) . 1641.El 1642.Pp 1643The above interpretation has the following consequences: 1644.Bl -bullet 1645.It 1646The path is interpreted relative to the 1647default login directory of the specified user or of the 1648.Sq anonymous 1649user. 1650If the 1651.Pa / 1652directory is required, use a leading path of 1653.Dq %2F . 1654If a user's home directory is required (and the remote server supports 1655the syntax), use a leading path of 1656.Dq %7Euser/ . 1657For example, to retrieve 1658.Pa /etc/motd 1659from 1660.Sq localhost 1661as the user 1662.Sq myname 1663with the password 1664.Sq mypass , 1665use 1666.Dq ftp://myname:mypass@localhost/%2fetc/motd 1667.It 1668The exact 1669.Ic cd 1670and 1671.Ic get 1672commands can be controlled by careful choice of 1673where to use 1674.Sq / 1675and where to use 1676.Sq %2F 1677(or 1678.Sq %2f ) . 1679For example, the following URLs correspond to the 1680equivalents of the indicated commands: 1681.Bl -tag -width "ftp://host/%2Fdir1%2Fdir2%2Ffile" 1682.It ftp://host/dir1/dir2/file 1683.Dq "cd dir1" , 1684.Dq "cd dir2" , 1685.Dq "get file" . 1686.It ftp://host/%2Fdir1/dir2/file 1687.Dq "cd /dir1" , 1688.Dq "cd dir2" , 1689.Dq "get file" . 1690.It ftp://host/dir1%2Fdir2/file 1691.Dq "cd dir1/dir2" , 1692.Dq "get file" . 1693.It ftp://host/%2Fdir1%2Fdir2/file 1694.Dq "cd /dir1/dir2" , 1695.Dq "get file" . 1696.It ftp://host/dir1%2Fdir2%2Ffile 1697.Dq "get dir1/dir2/file" . 1698.It ftp://host/%2Fdir1%2Fdir2%2Ffile 1699.Dq "get /dir1/dir2/file" . 1700.El 1701.It 1702You must have appropriate access permission for each of the 1703intermediate directories that is used in the equivalent of a 1704.Ic cd 1705command. 1706.El 1707.\" http://[user[:password]@]host[:port]/path 1708.It Xo 1709.Sm off 1710.Li http:// 1711.Oo Ar user 1712.Op Li \&: Ar password 1713.Li \&@ Oc 1714.Ar host Oo Li \&: Ar port Oc 1715.Li / Ar path 1716.Sm on 1717.Xc 1718An 1719.Tn HTTP 1720URL, retrieved using the 1721.Tn HTTP 1722protocol. 1723If 1724.Ic "set http_proxy" 1725is defined, it is used as a URL to an 1726.Tn HTTP 1727proxy server. 1728If 1729.Tn HTTP 1730authorization is required to retrieve 1731.Ar path , 1732and 1733.Sq user 1734(and optionally 1735.Sq password ) 1736is in the URL, use them for the first attempt to authenticate. 1737.\" file:///path 1738.It Xo 1739.Sm off 1740.Li file:/// Ar path 1741.Sm on 1742.Xc 1743A local URL, copied from 1744.Pa / Ns Ar path 1745on the local host. 1746.El 1747.Pp 1748Unless noted otherwise above, and 1749.Fl o Ar output 1750is not given, the file is stored in the current directory as the 1751.Xr basename 1 1752of 1753.Ar path . 1754Note that if a 1755.Tn HTTP 1756redirect is received, the fetch is retried using the new target URL 1757supplied by the server, with a corresponding new 1758.Ar path . 1759Using an explicit 1760.Fl o Ar output 1761is recommended, to avoid writing to unexpected file names. 1762.Pp 1763If a classic format or an 1764.Tn FTP 1765URL format has a trailing 1766.Sq / 1767or an empty 1768.Ar path 1769component, then 1770.Nm 1771will connect to the site and 1772.Ic cd 1773to the directory given as the path, and leave the user in interactive 1774mode ready for further input. 1775This will not work if 1776.Ic "set ftp_proxy" 1777is being used. 1778.Pp 1779Direct 1780.Tn HTTP 1781transfers use HTTP 1.1. 1782Proxied 1783.Tn FTP 1784and 1785.Tn HTTP 1786transfers use HTTP 1.0. 1787.Pp 1788If 1789.Fl R 1790is given, all auto-fetches that don't go via the 1791.Tn FTP 1792or 1793.Tn HTTP 1794proxies will be restarted. 1795For 1796.Tn FTP , 1797this is implemented by using 1798.Nm reget 1799instead of 1800.Nm get . 1801For 1802.Tn HTTP , 1803this is implemented by using the 1804.Sq "Range: bytes=" 1805.Tn "HTTP/1.1" 1806directive. 1807.Pp 1808If WWW or proxy WWW authentication is required, you will be prompted 1809to enter a username and password to authenticate with. 1810.Pp 1811When specifying IPv6 numeric addresses in a URL, you need to 1812surround the address in square brackets. 1813E.g.: 1814.Dq ftp://[::1]:21/ . 1815This is because colons are used in IPv6 numeric address as well as 1816being the separator for the port number. 1817.Sh ABORTING A FILE TRANSFER 1818To abort a file transfer, use the terminal interrupt key 1819(usually Ctrl-C). 1820Sending transfers will be immediately halted. 1821Receiving transfers will be halted by sending an 1822.Tn FTP 1823protocol 1824.Dv ABOR 1825command to the remote server, and discarding any further data received. 1826The speed at which this is accomplished depends upon the remote 1827server's support for 1828.Dv ABOR 1829processing. 1830If the remote server does not support the 1831.Dv ABOR 1832command, the prompt will not appear until the remote server has completed 1833sending the requested file. 1834.Pp 1835If the terminal interrupt key sequence is used whilst 1836.Nm 1837is awaiting a reply from the remote server for the ABOR processing, 1838then the connection will be closed. 1839This is different from the traditional behaviour (which ignores the 1840terminal interrupt during this phase), but is considered more useful. 1841.Sh FILE NAMING CONVENTIONS 1842Files specified as arguments to 1843.Nm 1844commands are processed according to the following rules. 1845.Bl -enum 1846.It 1847If the file name 1848.Sq Fl 1849is specified, the 1850.Ar stdin 1851(for reading) or 1852.Ar stdout 1853(for writing) is used. 1854.It 1855If the first character of the file name is 1856.Sq \&| , 1857the 1858remainder of the argument is interpreted as a shell command. 1859.Nm 1860then forks a shell, using 1861.Xr popen 3 1862with the argument supplied, and reads (writes) from the stdout 1863(stdin). 1864If the shell command includes spaces, the argument 1865must be quoted; e.g. 1866.Dq Qq Li \&| ls\ \-lt . 1867A particularly 1868useful example of this mechanism is: 1869.Dq Li dir \&"\&" \&|more . 1870.It 1871Failing the above checks, if ``globbing'' is enabled, 1872local file names are expanded 1873according to the rules used in the 1874.Xr csh 1 ; 1875c.f. the 1876.Ic glob 1877command. 1878If the 1879.Nm 1880command expects a single local file (e.g. 1881.Ic put ) , 1882only the first filename generated by the "globbing" operation is used. 1883.It 1884For 1885.Ic mget 1886commands and 1887.Ic get 1888commands with unspecified local file names, the local filename is 1889the remote filename, which may be altered by a 1890.Ic case , 1891.Ic ntrans , 1892or 1893.Ic nmap 1894setting. 1895The resulting filename may then be altered if 1896.Ic runique 1897is on. 1898.It 1899For 1900.Ic mput 1901commands and 1902.Ic put 1903commands with unspecified remote file names, the remote filename is 1904the local filename, which may be altered by a 1905.Ic ntrans 1906or 1907.Ic nmap 1908setting. 1909The resulting filename may then be altered by the remote server if 1910.Ic sunique 1911is on. 1912.El 1913.Sh FILE TRANSFER PARAMETERS 1914The 1915.Tn FTP 1916specification specifies many parameters which may affect a file transfer. 1917The 1918.Ic type 1919may be one of 1920.Dq ascii , 1921.Dq image 1922(binary), 1923.Dq ebcdic , 1924and 1925.Dq local byte size 1926(for 1927.Tn PDP Ns -10's 1928and 1929.Tn PDP Ns -20's 1930mostly). 1931.Nm 1932supports the ascii and image types of file transfer, 1933plus local byte size 8 for 1934.Ic tenex 1935mode transfers. 1936.Pp 1937.Nm 1938supports only the default values for the remaining 1939file transfer parameters: 1940.Ic mode , 1941.Ic form , 1942and 1943.Ic struct . 1944.Sh THE .netrc FILE 1945The 1946.Pa .netrc 1947file contains login and initialization information 1948used by the auto-login process. 1949It resides in the user's home directory, 1950unless overridden with the 1951.Fl N Ar netrc 1952option, or specified in the 1953.Ev NETRC 1954environment variable. 1955The following tokens are recognized; they may be separated by spaces, 1956tabs, or new-lines: 1957.Bl -tag -width password 1958.It Ic machine Ar name 1959Identify a remote machine 1960.Ar name . 1961The auto-login process searches the 1962.Pa .netrc 1963file for a 1964.Ic machine 1965token that matches the remote machine specified on the 1966.Nm 1967command line or as an 1968.Ic open 1969command argument. 1970Once a match is made, the subsequent 1971.Pa .netrc 1972tokens are processed, 1973stopping when the end of file is reached or another 1974.Ic machine 1975or a 1976.Ic default 1977token is encountered. 1978.It Ic default 1979This is the same as 1980.Ic machine 1981.Ar name 1982except that 1983.Ic default 1984matches any name. 1985There can be only one 1986.Ic default 1987token, and it must be after all 1988.Ic machine 1989tokens. 1990This is normally used as: 1991.Pp 1992.Dl default login anonymous password user@site 1993.Pp 1994thereby giving the user an automatic anonymous 1995.Tn FTP 1996login to 1997machines not specified in 1998.Pa .netrc . 1999This can be overridden 2000by using the 2001.Fl n 2002flag to disable auto-login. 2003.It Ic login Ar name 2004Identify a user on the remote machine. 2005If this token is present, the auto-login process will initiate 2006a login using the specified 2007.Ar name . 2008.It Ic password Ar string 2009Supply a password. 2010If this token is present, the auto-login process will supply the 2011specified string if the remote server requires a password as part 2012of the login process. 2013Note that if this token is present in the 2014.Pa .netrc 2015file for any user other 2016than 2017.Ar anonymous , 2018.Nm 2019will abort the auto-login process if the 2020.Pa .netrc 2021is readable by 2022anyone besides the user. 2023.It Ic account Ar string 2024Supply an additional account password. 2025If this token is present, the auto-login process will supply the 2026specified string if the remote server requires an additional 2027account password, or the auto-login process will initiate an 2028.Dv ACCT 2029command if it does not. 2030.It Ic macdef Ar name 2031Define a macro. 2032This token functions like the 2033.Nm 2034.Ic macdef 2035command functions. 2036A macro is defined with the specified name; its contents begin with the 2037next 2038.Pa .netrc 2039line and continue until a blank line (consecutive new-line 2040characters) is encountered. 2041If a macro named 2042.Ic init 2043is defined, it is automatically executed as the last step in the 2044auto-login process. 2045For example, 2046.Bd -literal -offset indent 2047default 2048macdef init 2049epsv4 off 2050.Ed 2051.Pp 2052followed by a blank line. 2053.El 2054.Sh COMMAND LINE EDITING 2055.Nm 2056supports interactive command line editing, via the 2057.Xr editline 3 2058library. 2059It is enabled with the 2060.Ic edit 2061command, and is enabled by default if input is from a tty. 2062Previous lines can be recalled and edited with the arrow keys, 2063and other GNU Emacs-style editing keys may be used as well. 2064.Pp 2065The 2066.Xr editline 3 2067library is configured with a 2068.Pa .editrc 2069file - refer to 2070.Xr editrc 5 2071for more information. 2072.Pp 2073An extra key binding is available to 2074.Nm 2075to provide context sensitive command and filename completion 2076(including remote file completion). 2077To use this, bind a key to the 2078.Xr editline 3 2079command 2080.Ic ftp-complete . 2081By default, this is bound to the TAB key. 2082.Sh COMMAND LINE PROMPT 2083By default, 2084.Nm 2085displays a command line prompt of 2086.Dq "ftp\*[Gt] " 2087to the user. 2088This can be changed with the 2089.Ic "set prompt" 2090command. 2091.Pp 2092A prompt can be displayed on the right side of the screen (after the 2093command input) with the 2094.Ic "set rprompt" 2095command. 2096.Pp 2097The following formatting sequences are replaced by the given 2098information: 2099.Bl -tag -width "%% " -offset indent 2100.It Li \&%/ 2101The current remote working directory. 2102.\" %c[[0]n], %.[[0]n] 2103.It Xo 2104.Sm off 2105.Li \&%c 2106.Op Oo Li 0 Oc Ar n Ns , 2107.Li \&%. 2108.Op Oo Li 0 Oc Ar n 2109.Sm on 2110.Xc 2111The trailing component of the current remote working directory, or 2112.Em n 2113trailing components if a digit 2114.Em n 2115is given. 2116If 2117.Em n 2118begins with 2119.Sq 0 , 2120the number of skipped components precede the trailing component(s) in 2121the format 2122.\" ``/<number>trailing'' 2123.Do 2124.Sm off 2125.Li / Li \*[Lt] Va number Li \*[Gt] 2126.Va trailing 2127.Sm on 2128.Dc 2129(for 2130.Sq \&%c ) 2131or 2132.\" ``...trailing'' 2133.Dq Li \&... Ns Va trailing 2134(for 2135.Sq \&%. ) . 2136.It Li \&%M 2137The remote host name. 2138.It Li \&%m 2139The remote host name, up to the first 2140.Sq \&. . 2141.It Li \&%n 2142The remote user name. 2143.It Li \&%% 2144A single 2145.Sq % . 2146.El 2147.Sh ENVIRONMENT 2148.Nm 2149uses the following environment variables. 2150.Bl -tag -width "FTPSERVERPORT" 2151.It Ev FTPANONPASS 2152Password to send in an anonymous 2153.Tn FTP 2154transfer. 2155Defaults to 2156.Dq Li `whoami`@ . 2157.It Ev FTPMODE 2158Overrides the default operation mode. 2159Support values are: 2160.Bl -tag -width "passive" 2161.It Cm active 2162active mode 2163.Tn FTP 2164only 2165.It Cm auto 2166automatic determination of passive or active (this is the default) 2167.It Cm gate 2168gate-ftp mode 2169.It Cm passive 2170passive mode 2171.Tn FTP 2172only 2173.El 2174.It Ev FTPPROMPT 2175Command-line prompt to use. 2176Defaults to 2177.Dq "ftp\*[Gt] " . 2178Refer to 2179.Sx COMMAND LINE PROMPT 2180for more information. 2181.It Ev FTPRPROMPT 2182Command-line right side prompt to use. 2183Defaults to 2184.Dq "" . 2185Refer to 2186.Sx COMMAND LINE PROMPT 2187for more information. 2188.It Ev FTPSERVER 2189Host to use as gate-ftp server when 2190.Ic gate 2191is enabled. 2192.It Ev FTPSERVERPORT 2193Port to use when connecting to gate-ftp server when 2194.Ic gate 2195is enabled. 2196Default is port returned by a 2197.Fn getservbyname 2198lookup of 2199.Dq ftpgate/tcp . 2200.It Ev FTPUSERAGENT 2201The value to send for the 2202.Tn HTTP 2203User-Agent 2204header. 2205.It Ev HOME 2206For default location of a 2207.Pa .netrc 2208file, if one exists. 2209.It Ev NETRC 2210An alternate location of the 2211.Pa .netrc 2212file. 2213.It Ev PAGER 2214Used by various commands to display files. 2215Defaults to 2216.Xr more 1 2217if empty or not set. 2218.It Ev SHELL 2219For default shell. 2220.It Ev ftp_proxy 2221URL of 2222.Tn FTP 2223proxy to use when making 2224.Tn FTP 2225URL requests 2226(if not defined, use the standard 2227.Tn FTP 2228protocol). 2229.Pp 2230See 2231.Ev http_proxy 2232for further notes about proxy use. 2233.It Ev http_proxy 2234URL of 2235.Tn HTTP 2236proxy to use when making 2237.Tn HTTP 2238URL requests. 2239If proxy authentication is required and there is a username and 2240password in this URL, they will automatically be used in the first 2241attempt to authenticate to the proxy. 2242.Pp 2243If 2244.Dq unsafe 2245URL characters are required in the username or password 2246(for example 2247.Sq @ 2248or 2249.Sq / ) , 2250encode them with 2251.Cm RFC 1738 2252.Sq Li \&% Ns Ar XX 2253encoding. 2254.Pp 2255Note that the use of a username and password in 2256.Ev ftp_proxy 2257and 2258.Ev http_proxy 2259may be incompatible with other programs that use it 2260(such as 2261.Xr lynx 1 ) . 2262.Pp 2263.Em NOTE : 2264this is not used for interactive sessions, only for command-line 2265fetches. 2266.It Ev no_proxy 2267A space or comma separated list of hosts (or domains) for which 2268proxying is not to be used. 2269Each entry may have an optional trailing ":port", which restricts 2270the matching to connections to that port. 2271.El 2272.Sh EXTENDED PASSIVE MODE AND FIREWALLS 2273Some firewall configurations do not allow 2274.Nm 2275to use extended passive mode. 2276If you find that even a simple 2277.Ic ls 2278appears to hang after printing a message such as this: 2279.Pp 2280.Dl 229 Entering Extended Passive Mode (|||58551|) 2281.Pp 2282then you will need to disable extended passive mode with 2283.Ic epsv4 off . 2284See the above section 2285.Sx The .netrc File 2286for an example of how to make this automatic. 2287.Sh SEE ALSO 2288.Xr getservbyname 3 , 2289.Xr editrc 5 , 2290.Xr services 5 , 2291.Xr ftpd 8 2292.Sh STANDARDS 2293.Nm 2294attempts to be compliant with 2295.Cm RFC 959 , 2296.Cm RFC 1123 , 2297.Cm RFC 1738 , 2298.Cm RFC 2068 , 2299.Cm RFC 2389 , 2300.Cm RFC 2428 , 2301.Cm RFC 2732 , 2302and 2303.Cm draft-ietf-ftpext-mlst-11 . 2304.Sh HISTORY 2305The 2306.Nm 2307command appeared in 2308.Bx 4.2 . 2309.Pp 2310Various features such as command line editing, context sensitive 2311command and file completion, dynamic progress bar, automatic 2312fetching of files and URLs, modification time preservation, 2313transfer rate throttling, configurable command line prompt, 2314and other enhancements over the standard 2315.Bx 2316.Nm 2317were implemented in 2318.Nx 1.3 2319and later releases 2320by 2321.An Luke Mewburn 2322.Aq lukem@NetBSD.org . 2323.Pp 2324IPv6 support was added by the WIDE/KAME project 2325(but may not be present in all non-NetBSD versions of this program, depending 2326if the operating system supports IPv6 in a similar manner to KAME). 2327.Sh BUGS 2328Correct execution of many commands depends upon proper behavior 2329by the remote server. 2330.Pp 2331An error in the treatment of carriage returns 2332in the 2333.Bx 4.2 2334ascii-mode transfer code 2335has been corrected. 2336This correction may result in incorrect transfers of binary files 2337to and from 2338.Bx 4.2 2339servers using the ascii type. 2340Avoid this problem by using the binary image type. 2341.Pp 2342.Nm 2343assumes that all IPv4 mapped addresses 2344.Po 2345IPv6 addresses with a form like 2346.Li ::ffff:10.1.1.1 2347.Pc 2348indicate IPv4 destinations which can be handled by 2349.Dv AF_INET 2350sockets. 2351However, in certain IPv6 network configurations, this assumption is not true. 2352In such an environment, IPv4 mapped addresses must be passed to 2353.Dv AF_INET6 2354sockets directly. 2355For example, if your site uses a SIIT translator for IPv6-to-IPv4 translation, 2356.Nm 2357is unable to support your configuration. 2358