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