usr.bin/fetch/fetch.1

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