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