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