xref: /minix3/minix/commands/fetch/fetch.1 (revision 433d6423c39e34ec4b79c950597bb2d236f886be)
1*433d6423SLionel Sambuc.\" $NetBSD: fetch.1,v 1.4 2009/02/07 15:25:51 wiz Exp $
2*433d6423SLionel Sambuc.\"-
3*433d6423SLionel Sambuc.\" Copyright (c) 2000-2004 Dag-Erling Coïdan Smørgrav
4*433d6423SLionel Sambuc.\" All rights reserved.
5*433d6423SLionel Sambuc.\" Portions Copyright (c) 1999 Massachusetts Institute of Technology; used
6*433d6423SLionel Sambuc.\" by permission.
7*433d6423SLionel Sambuc.\"
8*433d6423SLionel Sambuc.\" Redistribution and use in source and binary forms, with or without
9*433d6423SLionel Sambuc.\" modification, are permitted provided that the following conditions
10*433d6423SLionel Sambuc.\" are met:
11*433d6423SLionel Sambuc.\" 1. Redistributions of source code must retain the above copyright
12*433d6423SLionel Sambuc.\"    notice, this list of conditions and the following disclaimer
13*433d6423SLionel Sambuc.\"    in this position and unchanged.
14*433d6423SLionel Sambuc.\" 2. Redistributions in binary form must reproduce the above copyright
15*433d6423SLionel Sambuc.\"    notice, this list of conditions and the following disclaimer in the
16*433d6423SLionel Sambuc.\"    documentation and/or other materials provided with the distribution.
17*433d6423SLionel Sambuc.\" 3. The name of the author may not be used to endorse or promote products
18*433d6423SLionel Sambuc.\"    derived from this software without specific prior written permission.
19*433d6423SLionel Sambuc.\"
20*433d6423SLionel Sambuc.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
21*433d6423SLionel Sambuc.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
22*433d6423SLionel Sambuc.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
23*433d6423SLionel Sambuc.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
24*433d6423SLionel Sambuc.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
25*433d6423SLionel Sambuc.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26*433d6423SLionel Sambuc.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27*433d6423SLionel Sambuc.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28*433d6423SLionel Sambuc.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
29*433d6423SLionel Sambuc.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30*433d6423SLionel Sambuc.\"
31*433d6423SLionel Sambuc.\" $FreeBSD$
32*433d6423SLionel Sambuc.\"
33*433d6423SLionel Sambuc.Dd February 5, 2009
34*433d6423SLionel Sambuc.Dt FETCH 1
35*433d6423SLionel Sambuc.Os
36*433d6423SLionel Sambuc.Sh NAME
37*433d6423SLionel Sambuc.Nm fetch
38*433d6423SLionel Sambuc.Nd retrieve a file by Uniform Resource Locator
39*433d6423SLionel Sambuc.Sh SYNOPSIS
40*433d6423SLionel Sambuc.Nm
41*433d6423SLionel Sambuc.Op Fl 146AFMRUadilmnqrsv
42*433d6423SLionel Sambuc.Op Fl B Ar bytes
43*433d6423SLionel Sambuc.Op Fl N Ar file
44*433d6423SLionel Sambuc.Op Fl o Ar file
45*433d6423SLionel Sambuc.Op Fl S Ar bytes
46*433d6423SLionel Sambuc.Op Fl T Ar seconds
47*433d6423SLionel Sambuc.Op Fl w Ar seconds
48*433d6423SLionel Sambuc.Op Ar URL ...
49*433d6423SLionel Sambuc.Sh DESCRIPTION
50*433d6423SLionel SambucThe
51*433d6423SLionel Sambuc.Nm
52*433d6423SLionel Sambucutility provides a command-line interface to the
53*433d6423SLionel Sambuc.Xr fetch 3
54*433d6423SLionel Sambuclibrary.
55*433d6423SLionel SambucIts purpose is to retrieve the file(s) pointed to by the URL(s) on the
56*433d6423SLionel Sambuccommand line.
57*433d6423SLionel Sambuc.Pp
58*433d6423SLionel SambucThe following options are available:
59*433d6423SLionel Sambuc.Bl -tag -width Fl
60*433d6423SLionel Sambuc.It Fl 1
61*433d6423SLionel SambucStop and return exit code 0 at the first successfully retrieved file.
62*433d6423SLionel Sambuc.It Fl 4
63*433d6423SLionel SambucForces
64*433d6423SLionel Sambuc.Nm
65*433d6423SLionel Sambucto use IPv4 addresses only.
66*433d6423SLionel Sambuc.It Fl 6
67*433d6423SLionel SambucForces
68*433d6423SLionel Sambuc.Nm
69*433d6423SLionel Sambucto use IPv6 addresses only.
70*433d6423SLionel Sambuc.It Fl A
71*433d6423SLionel SambucDo not automatically follow
72*433d6423SLionel Sambuc.Dq temporary
73*433d6423SLionel Sambuc(302) redirects.
74*433d6423SLionel SambucSome broken Web sites will return a redirect instead of a not-found
75*433d6423SLionel Sambucerror when the requested object does not exist.
76*433d6423SLionel Sambuc.It Fl a
77*433d6423SLionel SambucAutomatically retry the transfer upon soft failures.
78*433d6423SLionel Sambuc.It Fl B Ar bytes
79*433d6423SLionel SambucSpecify the read buffer size in bytes.
80*433d6423SLionel SambucThe default is 4096 bytes.
81*433d6423SLionel SambucAttempts to set a buffer size lower than this will be silently
82*433d6423SLionel Sambucignored.
83*433d6423SLionel SambucThe number of reads actually performed is reported at verbosity level
84*433d6423SLionel Sambuctwo or higher (see the
85*433d6423SLionel Sambuc.Fl v
86*433d6423SLionel Sambucflag).
87*433d6423SLionel Sambuc.It Fl d
88*433d6423SLionel SambucUse a direct connection even if a proxy is configured.
89*433d6423SLionel Sambuc.It Fl F
90*433d6423SLionel SambucIn combination with the
91*433d6423SLionel Sambuc.Fl r
92*433d6423SLionel Sambucflag, forces a restart even if the local and remote files have
93*433d6423SLionel Sambucdifferent modification times.
94*433d6423SLionel SambucImplies
95*433d6423SLionel Sambuc.Fl R .
96*433d6423SLionel Sambuc.It Fl i
97*433d6423SLionel SambucOnly fetch if it the output file is older than the referenced URL.
98*433d6423SLionel SambucThis option is overriden by
99*433d6423SLionel Sambuc.Fl o Ar - .
100*433d6423SLionel Sambuc.It Fl l
101*433d6423SLionel SambucIf the target is a file-scheme URL, make a symbolic link to the target
102*433d6423SLionel Sambucrather than trying to copy it.
103*433d6423SLionel Sambuc.It Fl M
104*433d6423SLionel Sambuc.It Fl m
105*433d6423SLionel SambucMirror mode: if the file already exists locally and has the same size
106*433d6423SLionel Sambucand modification time as the remote file, it will not be fetched.
107*433d6423SLionel SambucNote that the
108*433d6423SLionel Sambuc.Fl m
109*433d6423SLionel Sambucand
110*433d6423SLionel Sambuc.Fl r
111*433d6423SLionel Sambucflags are mutually exclusive.
112*433d6423SLionel Sambuc.It Fl N Ar file
113*433d6423SLionel SambucUse
114*433d6423SLionel Sambuc.Ar file
115*433d6423SLionel Sambucinstead of
116*433d6423SLionel Sambuc.Pa ~/.netrc
117*433d6423SLionel Sambucto look up login names and passwords for FTP sites.
118*433d6423SLionel SambucSee
119*433d6423SLionel Sambuc.Xr ftp 1
120*433d6423SLionel Sambucfor a description of the file format.
121*433d6423SLionel SambucThis feature is experimental.
122*433d6423SLionel Sambuc.It Fl n
123*433d6423SLionel SambucDo not preserve the modification time of the transferred file.
124*433d6423SLionel Sambuc.It Fl o Ar file
125*433d6423SLionel SambucSet the output file name to
126*433d6423SLionel Sambuc.Ar file .
127*433d6423SLionel SambucBy default, a
128*433d6423SLionel Sambuc.Dq pathname
129*433d6423SLionel Sambucis extracted from the specified URI, and
130*433d6423SLionel Sambucits basename is used as the name of the output file.
131*433d6423SLionel SambucA
132*433d6423SLionel Sambuc.Ar file
133*433d6423SLionel Sambucargument of
134*433d6423SLionel Sambuc.Sq Li \&-
135*433d6423SLionel Sambucindicates that results are to be directed to the standard output.
136*433d6423SLionel SambucIf the
137*433d6423SLionel Sambuc.Ar file
138*433d6423SLionel Sambucargument is a directory, fetched file(s) will be placed within the
139*433d6423SLionel Sambucdirectory, with name(s) selected as in the default behaviour.
140*433d6423SLionel Sambuc.It Fl q
141*433d6423SLionel SambucQuiet mode.
142*433d6423SLionel Sambuc.It Fl R
143*433d6423SLionel SambucThe output files are precious, and should not be deleted under any
144*433d6423SLionel Sambuccircumstances, even if the transfer failed or was incomplete.
145*433d6423SLionel Sambuc.It Fl r
146*433d6423SLionel SambucRestart a previously interrupted transfer.
147*433d6423SLionel SambucNote that the
148*433d6423SLionel Sambuc.Fl m
149*433d6423SLionel Sambucand
150*433d6423SLionel Sambuc.Fl r
151*433d6423SLionel Sambucflags are mutually exclusive.
152*433d6423SLionel Sambuc.It Fl S Ar bytes
153*433d6423SLionel SambucRequire the file size reported by the server to match the specified
154*433d6423SLionel Sambucvalue.
155*433d6423SLionel SambucIf it does not, a message is printed and the file is not fetched.
156*433d6423SLionel SambucIf the server does not support reporting file sizes, this option is
157*433d6423SLionel Sambucignored and the file is fetched unconditionally.
158*433d6423SLionel Sambuc.It Fl s
159*433d6423SLionel SambucPrint the size in bytes of each requested file, without fetching it.
160*433d6423SLionel Sambuc.It Fl T Ar seconds
161*433d6423SLionel SambucSet timeout value to
162*433d6423SLionel Sambuc.Ar seconds .
163*433d6423SLionel SambucOverrides the environment variables
164*433d6423SLionel Sambuc.Ev FTP_TIMEOUT
165*433d6423SLionel Sambucfor FTP transfers or
166*433d6423SLionel Sambuc.Ev HTTP_TIMEOUT
167*433d6423SLionel Sambucfor HTTP transfers if set.
168*433d6423SLionel Sambuc.It Fl U
169*433d6423SLionel SambucWhen using passive FTP, allocate the port for the data connection from
170*433d6423SLionel Sambucthe low (default) port range.
171*433d6423SLionel SambucSee
172*433d6423SLionel Sambuc.Xr ip 4
173*433d6423SLionel Sambucfor details on how to specify which port range this corresponds to.
174*433d6423SLionel Sambuc.It Fl v
175*433d6423SLionel SambucIncrease verbosity level.
176*433d6423SLionel Sambuc.It Fl w Ar seconds
177*433d6423SLionel SambucWhen the
178*433d6423SLionel Sambuc.Fl a
179*433d6423SLionel Sambucflag is specified, wait this many seconds between successive retries.
180*433d6423SLionel Sambuc.El
181*433d6423SLionel Sambuc.Pp
182*433d6423SLionel SambucIf
183*433d6423SLionel Sambuc.Nm
184*433d6423SLionel Sambucreceives a
185*433d6423SLionel Sambuc.Dv SIGINFO
186*433d6423SLionel Sambucsignal (see the
187*433d6423SLionel Sambuc.Cm status
188*433d6423SLionel Sambucargument for
189*433d6423SLionel Sambuc.Xr stty 1 ) ,
190*433d6423SLionel Sambucthe current transfer rate statistics will be written to the
191*433d6423SLionel Sambucstandard error output, in the same format as the standard completion
192*433d6423SLionel Sambucmessage.
193*433d6423SLionel Sambuc.Sh EXIT STATUS
194*433d6423SLionel SambucThe
195*433d6423SLionel Sambuc.Nm
196*433d6423SLionel Sambuccommand returns zero on success, or one on failure.
197*433d6423SLionel SambucIf multiple URLs are listed on the command line,
198*433d6423SLionel Sambuc.Nm
199*433d6423SLionel Sambucwill attempt to retrieve each one of them in turn, and will return
200*433d6423SLionel Sambuczero only if they were all successfully retrieved.
201*433d6423SLionel Sambuc.Sh ENVIRONMENT
202*433d6423SLionel Sambuc.Bl -tag -width HTTP_TIMEOUT
203*433d6423SLionel Sambuc.It Ev FTP_TIMEOUT
204*433d6423SLionel SambucMaximum time, in seconds, to wait before aborting an FTP connection.
205*433d6423SLionel Sambuc.It Ev HTTP_TIMEOUT
206*433d6423SLionel SambucMaximum time, in seconds, to wait before aborting an HTTP connection.
207*433d6423SLionel Sambuc.El
208*433d6423SLionel Sambuc.Pp
209*433d6423SLionel SambucSee
210*433d6423SLionel Sambuc.Xr fetch 3
211*433d6423SLionel Sambucfor a description of additional environment variables, including
212*433d6423SLionel Sambuc.Ev FETCH_BIND_ADDRESS ,
213*433d6423SLionel Sambuc.Ev FTP_LOGIN ,
214*433d6423SLionel Sambuc.Ev FTP_PASSIVE_MODE ,
215*433d6423SLionel Sambuc.Ev FTP_PASSWORD ,
216*433d6423SLionel Sambuc.Ev FTP_PROXY ,
217*433d6423SLionel Sambuc.Ev ftp_proxy ,
218*433d6423SLionel Sambuc.Ev HTTP_AUTH ,
219*433d6423SLionel Sambuc.Ev HTTP_PROXY ,
220*433d6423SLionel Sambuc.Ev http_proxy ,
221*433d6423SLionel Sambuc.Ev HTTP_PROXY_AUTH ,
222*433d6423SLionel Sambuc.Ev HTTP_REFERER ,
223*433d6423SLionel Sambuc.Ev HTTP_USER_AGENT ,
224*433d6423SLionel Sambuc.Ev NETRC ,
225*433d6423SLionel Sambuc.Ev NO_PROXY
226*433d6423SLionel Sambucand
227*433d6423SLionel Sambuc.Ev no_proxy .
228*433d6423SLionel Sambuc.Sh SEE ALSO
229*433d6423SLionel Sambuc.Xr fetch 3
230*433d6423SLionel Sambuc.Sh HISTORY
231*433d6423SLionel SambucThe
232*433d6423SLionel Sambuc.Nm
233*433d6423SLionel Sambuccommand appeared in
234*433d6423SLionel Sambuc.Fx 2.1.5 .
235*433d6423SLionel SambucThis implementation first appeared in
236*433d6423SLionel Sambuc.Fx 4.1 .
237*433d6423SLionel Sambuc.Sh AUTHORS
238*433d6423SLionel Sambuc.An -nosplit
239*433d6423SLionel SambucThe original implementation of
240*433d6423SLionel Sambuc.Nm
241*433d6423SLionel Sambucwas done by
242*433d6423SLionel Sambuc.An Jean-Marc Zucconi Aq jmz@FreeBSD.org .
243*433d6423SLionel SambucIt was extensively re-worked for
244*433d6423SLionel Sambuc.Fx 2.2
245*433d6423SLionel Sambucby
246*433d6423SLionel Sambuc.An Garrett Wollman Aq wollman@FreeBSD.org ,
247*433d6423SLionel Sambucand later completely rewritten to use the
248*433d6423SLionel Sambuc.Xr fetch 3
249*433d6423SLionel Sambuclibrary by
250*433d6423SLionel Sambuc.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
251*433d6423SLionel Sambuc.Sh NOTES
252*433d6423SLionel SambucThe
253*433d6423SLionel Sambuc.Fl b
254*433d6423SLionel Sambucand
255*433d6423SLionel Sambuc.Fl t
256*433d6423SLionel Sambucoptions are no longer supported and will generate warnings.
257*433d6423SLionel SambucThey were workarounds for bugs in other OSes which this implementation
258*433d6423SLionel Sambucdoes not trigger.
259*433d6423SLionel Sambuc.Pp
260*433d6423SLionel SambucOne cannot both use the
261*433d6423SLionel Sambuc.Fl h ,
262*433d6423SLionel Sambuc.Fl c ,
263*433d6423SLionel Sambucand
264*433d6423SLionel Sambuc.Fl f
265*433d6423SLionel Sambucoptions and specify URLs on the command line.
266