xref: /freebsd/usr.bin/fetch/fetch.1 (revision 6c7216df785592bb069469113f556dfd1946ed5d)
1b39628e7SDag-Erling Smørgrav.\"-
22cbbf9daSDag-Erling Smørgrav.\" Copyright (c) 2000-2004 Dag-Erling Co�dan Sm�rgrav
3b39628e7SDag-Erling Smørgrav.\" All rights reserved.
4114c3c1aSDag-Erling Smørgrav.\" Portions Copyright (c) 1999 Massachusetts Institute of Technology; used
5114c3c1aSDag-Erling Smørgrav.\" by permission.
6b39628e7SDag-Erling Smørgrav.\"
7b39628e7SDag-Erling Smørgrav.\" Redistribution and use in source and binary forms, with or without
8b39628e7SDag-Erling Smørgrav.\" modification, are permitted provided that the following conditions
9b39628e7SDag-Erling Smørgrav.\" are met:
10b39628e7SDag-Erling Smørgrav.\" 1. Redistributions of source code must retain the above copyright
11b39628e7SDag-Erling Smørgrav.\"    notice, this list of conditions and the following disclaimer
12b39628e7SDag-Erling Smørgrav.\"    in this position and unchanged.
13b39628e7SDag-Erling Smørgrav.\" 2. Redistributions in binary form must reproduce the above copyright
14b39628e7SDag-Erling Smørgrav.\"    notice, this list of conditions and the following disclaimer in the
15b39628e7SDag-Erling Smørgrav.\"    documentation and/or other materials provided with the distribution.
16b39628e7SDag-Erling Smørgrav.\" 3. The name of the author may not be used to endorse or promote products
17b39628e7SDag-Erling Smørgrav.\"    derived from this software without specific prior written permission.
18b39628e7SDag-Erling Smørgrav.\"
19b39628e7SDag-Erling Smørgrav.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20b39628e7SDag-Erling Smørgrav.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21b39628e7SDag-Erling Smørgrav.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22b39628e7SDag-Erling Smørgrav.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23b39628e7SDag-Erling Smørgrav.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24b39628e7SDag-Erling Smørgrav.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25b39628e7SDag-Erling Smørgrav.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26b39628e7SDag-Erling Smørgrav.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27b39628e7SDag-Erling Smørgrav.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28b39628e7SDag-Erling Smørgrav.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29b39628e7SDag-Erling Smørgrav.\"
30c3aac50fSPeter Wemm.\" $FreeBSD$
31b39628e7SDag-Erling Smørgrav.\"
326ce729e1SRuslan Ermilov.Dd March 11, 2003
337fefc698SJordan K. Hubbard.Dt FETCH 1
34b39628e7SDag-Erling Smørgrav.Os
357fefc698SJordan K. Hubbard.Sh NAME
367fefc698SJordan K. Hubbard.Nm fetch
377fefc698SJordan K. Hubbard.Nd retrieve a file by Uniform Resource Locator
387fefc698SJordan K. Hubbard.Sh SYNOPSIS
39b39628e7SDag-Erling Smørgrav.Nm
407c480c6cSDag-Erling Smørgrav.Op Fl 146AFMPRUadlmnpqrsv
41b39628e7SDag-Erling Smørgrav.Op Fl B Ar bytes
42b39628e7SDag-Erling Smørgrav.Op Fl S Ar bytes
43b39628e7SDag-Erling Smørgrav.Op Fl T Ar seconds
447dcb0a0eSDag-Erling Smørgrav.Op Fl N Ar file
457fefc698SJordan K. Hubbard.Op Fl o Ar file
46b39628e7SDag-Erling Smørgrav.Op Fl w Ar seconds
47047843ddSDag-Erling Smørgrav.Op Fl h Ar host
48047843ddSDag-Erling Smørgrav.Op Fl c Ar dir
49047843ddSDag-Erling Smørgrav.Op Fl f Ar file
50047843ddSDag-Erling Smørgrav.Op Ar URL ...
517fefc698SJordan K. Hubbard.Sh DESCRIPTION
523898680cSPhilippe CharnierThe
533898680cSPhilippe Charnier.Nm
543898680cSPhilippe Charnierutility provides a command-line interface to the
55b39628e7SDag-Erling Smørgrav.Xr fetch 3
56b39628e7SDag-Erling Smørgravlibrary.
57b39628e7SDag-Erling SmørgravIts purpose is to retrieve the file(s) pointed to by the URL(s) on the
58b39628e7SDag-Erling Smørgravcommand line.
597fefc698SJordan K. Hubbard.Pp
607fefc698SJordan K. HubbardThe following options are available:
6176dafb89SGarrett Wollman.Bl -tag -width Fl
62b39628e7SDag-Erling Smørgrav.It Fl \&1
63b39628e7SDag-Erling SmørgravStop and return exit code 0 at the first successfully retrieved file.
64b39628e7SDag-Erling Smørgrav.It Fl 4
65b39628e7SDag-Erling SmørgravForces
66b39628e7SDag-Erling Smørgrav.Nm
67b39628e7SDag-Erling Smørgravto use IPv4 addresses only.
68b39628e7SDag-Erling Smørgrav.It Fl 6
69b39628e7SDag-Erling SmørgravForces
70b39628e7SDag-Erling Smørgrav.Nm
71b39628e7SDag-Erling Smørgravto use IPv6 addresses only.
72189da044SGarrett Wollman.It Fl A
73b39628e7SDag-Erling SmørgravDo not automatically follow ``temporary'' (302) redirects.
74b39628e7SDag-Erling SmørgravSome broken Web sites will return a redirect instead of a not-found
75b39628e7SDag-Erling Smørgraverror when the requested object does not exist.
762494e810SGarrett Wollman.It Fl a
772494e810SGarrett WollmanAutomatically retry the transfer upon soft failures.
78b39628e7SDag-Erling Smørgrav.It Fl B Ar bytes
79b39628e7SDag-Erling SmørgravSpecify the read buffer size in bytes.
80b39628e7SDag-Erling SmørgravThe default is 4096 bytes.
81b39628e7SDag-Erling SmørgravAttempts to set a buffer size lower than this will be silently
82b39628e7SDag-Erling Smørgravignored.
83b39628e7SDag-Erling SmørgravThe number of reads actually performed is reported at verbosity level
84b39628e7SDag-Erling Smørgravtwo or higher (see the
85b39628e7SDag-Erling Smørgrav.Fl v
86b39628e7SDag-Erling Smørgravflag).
8778be3199SGarrett Wollman.It Fl c Ar dir
8878be3199SGarrett WollmanThe file to retrieve is in directory
8978be3199SGarrett Wollman.Ar dir
9078be3199SGarrett Wollmanon the remote host.
91047843ddSDag-Erling SmørgravThis option is deprecated and is provided for backward compatibility
92047843ddSDag-Erling Smørgravonly.
93047843ddSDag-Erling Smørgrav.It Fl d
94047843ddSDag-Erling SmørgravUse a direct connection even if a proxy is configured.
95d6a8296aSBrian Feldman.It Fl F
96b39628e7SDag-Erling SmørgravIn combination with the
97d6a8296aSBrian Feldman.Fl r
98b39628e7SDag-Erling Smørgravflag, forces a restart even if the local and remote files have
99b39628e7SDag-Erling Smørgravdifferent modification times.
1001bbb80b6SDag-Erling SmørgravImplies
1011bbb80b6SDag-Erling Smørgrav.Fl R .
10278be3199SGarrett Wollman.It Fl f Ar file
10378be3199SGarrett WollmanThe file to retrieve is named
10478be3199SGarrett Wollman.Ar file
10578be3199SGarrett Wollmanon the remote host.
106047843ddSDag-Erling SmørgravThis option is deprecated and is provided for backward compatibility
107047843ddSDag-Erling Smørgravonly.
10878be3199SGarrett Wollman.It Fl h Ar host
10978be3199SGarrett WollmanThe file to retrieve is located on the host
11078be3199SGarrett Wollman.Ar host .
111047843ddSDag-Erling SmørgravThis option is deprecated and is provided for backward compatibility
112047843ddSDag-Erling Smørgravonly.
11378be3199SGarrett Wollman.It Fl l
114b39628e7SDag-Erling SmørgravIf the target is a file-scheme URL, make a symbolic link to the target
115b39628e7SDag-Erling Smørgravrather than trying to copy it.
1167fefc698SJordan K. Hubbard.It Fl M
1177fefc698SJordan K. Hubbard.It Fl m
1180b474bc6SDag-Erling SmørgravMirror mode: if the file already exists locally and has the same size
1190b474bc6SDag-Erling Smørgravand modification time as the remote file, it will not be fetched.
120c0b0d54eSDag-Erling SmørgravNote that the
121c0b0d54eSDag-Erling Smørgrav.Fl m
122c0b0d54eSDag-Erling Smørgravand
123c0b0d54eSDag-Erling Smørgrav.Fl r
124c0b0d54eSDag-Erling Smørgravflags are mutually exclusive.
1257dcb0a0eSDag-Erling Smørgrav.It Fl N Ar file
1267dcb0a0eSDag-Erling SmørgravUse
1277dcb0a0eSDag-Erling Smørgrav.Ar file
1287dcb0a0eSDag-Erling Smørgravinstead of
1297dcb0a0eSDag-Erling Smørgrav.Pa ~/.netrc
1307dcb0a0eSDag-Erling Smørgravto look up login names and passwords for FTP sites.
1317dcb0a0eSDag-Erling SmørgravSee
1327dcb0a0eSDag-Erling Smørgrav.Xr ftp 1
1337dcb0a0eSDag-Erling Smørgravfor a description of the file format.
1347dcb0a0eSDag-Erling SmørgravThis feature is experimental.
1356b5c2db2SJordan K. Hubbard.It Fl n
1360b474bc6SDag-Erling SmørgravDon't preserve the modification time of the transferred file.
13778be3199SGarrett Wollman.It Fl o Ar file
13878be3199SGarrett WollmanSet the output file name to
13978be3199SGarrett Wollman.Ar file .
14078be3199SGarrett WollmanBy default, a ``pathname'' is extracted from the specified URI, and
141b39628e7SDag-Erling Smørgravits basename is used as the name of the output file.
142b39628e7SDag-Erling SmørgravA
14378be3199SGarrett Wollman.Ar file
14478be3199SGarrett Wollmanargument of
14578be3199SGarrett Wollman.Sq Li \&-
14678be3199SGarrett Wollmanindicates that results are to be directed to the standard output.
147fe6a0485SColin PercivalIf the
148fe6a0485SColin Percival.Ar file
149fe6a0485SColin Percivalargument is a directory, fetched file(s) will be placed within the
150fe6a0485SColin Percivaldirectory, with name(s) selected as in the default behaviour.
1517fefc698SJordan K. Hubbard.It Fl P
1527fefc698SJordan K. Hubbard.It Fl p
153b39628e7SDag-Erling SmørgravUse passive FTP.
154b39628e7SDag-Erling SmørgravThis is useful if you are behind a firewall which blocks incoming
155b39628e7SDag-Erling Smørgravconnections.
156b39628e7SDag-Erling SmørgravTry this flag if
157b39628e7SDag-Erling Smørgrav.Nm
158b39628e7SDag-Erling Smørgravseems to hang when retrieving FTP URLs.
15978be3199SGarrett Wollman.It Fl q
16087faa07bSSheldon HearnQuiet mode.
16178be3199SGarrett Wollman.It Fl R
162b39628e7SDag-Erling SmørgravThe output files are precious, and should not be deleted under any
163b39628e7SDag-Erling Smørgravcircumstances, even if the transfer failed or was incomplete.
16478be3199SGarrett Wollman.It Fl r
16578be3199SGarrett WollmanRestart a previously interrupted transfer.
166c0b0d54eSDag-Erling SmørgravNote that the
167c0b0d54eSDag-Erling Smørgrav.Fl m
168c0b0d54eSDag-Erling Smørgravand
169c0b0d54eSDag-Erling Smørgrav.Fl r
170c0b0d54eSDag-Erling Smørgravflags are mutually exclusive.
1710637c2ccSJordan K. Hubbard.It Fl S Ar bytes
172b39628e7SDag-Erling SmørgravRequire the file size reported by the server to match the specified
173b39628e7SDag-Erling Smørgravvalue.
174b39628e7SDag-Erling SmørgravIf it does not, a message is printed and the file is not fetched.
175b39628e7SDag-Erling SmørgravIf the server does not support reporting file sizes, this option is
176b39628e7SDag-Erling Smørgravignored and the file is fetched unconditionally.
177b451f452SMartin Cracauer.It Fl s
178b39628e7SDag-Erling SmørgravPrint the size in bytes of each requested file, without fetching it.
179fc6fcbf9SJordan K. Hubbard.It Fl T Ar seconds
180fc6fcbf9SJordan K. HubbardSet timeout value to
181fc6fcbf9SJordan K. Hubbard.Ar seconds .
182a43a248cSPeter WemmOverrides the environment variables
183fc6fcbf9SJordan K. Hubbard.Ev FTP_TIMEOUT
184b39628e7SDag-Erling Smørgravfor FTP transfers or
185a43a248cSPeter Wemm.Ev HTTP_TIMEOUT
186b39628e7SDag-Erling Smørgravfor HTTP transfers if set.
1877c480c6cSDag-Erling Smørgrav.It Fl U
1887c480c6cSDag-Erling SmørgravWhen using passive FTP, allocate the port for the data connection from
1897c480c6cSDag-Erling Smørgravthe low (default) port range.
1907c480c6cSDag-Erling SmørgravSee
1917c480c6cSDag-Erling Smørgrav.Xr ip 4
1927c480c6cSDag-Erling Smørgravfor details on how to specify which port range this corresponds to.
1937ae26f14SJordan K. Hubbard.It Fl v
19438a616e4SDag-Erling SmørgravIncrease verbosity level.
195b39628e7SDag-Erling Smørgrav.It Fl w Ar seconds
196b39628e7SDag-Erling SmørgravWhen the
197b39628e7SDag-Erling Smørgrav.Fl a
198b39628e7SDag-Erling Smørgravflag is specified, wait this many seconds between successive retries.
1997fefc698SJordan K. Hubbard.El
200ab47d799SRuslan Ermilov.Pp
201ab47d799SRuslan ErmilovIf
202ab47d799SRuslan Ermilov.Nm
203ab47d799SRuslan Ermilovreceives a
204ab47d799SRuslan Ermilov.Dv SIGINFO
205ab47d799SRuslan Ermilovsignal (see the
206ab47d799SRuslan Ermilov.Cm status
207ab47d799SRuslan Ermilovargument for
208ab47d799SRuslan Ermilov.Xr stty 1 ) ,
209ab47d799SRuslan Ermilovthe current transfer rate statistics will be written to the
210ab47d799SRuslan Ermilovstandard error output, in the same format as the standard completion
211ab47d799SRuslan Ermilovmessage.
2127fefc698SJordan K. Hubbard.Sh ENVIRONMENT
21309d2d42eSWes Peters.Bl -tag -width HTTP_TIMEOUT
21409d2d42eSWes Peters.It Ev FTP_TIMEOUT
21509d2d42eSWes Petersmaximum time, in seconds, to wait before aborting an FTP connection.
21609d2d42eSWes Peters.It Ev HTTP_TIMEOUT
2174bdd89baSRuslan Ermilovmaximum time, in seconds, to wait before aborting an HTTP connection.
218cec5287bSWes Peters.El
21909d2d42eSWes Peters.Pp
22009d2d42eSWes PetersAll environment variables mentioned in the documentation for the
22109d2d42eSWes Peters.Xr fetch 3
222fbcf5e65SWes Peterslibrary are supported.
223fbcf5e65SWes PetersA number of these are quite important to the proper operation of
22409d2d42eSWes Peters.Nm ;
22509d2d42eSWes Petersyou are strongly encouraged to read
22609d2d42eSWes Peters.Xr fetch 3
22709d2d42eSWes Petersas well.
2286c7216dfSRuslan Ermilov.Sh EXIT STATUS
2296c7216dfSRuslan ErmilovThe
2306c7216dfSRuslan Ermilov.Nm
2316c7216dfSRuslan Ermilovcommand returns zero on success, or one on failure.
2326c7216dfSRuslan ErmilovIf multiple URLs are listed on the command line,
2336c7216dfSRuslan Ermilov.Nm
2346c7216dfSRuslan Ermilovwill attempt to retrieve them each of them in turn, and return zero
2356c7216dfSRuslan Ermilovonly if they were all successfully retrieved.
2367fefc698SJordan K. Hubbard.Sh SEE ALSO
237b39628e7SDag-Erling Smørgrav.Xr fetch 3
2387fefc698SJordan K. Hubbard.Sh HISTORY
2397fefc698SJordan K. HubbardThe
240b39628e7SDag-Erling Smørgrav.Nm
24185cf659aSMike Pritchardcommand appeared in
24285cf659aSMike Pritchard.Fx 2.1.5 .
243b39628e7SDag-Erling SmørgravThis implementation first appeared in
244b39628e7SDag-Erling Smørgrav.Fx 4.1 .
24578be3199SGarrett Wollman.Sh AUTHORS
246f4d874a1SRuslan Ermilov.An -nosplit
24778be3199SGarrett WollmanThe original implementation of
24878be3199SGarrett Wollman.Nm
249306005e7SPhilippe Charnierwas done by
25009e06539SDag-Erling Smørgrav.An Jean-Marc Zucconi Aq jmz@FreeBSD.org .
251306005e7SPhilippe CharnierIt was extensively re-worked for
252bc5d5816SWolfram Schneider.Fx 2.2
253306005e7SPhilippe Charnierby
25409e06539SDag-Erling Smørgrav.An Garrett Wollman Aq wollman@FreeBSD.org ,
255b39628e7SDag-Erling Smørgravand later completely rewritten to use the
256b39628e7SDag-Erling Smørgrav.Xr fetch 3
257b39628e7SDag-Erling Smørgravlibrary by
25890ffd7eaSDag-Erling Smørgrav.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
259b39628e7SDag-Erling Smørgrav.Sh NOTES
2602494e810SGarrett WollmanThe
2610c8cc99eSGarrett Wollman.Fl b
262b39628e7SDag-Erling Smørgravand
263b39628e7SDag-Erling Smørgrav.Fl t
264b39628e7SDag-Erling Smørgravoptions are no longer supported and will generate warnings.
265b39628e7SDag-Erling SmørgravThey were workarounds for bugs in other OSes which this implementation
266b39628e7SDag-Erling Smørgravdoes not trigger.
267c1468430SGarrett Wollman.Pp
268047843ddSDag-Erling SmørgravOne cannot both use the
269047843ddSDag-Erling Smørgrav.Fl h ,
270cf575052SBen Smithurst.Fl c
271cf575052SBen Smithurstand
272b39628e7SDag-Erling Smørgrav.Fl f
273047843ddSDag-Erling Smørgravoptions and specify URLs on the command line.
274