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