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