2 .\" Copyright (c) 2000-2012 Dag-Erling Smørgrav
3 .\" All rights reserved.
4 .\" Portions Copyright (c) 1999 Massachusetts Institute of Technology; used
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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.
37 .Nd retrieve a file by Uniform Resource Locator
40 .Op Fl 146AadFlMmnPpqRrsUv
50 .Op Fl 146AadFlMmnPpqRrsUv
58 .Fl h Ar host Fl f Ar file Oo Fl c Ar dir Oc
62 utility provides a command-line interface to the
65 Its purpose is to retrieve the file(s) pointed to by the URL(s) on the
68 The following options are available:
71 Stop and return exit code 0 at the first successfully retrieved file.
75 to use IPv4 addresses only.
79 to use IPv6 addresses only.
81 Do not automatically follow ``temporary'' (302) redirects.
82 Some broken Web sites will return a redirect instead of a not-found
83 error when the requested object does not exist.
85 Automatically retry the transfer upon soft failures.
87 Specify the read buffer size in bytes.
88 The default is 4096 bytes.
89 Attempts to set a buffer size lower than this will be silently
91 The number of reads actually performed is reported at verbosity level
92 two or higher (see the
96 The file to retrieve is in directory
99 This option is deprecated and is provided for backward compatibility
102 Use a direct connection even if a proxy is configured.
104 In combination with the
106 flag, forces a restart even if the local and remote files have
107 different modification times.
111 The file to retrieve is named
114 This option is deprecated and is provided for backward compatibility
117 The file to retrieve is located on the host
119 This option is deprecated and is provided for backward compatibility
122 If-Modified-Since mode: the remote file will only be retrieved if it
128 If the target is a file-scheme URL, make a symbolic link to the target
129 rather than trying to copy it.
132 Mirror mode: if the file already exists locally and has the same size
133 and modification time as the remote file, it will not be fetched.
138 flags are mutually exclusive.
144 to look up login names and passwords for FTP sites.
147 for a description of the file format.
148 This feature is experimental.
150 Do not preserve the modification time of the transferred file.
152 Set the output file name to
154 By default, a ``pathname'' is extracted from the specified URI, and
155 its basename is used as the name of the output file.
160 indicates that results are to be directed to the standard output.
163 argument is a directory, fetched file(s) will be placed within the
164 directory, with name(s) selected as in the default behaviour.
168 These flags have no effect, since passive FTP is the default, but are
169 provided for compatibility with earlier versions where active FTP was
171 To force active mode, set the
173 environment variable to
178 The output files are precious, and should not be deleted under any
179 circumstances, even if the transfer failed or was incomplete.
181 Restart a previously interrupted transfer.
186 flags are mutually exclusive.
188 Require the file size reported by the server to match the specified
190 If it does not, a message is printed and the file is not fetched.
191 If the server does not support reporting file sizes, this option is
192 ignored and the file is fetched unconditionally.
194 Print the size in bytes of each requested file, without fetching it.
198 Overrides the environment variables
202 for HTTP transfers if set.
204 When using passive FTP, allocate the port for the data connection from
205 the low (default) port range.
208 for details on how to specify which port range this corresponds to.
210 Increase verbosity level.
214 flag is specified, wait this many seconds between successive retries.
219 <scheme>:(//(<user>(:<pwd>)?@)?<host>(:<port>)?)?/(<document>)?
230 the current transfer rate statistics will be written to the
231 standard error output, in the same format as the standard completion
234 .Bl -tag -width HTTP_TIMEOUT
236 Maximum time, in seconds, to wait before aborting an FTP connection.
238 Maximum time, in seconds, to wait before aborting an HTTP connection.
243 for a description of additional environment variables, including
244 .Ev FETCH_BIND_ADDRESS ,
246 .Ev FTP_PASSIVE_MODE ,
253 .Ev HTTP_PROXY_AUTH ,
255 .Ev HTTP_USER_AGENT ,
262 command returns zero on success, or one on failure.
263 If multiple URLs are listed on the command line,
265 will attempt to retrieve each one of them in turn, and will return
266 zero only if they were all successfully retrieved.
270 argument is used and the remote file is not newer than the
271 specified file then the command will still return success,
272 although no file is transferred.
280 This implementation first appeared in
284 The original implementation of
287 .An Jean-Marc Zucconi Aq jmz@FreeBSD.org .
288 It was extensively re-worked for
291 .An Garrett Wollman Aq wollman@FreeBSD.org ,
292 and later completely rewritten to use the
295 .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
301 options are no longer supported and will generate warnings.
302 They were workarounds for bugs in other OSes which this implementation
305 One cannot both use the
310 options and specify URLs on the command line.