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