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