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