1.\" $NetBSD: fetch.1,v 1.4 2009/02/07 15:25:51 wiz Exp $ 2.\"- 3.\" Copyright (c) 2000-2004 Dag-Erling Coïdan Smørgrav 4.\" All rights reserved. 5.\" Portions Copyright (c) 1999 Massachusetts Institute of Technology; used 6.\" by permission. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer 13.\" in this position and unchanged. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd February 5, 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 146AFMRUadilmnqrsv 42.Op Fl B Ar bytes 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.Op Ar URL ... 49.Sh DESCRIPTION 50The 51.Nm 52utility provides 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 72.Dq temporary 73(302) redirects. 74Some broken Web sites will return a redirect instead of a not-found 75error when the requested object does not exist. 76.It Fl a 77Automatically retry the transfer upon soft failures. 78.It Fl B Ar bytes 79Specify the read buffer size in bytes. 80The default is 4096 bytes. 81Attempts to set a buffer size lower than this will be silently 82ignored. 83The number of reads actually performed is reported at verbosity level 84two or higher (see the 85.Fl v 86flag). 87.It Fl d 88Use a direct connection even if a proxy is configured. 89.It Fl F 90In combination with the 91.Fl r 92flag, forces a restart even if the local and remote files have 93different modification times. 94Implies 95.Fl R . 96.It Fl i 97Only fetch if it the output file is older than the referenced URL. 98This option is overriden by 99.Fl o Ar - . 100.It Fl l 101If the target is a file-scheme URL, make a symbolic link to the target 102rather than trying to copy it. 103.It Fl M 104.It Fl m 105Mirror mode: if the file already exists locally and has the same size 106and modification time as the remote file, it will not be fetched. 107Note that the 108.Fl m 109and 110.Fl r 111flags are mutually exclusive. 112.It Fl N Ar file 113Use 114.Ar file 115instead of 116.Pa ~/.netrc 117to look up login names and passwords for FTP sites. 118See 119.Xr ftp 1 120for a description of the file format. 121This feature is experimental. 122.It Fl n 123Do not preserve the modification time of the transferred file. 124.It Fl o Ar file 125Set the output file name to 126.Ar file . 127By default, a 128.Dq pathname 129is extracted from the specified URI, and 130its basename is used as the name of the output file. 131A 132.Ar file 133argument of 134.Sq Li \&- 135indicates that results are to be directed to the standard output. 136If the 137.Ar file 138argument is a directory, fetched file(s) will be placed within the 139directory, with name(s) selected as in the default behaviour. 140.It Fl q 141Quiet mode. 142.It Fl R 143The output files are precious, and should not be deleted under any 144circumstances, even if the transfer failed or was incomplete. 145.It Fl r 146Restart a previously interrupted transfer. 147Note that the 148.Fl m 149and 150.Fl r 151flags are mutually exclusive. 152.It Fl S Ar bytes 153Require the file size reported by the server to match the specified 154value. 155If it does not, a message is printed and the file is not fetched. 156If the server does not support reporting file sizes, this option is 157ignored and the file is fetched unconditionally. 158.It Fl s 159Print the size in bytes of each requested file, without fetching it. 160.It Fl T Ar seconds 161Set timeout value to 162.Ar seconds . 163Overrides the environment variables 164.Ev FTP_TIMEOUT 165for FTP transfers or 166.Ev HTTP_TIMEOUT 167for HTTP transfers if set. 168.It Fl U 169When using passive FTP, allocate the port for the data connection from 170the low (default) port range. 171See 172.Xr ip 4 173for details on how to specify which port range this corresponds to. 174.It Fl v 175Increase verbosity level. 176.It Fl w Ar seconds 177When the 178.Fl a 179flag is specified, wait this many seconds between successive retries. 180.El 181.Pp 182If 183.Nm 184receives a 185.Dv SIGINFO 186signal (see the 187.Cm status 188argument for 189.Xr stty 1 ) , 190the current transfer rate statistics will be written to the 191standard error output, in the same format as the standard completion 192message. 193.Sh EXIT STATUS 194The 195.Nm 196command returns zero on success, or one on failure. 197If multiple URLs are listed on the command line, 198.Nm 199will attempt to retrieve each one of them in turn, and will return 200zero only if they were all successfully retrieved. 201.Sh ENVIRONMENT 202.Bl -tag -width HTTP_TIMEOUT 203.It Ev FTP_TIMEOUT 204Maximum time, in seconds, to wait before aborting an FTP connection. 205.It Ev HTTP_TIMEOUT 206Maximum time, in seconds, to wait before aborting an HTTP connection. 207.El 208.Pp 209See 210.Xr fetch 3 211for a description of additional environment variables, including 212.Ev FETCH_BIND_ADDRESS , 213.Ev FTP_LOGIN , 214.Ev FTP_PASSIVE_MODE , 215.Ev FTP_PASSWORD , 216.Ev FTP_PROXY , 217.Ev ftp_proxy , 218.Ev HTTP_AUTH , 219.Ev HTTP_PROXY , 220.Ev http_proxy , 221.Ev HTTP_PROXY_AUTH , 222.Ev HTTP_REFERER , 223.Ev HTTP_USER_AGENT , 224.Ev NETRC , 225.Ev NO_PROXY 226and 227.Ev no_proxy . 228.Sh SEE ALSO 229.Xr fetch 3 230.Sh HISTORY 231The 232.Nm 233command appeared in 234.Fx 2.1.5 . 235This implementation first appeared in 236.Fx 4.1 . 237.Sh AUTHORS 238.An -nosplit 239The original implementation of 240.Nm 241was done by 242.An Jean-Marc Zucconi Aq jmz@FreeBSD.org . 243It was extensively re-worked for 244.Fx 2.2 245by 246.An Garrett Wollman Aq wollman@FreeBSD.org , 247and later completely rewritten to use the 248.Xr fetch 3 249library by 250.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . 251.Sh NOTES 252The 253.Fl b 254and 255.Fl t 256options are no longer supported and will generate warnings. 257They were workarounds for bugs in other OSes which this implementation 258does not trigger. 259.Pp 260One cannot both use the 261.Fl h , 262.Fl c , 263and 264.Fl f 265options and specify URLs on the command line. 266