/usr.bin/fetch/fetch.1
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 305 lines · 305 code · 0 blank · 0 comment · 0 complexity · 1604c0b2080a80e2d5204cb8c477721a MD5 · raw file
- .\"-
- .\" Copyright (c) 2000-2011 Dag-Erling Smørgrav
- .\" All rights reserved.
- .\" Portions Copyright (c) 1999 Massachusetts Institute of Technology; used
- .\" by permission.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer
- .\" in this position and unchanged.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\" 3. The name of the author may not be used to endorse or promote products
- .\" derived from this software without specific prior written permission.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
- .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
- .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
- .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
- .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
- .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
- .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- .\"
- .\" $FreeBSD$
- .\"
- .Dd September 27, 2011
- .Dt FETCH 1
- .Os
- .Sh NAME
- .Nm fetch
- .Nd retrieve a file by Uniform Resource Locator
- .Sh SYNOPSIS
- .Nm
- .Op Fl 146AadFlMmnPpqRrsUv
- .Op Fl B Ar bytes
- .Op Fl i Ar file
- .Op Fl N Ar file
- .Op Fl o Ar file
- .Op Fl S Ar bytes
- .Op Fl T Ar seconds
- .Op Fl w Ar seconds
- .Ar URL ...
- .Nm
- .Op Fl 146AadFlMmnPpqRrsUv
- .Op Fl B Ar bytes
- .Op Fl i Ar file
- .Op Fl N Ar file
- .Op Fl o Ar file
- .Op Fl S Ar bytes
- .Op Fl T Ar seconds
- .Op Fl w Ar seconds
- .Fl h Ar host Fl f Ar file Oo Fl c Ar dir Oc
- .Sh DESCRIPTION
- The
- .Nm
- utility provides a command-line interface to the
- .Xr fetch 3
- library.
- Its purpose is to retrieve the file(s) pointed to by the URL(s) on the
- command line.
- .Pp
- The following options are available:
- .Bl -tag -width Fl
- .It Fl 1
- Stop and return exit code 0 at the first successfully retrieved file.
- .It Fl 4
- Forces
- .Nm
- to use IPv4 addresses only.
- .It Fl 6
- Forces
- .Nm
- to use IPv6 addresses only.
- .It Fl A
- Do not automatically follow ``temporary'' (302) redirects.
- Some broken Web sites will return a redirect instead of a not-found
- error when the requested object does not exist.
- .It Fl a
- Automatically retry the transfer upon soft failures.
- .It Fl B Ar bytes
- Specify the read buffer size in bytes.
- The default is 4096 bytes.
- Attempts to set a buffer size lower than this will be silently
- ignored.
- The number of reads actually performed is reported at verbosity level
- two or higher (see the
- .Fl v
- flag).
- .It Fl c Ar dir
- The file to retrieve is in directory
- .Ar dir
- on the remote host.
- This option is deprecated and is provided for backward compatibility
- only.
- .It Fl d
- Use a direct connection even if a proxy is configured.
- .It Fl F
- In combination with the
- .Fl r
- flag, forces a restart even if the local and remote files have
- different modification times.
- Implies
- .Fl R .
- .It Fl f Ar file
- The file to retrieve is named
- .Ar file
- on the remote host.
- This option is deprecated and is provided for backward compatibility
- only.
- .It Fl h Ar host
- The file to retrieve is located on the host
- .Ar host .
- This option is deprecated and is provided for backward compatibility
- only.
- .It Fl i Ar file
- If-Modified-Since mode: the remote file will only be retrieved if it
- is newer than
- .Ar file
- on the local host.
- (HTTP only)
- .It Fl l
- If the target is a file-scheme URL, make a symbolic link to the target
- rather than trying to copy it.
- .It Fl M
- .It Fl m
- Mirror mode: if the file already exists locally and has the same size
- and modification time as the remote file, it will not be fetched.
- Note that the
- .Fl m
- and
- .Fl r
- flags are mutually exclusive.
- .It Fl N Ar file
- Use
- .Ar file
- instead of
- .Pa ~/.netrc
- to look up login names and passwords for FTP sites.
- See
- .Xr ftp 1
- for a description of the file format.
- This feature is experimental.
- .It Fl n
- Do not preserve the modification time of the transferred file.
- .It Fl o Ar file
- Set the output file name to
- .Ar file .
- By default, a ``pathname'' is extracted from the specified URI, and
- its basename is used as the name of the output file.
- A
- .Ar file
- argument of
- .Sq Li \&-
- indicates that results are to be directed to the standard output.
- If the
- .Ar file
- argument is a directory, fetched file(s) will be placed within the
- directory, with name(s) selected as in the default behaviour.
- .It Fl P
- .It Fl p
- Use passive FTP.
- These flags have no effect, since passive FTP is the default, but are
- provided for compatibility with earlier versions where active FTP was
- the default.
- To force active mode, set the
- .Ev FTP_PASSIVE_MODE
- environment variable to
- .Ql NO .
- .It Fl q
- Quiet mode.
- .It Fl R
- The output files are precious, and should not be deleted under any
- circumstances, even if the transfer failed or was incomplete.
- .It Fl r
- Restart a previously interrupted transfer.
- Note that the
- .Fl m
- and
- .Fl r
- flags are mutually exclusive.
- .It Fl S Ar bytes
- Require the file size reported by the server to match the specified
- value.
- If it does not, a message is printed and the file is not fetched.
- If the server does not support reporting file sizes, this option is
- ignored and the file is fetched unconditionally.
- .It Fl s
- Print the size in bytes of each requested file, without fetching it.
- .It Fl T Ar seconds
- Set timeout value to
- .Ar seconds .
- Overrides the environment variables
- .Ev FTP_TIMEOUT
- for FTP transfers or
- .Ev HTTP_TIMEOUT
- for HTTP transfers if set.
- .It Fl U
- When using passive FTP, allocate the port for the data connection from
- the low (default) port range.
- See
- .Xr ip 4
- for details on how to specify which port range this corresponds to.
- .It Fl v
- Increase verbosity level.
- .It Fl w Ar seconds
- When the
- .Fl a
- flag is specified, wait this many seconds between successive retries.
- .El
- .Pp
- If
- .Nm
- receives a
- .Dv SIGINFO
- signal (see the
- .Cm status
- argument for
- .Xr stty 1 ) ,
- the current transfer rate statistics will be written to the
- standard error output, in the same format as the standard completion
- message.
- .Sh ENVIRONMENT
- .Bl -tag -width HTTP_TIMEOUT
- .It Ev FTP_TIMEOUT
- Maximum time, in seconds, to wait before aborting an FTP connection.
- .It Ev HTTP_TIMEOUT
- Maximum time, in seconds, to wait before aborting an HTTP connection.
- .El
- .Pp
- See
- .Xr fetch 3
- for a description of additional environment variables, including
- .Ev FETCH_BIND_ADDRESS ,
- .Ev FTP_LOGIN ,
- .Ev FTP_PASSIVE_MODE ,
- .Ev FTP_PASSWORD ,
- .Ev FTP_PROXY ,
- .Ev ftp_proxy ,
- .Ev HTTP_AUTH ,
- .Ev HTTP_PROXY ,
- .Ev http_proxy ,
- .Ev HTTP_PROXY_AUTH ,
- .Ev HTTP_REFERER ,
- .Ev HTTP_USER_AGENT ,
- .Ev NETRC ,
- .Ev NO_PROXY No and
- .Ev no_proxy .
- .Sh EXIT STATUS
- The
- .Nm
- command returns zero on success, or one on failure.
- If multiple URLs are listed on the command line,
- .Nm
- will attempt to retrieve each one of them in turn, and will return
- zero only if they were all successfully retrieved.
- .Pp
- If the
- .Fl i
- argument is used and the remote file is not newer than the
- specified file then the command will still return success,
- although no file is transferred.
- .Sh SEE ALSO
- .Xr fetch 3
- .Sh HISTORY
- The
- .Nm
- command appeared in
- .Fx 2.1.5 .
- This implementation first appeared in
- .Fx 4.1 .
- .Sh AUTHORS
- .An -nosplit
- The original implementation of
- .Nm
- was done by
- .An Jean-Marc Zucconi Aq jmz@FreeBSD.org .
- It was extensively re-worked for
- .Fx 2.2
- by
- .An Garrett Wollman Aq wollman@FreeBSD.org ,
- and later completely rewritten to use the
- .Xr fetch 3
- library by
- .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
- .Sh NOTES
- The
- .Fl b
- and
- .Fl t
- options are no longer supported and will generate warnings.
- They were workarounds for bugs in other OSes which this implementation
- does not trigger.
- .Pp
- One cannot both use the
- .Fl h ,
- .Fl c
- and
- .Fl f
- options and specify URLs on the command line.