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