usr.bin/fetch/fetch.1

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