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