/usr.bin/fetch/fetch.1

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