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