1.\"- 2.\" Copyright (c) 2000 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.33.2.12 2003/06/06 06:48:42 des Exp $ 31.\" $DragonFly: src/usr.bin/fetch/fetch.1,v 1.3 2006/02/17 19:39:03 swildner Exp $ 32.\" 33.Dd June 28, 2000 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 137Don't 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. 148.It Fl P 149.It Fl p 150Use passive FTP. 151This is useful if you are behind a firewall which blocks incoming 152connections. 153Try this flag if 154.Nm 155seems to hang when retrieving FTP URLs. 156.It Fl q 157Quiet mode. 158.It Fl R 159The output files are precious, and should not be deleted under any 160circumstances, even if the transfer failed or was incomplete. 161.It Fl r 162Restart a previously interrupted transfer. 163Note that the 164.Fl m 165and 166.Fl r 167flags are mutually exclusive. 168.It Fl S Ar bytes 169Require the file size reported by the server to match the specified 170value. 171If it does not, a message is printed and the file is not fetched. 172If the server does not support reporting file sizes, this option is 173ignored and the file is fetched unconditionally. 174.It Fl s 175Print the size in bytes of each requested file, without fetching it. 176.It Fl T Ar seconds 177Set timeout value to 178.Ar seconds . 179Overrides the environment variables 180.Ev FTP_TIMEOUT 181for FTP transfers or 182.Ev HTTP_TIMEOUT 183for HTTP transfers if set. 184.It Fl U 185When using passive FTP, allocate the port for the data connection from 186the low (default) port range. 187See 188.Xr ip 4 189for details on how to specify which port range this corresponds to. 190.It Fl v 191Increase verbosity level. 192.It Fl w Ar seconds 193When the 194.Fl a 195flag is specified, wait this many seconds between successive retries. 196.El 197.Pp 198If 199.Nm 200receives a 201.Dv SIGINFO 202signal (see the 203.Cm status 204argument for 205.Xr stty 1 ) , 206the current transfer rate statistics will be written to the 207standard error output, in the same format as the standard completion 208message. 209.Sh ENVIRONMENT 210.Bl -tag -width HTTP_TIMEOUT 211.It Ev FTP_TIMEOUT 212maximum time, in seconds, to wait before aborting an 213.Tn FTP 214connection. 215.It Ev HTTP_TIMEOUT 216maximum time, in seconds, to wait before aborting an 217.Tn HTTP 218connection. 219.El 220.Pp 221All environment variables mentioned in the documentation for the 222.Xr fetch 3 223library are supported. 224.Sh DIAGNOSTICS 225The 226.Nm 227command returns zero on success, or one on failure. 228If multiple URLs are listed on the command line, 229.Nm 230will attempt to retrieve them each of them in turn, and return zero 231only if they were all successfully retrieved. 232.Sh SEE ALSO 233.Xr sh 1 , 234.Xr fetch 3 235.Sh HISTORY 236The 237.Nm 238command appeared in 239.Fx 2.1.5 . 240This implementation first appeared in 241.Fx 4.1 . 242.Sh AUTHORS 243.An -nosplit 244The original implementation of 245.Nm 246was done by 247.An Jean-Marc Zucconi . 248It was extensively re-worked for 249.Fx 2.2 250by 251.An Garrett Wollman , 252and later completely rewritten to use the 253.Xr fetch 3 254library by 255.An Dag-Erling Sm\(/orgrav . 256.Sh NOTES 257The 258.Fl b 259and 260.Fl t 261options are no longer supported and will generate warnings. 262They were workarounds for bugs in other OSes which this implementation 263does not trigger. 264.Pp 265One cannot both use the 266.Fl h , 267.Fl c 268and 269.Fl f 270options and specify URLs on the command line. 271