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: src/usr.bin/fetch/fetch.1,v 1.70 2008/12/15 08:27:44 murray Exp $ 31.\" $DragonFly: src/usr.bin/fetch/fetch.1,v 1.4 2007/08/05 21:48:12 swildner Exp $ 32.\" 33.Dd May 10, 2009 34.Dt FETCH 1 35.Os 36.Sh NAME 37.Nm fetch 38.Nd retrieve a file by Uniform Resource Locator 39.Sh SYNOPSIS 40.Nm 41.Op Fl 146AadFlMmnPpqRrsUv 42.Op Fl B Ar bytes 43.Op Fl i Ar file 44.Op Fl N Ar file 45.Op Fl o Ar file 46.Op Fl S Ar bytes 47.Op Fl T Ar seconds 48.Op Fl w Ar seconds 49.Ar URL ... 50.Nm 51.Op Fl 146AadFlMmnPpqRrsUv 52.Op Fl B Ar bytes 53.Op Fl i Ar file 54.Op Fl N Ar file 55.Op Fl o Ar file 56.Op Fl S Ar bytes 57.Op Fl T Ar seconds 58.Op Fl w Ar seconds 59.Fl h Ar host Fl f Ar file Oo Fl c Ar dir Oc 60.Sh DESCRIPTION 61The 62.Nm 63utility provides a command-line interface to the 64.Xr fetch 3 65library. 66Its purpose is to retrieve the file(s) pointed to by the URL(s) on the 67command line. 68.Pp 69The following options are available: 70.Bl -tag -width Fl 71.It Fl 1 72Stop and return exit code 0 at the first successfully retrieved file. 73.It Fl 4 74Forces 75.Nm 76to use IPv4 addresses only. 77.It Fl 6 78Forces 79.Nm 80to use IPv6 addresses only. 81.It Fl A 82Do not automatically follow ``temporary'' (302) redirects. 83Some broken Web sites will return a redirect instead of a not-found 84error when the requested object does not exist. 85.It Fl a 86Automatically retry the transfer upon soft failures. 87.It Fl B Ar bytes 88Specify the read buffer size in bytes. 89The default is 4096 bytes. 90Attempts to set a buffer size lower than this will be silently 91ignored. 92The number of reads actually performed is reported at verbosity level 93two or higher (see the 94.Fl v 95flag). 96.It Fl c Ar dir 97The file to retrieve is in directory 98.Ar dir 99on the remote host. 100This option is deprecated and is provided for backward compatibility 101only. 102.It Fl d 103Use a direct connection even if a proxy is configured. 104.It Fl F 105In combination with the 106.Fl r 107flag, forces a restart even if the local and remote files have 108different modification times. 109Implies 110.Fl R . 111.It Fl f Ar file 112The file to retrieve is named 113.Ar file 114on the remote host. 115This option is deprecated and is provided for backward compatibility 116only. 117.It Fl h Ar host 118The file to retrieve is located on the host 119.Ar host . 120This option is deprecated and is provided for backward compatibility 121only. 122.It Fl i Ar file 123If-Modified-Since mode: the remote file will only be retrieved if it 124is newer than 125.Ar file 126on the local host. 127(HTTP only) 128.It Fl l 129If the target is a file-scheme URL, make a symbolic link to the target 130rather than trying to copy it. 131.It Fl M 132.It Fl m 133Mirror mode: if the file already exists locally and has the same size 134and modification time as the remote file, it will not be fetched. 135Note that the 136.Fl m 137and 138.Fl r 139flags are mutually exclusive. 140.It Fl N Ar file 141Use 142.Ar file 143instead of 144.Pa ~/.netrc 145to look up login names and passwords for FTP sites. 146See 147.Xr ftp 1 148for a description of the file format. 149This feature is experimental. 150.It Fl n 151Do not preserve the modification time of the transferred file. 152.It Fl o Ar file 153Set the output file name to 154.Ar file . 155By default, a ``pathname'' is extracted from the specified URI, and 156its basename is used as the name of the output file. 157A 158.Ar file 159argument of 160.Sq Li \&- 161indicates that results are to be directed to the standard output. 162If the 163.Ar file 164argument is a directory, fetched file(s) will be placed within the 165directory, with name(s) selected as in the default behaviour. 166.It Fl P 167.It Fl p 168Use passive FTP. 169This is useful if you are behind a firewall which blocks incoming 170connections. 171Try this flag if 172.Nm 173seems to hang when retrieving FTP URLs. 174.It Fl q 175Quiet mode. 176.It Fl R 177The output files are precious, and should not be deleted under any 178circumstances, even if the transfer failed or was incomplete. 179.It Fl r 180Restart a previously interrupted transfer. 181Note that the 182.Fl m 183and 184.Fl r 185flags are mutually exclusive. 186.It Fl S Ar bytes 187Require the file size reported by the server to match the specified 188value. 189If it does not, a message is printed and the file is not fetched. 190If the server does not support reporting file sizes, this option is 191ignored and the file is fetched unconditionally. 192.It Fl s 193Print the size in bytes of each requested file, without fetching it. 194.It Fl T Ar seconds 195Set timeout value to 196.Ar seconds . 197Overrides the environment variables 198.Ev FTP_TIMEOUT 199for FTP transfers or 200.Ev HTTP_TIMEOUT 201for HTTP transfers if set. 202.It Fl U 203When using passive FTP, allocate the port for the data connection from 204the low (default) port range. 205See 206.Xr ip 4 207for details on how to specify which port range this corresponds to. 208.It Fl v 209Increase verbosity level. 210.It Fl w Ar seconds 211When the 212.Fl a 213flag is specified, wait this many seconds between successive retries. 214.El 215.Pp 216If 217.Nm 218receives a 219.Dv SIGINFO 220signal (see the 221.Cm status 222argument for 223.Xr stty 1 ) , 224the current transfer rate statistics will be written to the 225standard error output, in the same format as the standard completion 226message. 227.Sh ENVIRONMENT 228.Bl -tag -width HTTP_TIMEOUT 229.It Ev FTP_TIMEOUT 230Maximum time, in seconds, to wait before aborting an FTP connection. 231.It Ev HTTP_TIMEOUT 232Maximum time, in seconds, to wait before aborting an HTTP connection. 233.El 234.Pp 235See 236.Xr fetch 3 237for a description of additional environment variables, including 238.Ev FETCH_BIND_ADDRESS , 239.Ev FTP_LOGIN , 240.Ev FTP_PASSIVE_MODE , 241.Ev FTP_PASSWORD , 242.Ev FTP_PROXY , 243.Ev ftp_proxy , 244.Ev HTTP_AUTH , 245.Ev HTTP_PROXY , 246.Ev http_proxy , 247.Ev HTTP_PROXY_AUTH , 248.Ev HTTP_REFERER , 249.Ev HTTP_USER_AGENT , 250.Ev NETRC , 251.Ev NO_PROXY and 252.Ev no_proxy . 253.Sh EXIT STATUS 254The 255.Nm 256command returns zero on success, or one on failure. 257If multiple URLs are listed on the command line, 258.Nm 259will attempt to retrieve each one of them in turn, and will return 260zero only if they were all successfully retrieved. 261.Pp 262If the 263.Fl i 264argument is used and the remote file is not newer than the 265specified file then the command will still return success, 266although no file is transferred. 267.Sh SEE ALSO 268.Xr fetch 3 269.Sh HISTORY 270The 271.Nm 272command appeared in 273.Fx 2.1.5 . 274This implementation first appeared in 275.Fx 4.1 . 276.Sh AUTHORS 277.An -nosplit 278The original implementation of 279.Nm 280was done by 281.An Jean-Marc Zucconi Aq jmz@FreeBSD.org . 282It was extensively re-worked for 283.Fx 2.2 284by 285.An Garrett Wollman Aq wollman@FreeBSD.org , 286and later completely rewritten to use the 287.Xr fetch 3 288library by 289.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . 290.Sh NOTES 291The 292.Fl b 293and 294.Fl t 295options are no longer supported and will generate warnings. 296They were workarounds for bugs in other OSes which this implementation 297does not trigger. 298.Pp 299One cannot both use the 300.Fl h , 301.Fl c 302and 303.Fl f 304options and specify URLs on the command line. 305