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