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