1.\"- 2.\" Copyright (c) 2000-2004 Dag-Erling Co�dan Sm�rgrav 3.\" All rights reserved. 4.\" Portions Copyright (c) 1999 Massachusetts Institute of Technology; used 5.\" by permission. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer 12.\" in this position and unchanged. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the author may not be used to endorse or promote products 17.\" derived from this software without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 20.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 21.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 22.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 24.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 28.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd March 11, 2003 33.Dt FETCH 1 34.Os 35.Sh NAME 36.Nm fetch 37.Nd retrieve a file by Uniform Resource Locator 38.Sh SYNOPSIS 39.Nm 40.Op Fl 146AFMPRUadlmnpqrsv 41.Op Fl B Ar bytes 42.Op Fl S Ar bytes 43.Op Fl T Ar seconds 44.Op Fl N Ar file 45.Op Fl o Ar file 46.Op Fl w Ar seconds 47.Op Fl h Ar host 48.Op Fl c Ar dir 49.Op Fl f Ar file 50.Op Ar URL ... 51.Sh DESCRIPTION 52The 53.Nm 54utility provides a command-line interface to the 55.Xr fetch 3 56library. 57Its purpose is to retrieve the file(s) pointed to by the URL(s) on the 58command line. 59.Pp 60The following options are available: 61.Bl -tag -width Fl 62.It Fl \&1 63Stop and return exit code 0 at the first successfully retrieved file. 64.It Fl 4 65Forces 66.Nm 67to use IPv4 addresses only. 68.It Fl 6 69Forces 70.Nm 71to use IPv6 addresses only. 72.It Fl A 73Do not automatically follow ``temporary'' (302) redirects. 74Some broken Web sites will return a redirect instead of a not-found 75error when the requested object does not exist. 76.It Fl a 77Automatically retry the transfer upon soft failures. 78.It Fl B Ar bytes 79Specify the read buffer size in bytes. 80The default is 4096 bytes. 81Attempts to set a buffer size lower than this will be silently 82ignored. 83The number of reads actually performed is reported at verbosity level 84two or higher (see the 85.Fl v 86flag). 87.It Fl c Ar dir 88The file to retrieve is in directory 89.Ar dir 90on the remote host. 91This option is deprecated and is provided for backward compatibility 92only. 93.It Fl d 94Use a direct connection even if a proxy is configured. 95.It Fl F 96In combination with the 97.Fl r 98flag, forces a restart even if the local and remote files have 99different modification times. 100Implies 101.Fl R . 102.It Fl f Ar file 103The file to retrieve is named 104.Ar file 105on the remote host. 106This option is deprecated and is provided for backward compatibility 107only. 108.It Fl h Ar host 109The file to retrieve is located on the host 110.Ar host . 111This option is deprecated and is provided for backward compatibility 112only. 113.It Fl l 114If the target is a file-scheme URL, make a symbolic link to the target 115rather than trying to copy it. 116.It Fl M 117.It Fl m 118Mirror mode: if the file already exists locally and has the same size 119and modification time as the remote file, it will not be fetched. 120Note that the 121.Fl m 122and 123.Fl r 124flags are mutually exclusive. 125.It Fl N Ar file 126Use 127.Ar file 128instead of 129.Pa ~/.netrc 130to look up login names and passwords for FTP sites. 131See 132.Xr ftp 1 133for a description of the file format. 134This feature is experimental. 135.It Fl n 136Do not preserve the modification time of the transferred file. 137.It Fl o Ar file 138Set the output file name to 139.Ar file . 140By default, a ``pathname'' is extracted from the specified URI, and 141its basename is used as the name of the output file. 142A 143.Ar file 144argument of 145.Sq Li \&- 146indicates that results are to be directed to the standard output. 147If the 148.Ar file 149argument is a directory, fetched file(s) will be placed within the 150directory, with name(s) selected as in the default behaviour. 151.It Fl P 152.It Fl p 153Use passive FTP. 154This is useful if you are behind a firewall which blocks incoming 155connections. 156Try this flag if 157.Nm 158seems to hang when retrieving FTP URLs. 159.It Fl q 160Quiet mode. 161.It Fl R 162The output files are precious, and should not be deleted under any 163circumstances, even if the transfer failed or was incomplete. 164.It Fl r 165Restart a previously interrupted transfer. 166Note that the 167.Fl m 168and 169.Fl r 170flags are mutually exclusive. 171.It Fl S Ar bytes 172Require the file size reported by the server to match the specified 173value. 174If it does not, a message is printed and the file is not fetched. 175If the server does not support reporting file sizes, this option is 176ignored and the file is fetched unconditionally. 177.It Fl s 178Print the size in bytes of each requested file, without fetching it. 179.It Fl T Ar seconds 180Set timeout value to 181.Ar seconds . 182Overrides the environment variables 183.Ev FTP_TIMEOUT 184for FTP transfers or 185.Ev HTTP_TIMEOUT 186for HTTP transfers if set. 187.It Fl U 188When using passive FTP, allocate the port for the data connection from 189the low (default) port range. 190See 191.Xr ip 4 192for details on how to specify which port range this corresponds to. 193.It Fl v 194Increase verbosity level. 195.It Fl w Ar seconds 196When the 197.Fl a 198flag is specified, wait this many seconds between successive retries. 199.El 200.Pp 201If 202.Nm 203receives a 204.Dv SIGINFO 205signal (see the 206.Cm status 207argument for 208.Xr stty 1 ) , 209the current transfer rate statistics will be written to the 210standard error output, in the same format as the standard completion 211message. 212.Sh ENVIRONMENT 213.Bl -tag -width HTTP_TIMEOUT 214.It Ev FTP_TIMEOUT 215Maximum time, in seconds, to wait before aborting an FTP connection. 216.It Ev HTTP_TIMEOUT 217Maximum time, in seconds, to wait before aborting an HTTP connection. 218.El 219.Pp 220See 221.Xr fetch 3 222for a description of additional environment variables, including 223.Ev FETCH_BIND_ADDRESS , 224.Ev FTP_LOGIN , 225.Ev FTP_PASSIVE_MODE , 226.Ev FTP_PASSWORD , 227.Ev FTP_PROXY , 228.Ev ftp_proxy , 229.Ev HTTP_AUTH , 230.Ev HTTP_PROXY , 231.Ev http_proxy , 232.Ev HTTP_PROXY_AUTH , 233.Ev HTTP_REFERER , 234.Ev HTTP_USER_AGENT , 235.Ev NETRC , 236.Ev NO_PROXY and 237.Ev no_proxy . 238.Sh EXIT STATUS 239The 240.Nm 241command returns zero on success, or one on failure. 242If multiple URLs are listed on the command line, 243.Nm 244will attempt to retrieve each one of them in turn, and will return 245zero only if they were all successfully retrieved. 246.Sh SEE ALSO 247.Xr fetch 3 248.Sh HISTORY 249The 250.Nm 251command appeared in 252.Fx 2.1.5 . 253This implementation first appeared in 254.Fx 4.1 . 255.Sh AUTHORS 256.An -nosplit 257The original implementation of 258.Nm 259was done by 260.An Jean-Marc Zucconi Aq jmz@FreeBSD.org . 261It was extensively re-worked for 262.Fx 2.2 263by 264.An Garrett Wollman Aq wollman@FreeBSD.org , 265and later completely rewritten to use the 266.Xr fetch 3 267library by 268.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . 269.Sh NOTES 270The 271.Fl b 272and 273.Fl t 274options are no longer supported and will generate warnings. 275They were workarounds for bugs in other OSes which this implementation 276does not trigger. 277.Pp 278One cannot both use the 279.Fl h , 280.Fl c 281and 282.Fl f 283options and specify URLs on the command line. 284