X-Git-Url: http://sjero.net/git/?p=wget;a=blobdiff_plain;f=doc%2Fwget.texi;h=2585d7ffc1bf535d6979db946d08fcde667c0538;hp=73fc527866990aa7202d821dbb9c12571f57109a;hb=edc9055768fed952b30629a9e8fa38ef68761882;hpb=e55befe5e204177c618bcbb9ea814ea8094bc48b diff --git a/doc/wget.texi b/doc/wget.texi index 73fc5278..2585d7ff 100644 --- a/doc/wget.texi +++ b/doc/wget.texi @@ -89,17 +89,17 @@ Info entry for @file{wget}. @end ifnottex @menu -* Overview:: Features of Wget. -* Invoking:: Wget command-line arguments. -* Recursive Download:: Downloading interlinked pages. -* Following Links:: The available methods of chasing links. -* Time-Stamping:: Mirroring according to time-stamps. -* Startup File:: Wget's initialization file. -* Examples:: Examples of usage. -* Various:: The stuff that doesn't fit anywhere else. -* Appendices:: Some useful references. -* Copying this manual:: You may give out copies of Wget and of this manual. -* Concept Index:: Topics covered by this manual. +* Overview:: Features of Wget. +* Invoking:: Wget command-line arguments. +* Recursive Download:: Downloading interlinked pages. +* Following Links:: The available methods of chasing links. +* Time-Stamping:: Mirroring according to time-stamps. +* Startup File:: Wget's initialization file. +* Examples:: Examples of usage. +* Various:: The stuff that doesn't fit anywhere else. +* Appendices:: Some useful references. +* Copying this manual:: You may give out copies of this manual. +* Concept Index:: Topics covered by this manual. @end menu @node Overview, Invoking, Top, Top @@ -235,17 +235,18 @@ command to @file{.wgetrc} (@pxref{Startup File}), or specifying it on the command line. @menu -* URL Format:: -* Option Syntax:: -* Basic Startup Options:: -* Logging and Input File Options:: -* Download Options:: -* Directory Options:: -* HTTP Options:: -* HTTPS (SSL/TLS) Options:: -* FTP Options:: -* Recursive Retrieval Options:: -* Recursive Accept/Reject Options:: +* URL Format:: +* Option Syntax:: +* Basic Startup Options:: +* Logging and Input File Options:: +* Download Options:: +* Directory Options:: +* HTTP Options:: +* HTTPS (SSL/TLS) Options:: +* FTP Options:: +* Recursive Retrieval Options:: +* Recursive Accept/Reject Options:: +* Exit Status:: @end menu @node URL Format, Option Syntax, Invoking, Invoking @@ -351,7 +352,7 @@ like: wget -drc @var{URL} @end example -This is a complete equivalent of: +This is completely equivalent to: @example wget -d -r -c @var{URL} @@ -904,24 +905,36 @@ won't need it. @cindex file names, restrict @cindex Windows file names -@item --restrict-file-names=@var{mode} -Change which characters found in remote URLs may show up in local file -names generated from those URLs. Characters that are @dfn{restricted} +@item --restrict-file-names=@var{modes} +Change which characters found in remote URLs must be escaped during +generation of local filenames. Characters that are @dfn{restricted} by this option are escaped, i.e. replaced with @samp{%HH}, where @samp{HH} is the hexadecimal number that corresponds to the restricted -character. - -By default, Wget escapes the characters that are not valid as part of -file names on your operating system, as well as control characters that -are typically unprintable. This option is useful for changing these -defaults, either because you are downloading to a non-native partition, -or because you want to disable escaping of the control characters. - -When mode is set to ``unix'', Wget escapes the character @samp{/} and +character. This option may also be used to force all alphabetical +cases to be either lower- or uppercase. + +By default, Wget escapes the characters that are not valid or safe as +part of file names on your operating system, as well as control +characters that are typically unprintable. This option is useful for +changing these defaults, perhaps because you are downloading to a +non-native partition, or because you want to disable escaping of the +control characters, or you want to further restrict characters to only +those in the @sc{ascii} range of values. + +The @var{modes} are a comma-separated set of text values. The +acceptable values are @samp{unix}, @samp{windows}, @samp{nocontrol}, +@samp{ascii}, @samp{lowercase}, and @samp{uppercase}. The values +@samp{unix} and @samp{windows} are mutually exclusive (one will +override the other), as are @samp{lowercase} and +@samp{uppercase}. Those last are special cases, as they do not change +the set of characters that would be escaped, but rather force local +file paths to be converted either to lower- or uppercase. + +When ``unix'' is specified, Wget escapes the character @samp{/} and the control characters in the ranges 0--31 and 128--159. This is the -default on Unix-like OS'es. +default on Unix-like operating systems. -When mode is set to ``windows'', Wget escapes the characters @samp{\}, +When ``windows'' is given, Wget escapes the characters @samp{\}, @samp{|}, @samp{/}, @samp{:}, @samp{?}, @samp{"}, @samp{*}, @samp{<}, @samp{>}, and the control characters in the ranges 0--31 and 128--159. In addition to this, Wget in Windows mode uses @samp{+} instead of @@ -932,11 +945,17 @@ name from the rest. Therefore, a URL that would be saved as saved as @samp{www.xemacs.org+4300/search.pl@@input=blah} in Windows mode. This mode is the default on Windows. -If you append @samp{,nocontrol} to the mode, as in -@samp{unix,nocontrol}, escaping of the control characters is also -switched off. You can use @samp{--restrict-file-names=nocontrol} to -turn off escaping of control characters without affecting the choice of -the OS to use as file name restriction mode. +If you specify @samp{nocontrol}, then the escaping of the control +characters is also switched off. This option may make sense +when you are downloading URLs whose names contain UTF-8 characters, on +a system which can save and display filenames in UTF-8 (some possible +byte values used in UTF-8 byte sequences fall in the range of values +designated by Wget as ``controls''). + +The @samp{ascii} mode is used to specify that any bytes whose values +are outside the range of @sc{ascii} characters (that is, greater than +127) shall be escaped. This can be useful when saving filenames +whose encoding does not match the one used locally. @cindex IPv6 @itemx -4 @@ -1130,8 +1149,9 @@ Use @var{name} as the default file name when it isn't known (i.e., for URLs that end in a slash), instead of @file{index.html}. @cindex .html extension +@cindex .css extension @item -E -@itemx --html-extension +@itemx --adjust-extension If a file of type @samp{application/xhtml+xml} or @samp{text/html} is downloaded and the URL does not end with the regexp @samp{\.[Hh][Tt][Mm][Ll]?}, this option will cause the suffix @samp{.html} @@ -1152,9 +1172,14 @@ version of the file will be saved as @file{@var{X}.orig} (@pxref{Recursive Retrieval Options}). As of version 1.12, Wget will also ensure that any downloaded files of -type @samp{text/css} end in the suffix @samp{.css}. Obviously, this -makes the name @samp{--html-extension} misleading; a better name is -expected to be offered as an alternative in the near future. +type @samp{text/css} end in the suffix @samp{.css}, and the option was +renamed from @samp{--html-extension}, to better reflect its new +behavior. The old option name is still acceptable, but should now be +considered deprecated. + +At some point in the future, this option may well be expanded to +include suffixes for other types of content, including content types +that are not parsed by Wget. @cindex http user @cindex http password @@ -1911,7 +1936,7 @@ If, for whatever reason, you want strict comment parsing, use this option to turn it on. @end table -@node Recursive Accept/Reject Options, , Recursive Retrieval Options, Invoking +@node Recursive Accept/Reject Options, Exit Status, Recursive Retrieval Options, Invoking @section Recursive Accept/Reject Options @table @samp @@ -2006,6 +2031,57 @@ This is a useful option, since it guarantees that only the files @c man end +@node Exit Status, , Recursive Accept/Reject Options, Invoking +@section Exit Status + +@c man begin EXITSTATUS + +Wget may return one of several error codes if it encounters problems. + + +@table @asis +@item 0 +No problems occurred. + +@item 1 +Generic error code. + +@item 2 +Parse error---for instance, when parsing command-line options, the +@samp{.wgetrc} or @samp{.netrc}... + +@item 3 +File I/O error. + +@item 4 +Network failure. + +@item 5 +SSL verification failure. + +@item 6 +Username/password authentication failure. + +@item 7 +Protocol errors. + +@item 8 +Server issued an error response. +@end table + + +With the exceptions of 0 and 1, the lower-numbered exit codes take +precedence over higher-numbered ones, when multiple types of errors +are encountered. + +In versions of Wget prior to 1.12, Wget's exit status tended to be +unhelpful and inconsistent. Recursive downloads would virtually always +return 0 (success), regardless of any issues encountered, and +non-recursive fetches only returned the status corresponding to the +most recently-attempted download. + +@c man end + @node Recursive Download, Following Links, Invoking, Top @chapter Recursive Download @cindex recursion @@ -2091,11 +2167,11 @@ Wget possesses several mechanisms that allows you to fine-tune which links it will follow. @menu -* Spanning Hosts:: (Un)limiting retrieval based on host name. -* Types of Files:: Getting only certain files. -* Directory-Based Limits:: Getting only certain directories. -* Relative Links:: Follow relative links only. -* FTP Links:: Following FTP links. +* Spanning Hosts:: (Un)limiting retrieval based on host name. +* Types of Files:: Getting only certain files. +* Directory-Based Limits:: Getting only certain directories. +* Relative Links:: Follow relative links only. +* FTP Links:: Following FTP links. @end menu @node Spanning Hosts, Types of Files, Following Links, Following Links @@ -2246,7 +2322,7 @@ ways, all of which can change whether an accept/reject rule matches: If the local file already exists and @samp{--no-directories} was specified, a numeric suffix will be appended to the original name. @item -If @samp{--html-extension} was specified, the local filename will have +If @samp{--adjust-extension} was specified, the local filename might have @samp{.html} appended to it. If Wget is invoked with @samp{-E -A.php}, a filename such as @samp{index.php} will match be accepted, but upon download will be named @samp{index.php.html}, which no longer matches, @@ -2438,9 +2514,9 @@ match, Wget will download the remote file no matter what the time-stamps say. @menu -* Time-Stamping Usage:: -* HTTP Time-Stamping Internals:: -* FTP Time-Stamping Internals:: +* Time-Stamping Usage:: +* HTTP Time-Stamping Internals:: +* FTP Time-Stamping Internals:: @end menu @node Time-Stamping Usage, HTTP Time-Stamping Internals, Time-Stamping, Time-Stamping @@ -2582,10 +2658,10 @@ Wget reads @file{.wgetrc} upon startup, recognizing a limited set of commands. @menu -* Wgetrc Location:: Location of various wgetrc files. -* Wgetrc Syntax:: Syntax of wgetrc. -* Wgetrc Commands:: List of available commands. -* Sample Wgetrc:: A wgetrc example. +* Wgetrc Location:: Location of various wgetrc files. +* Wgetrc Syntax:: Syntax of wgetrc. +* Wgetrc Commands:: List of available commands. +* Sample Wgetrc:: A wgetrc example. @end menu @node Wgetrc Location, Wgetrc Syntax, Startup File, Startup File @@ -2827,10 +2903,12 @@ Turn globbing on/off---the same as @samp{--glob} and @samp{--no-glob}. Define a header for HTTP downloads, like using @samp{--header=@var{string}}. -@item html_extension = on/off +@item adjust_extension = on/off Add a @samp{.html} extension to @samp{text/html} or -@samp{application/xhtml+xml} files without it, or a @samp{.css} -extension to @samp{text/css} files without it, like @samp{-E}. +@samp{application/xhtml+xml} files that lack one, or a @samp{.css} +extension to @samp{text/css} files that lack one, like +@samp{-E}. Previously named @samp{html_extension} (still acceptable, +but deprecated). @item http_keep_alive = on/off Turn the keep-alive feature on or off (defaults to on). Turning it @@ -3135,9 +3213,9 @@ The examples are divided into three sections loosely based on their complexity. @menu -* Simple Usage:: Simple, basic usage of the program. -* Advanced Usage:: Advanced tips. -* Very Advanced Usage:: The hairy stuff. +* Simple Usage:: Simple, basic usage of the program. +* Advanced Usage:: Advanced tips. +* Very Advanced Usage:: The hairy stuff. @end menu @node Simple Usage, Advanced Usage, Examples, Examples @@ -3385,14 +3463,14 @@ wget -m -k -K -E http://www.gnu.org/ -o /home/me/weeklog This chapter contains all the stuff that could not fit anywhere else. @menu -* Proxies:: Support for proxy servers. -* Distribution:: Getting the latest version. -* Web Site:: GNU Wget's presence on the World Wide Web. -* Mailing Lists:: Wget mailing list for announcements and discussion. -* Internet Relay Chat:: Wget's presence on IRC. -* Reporting Bugs:: How and where to report bugs. -* Portability:: The systems Wget works on. -* Signals:: Signal-handling performed by Wget. +* Proxies:: Support for proxy servers. +* Distribution:: Getting the latest version. +* Web Site:: GNU Wget's presence on the World Wide Web. +* Mailing Lists:: Wget mailing list for announcements and discussion. +* Internet Relay Chat:: Wget's presence on IRC. +* Reporting Bugs:: How and where to report bugs. +* Portability:: The systems Wget works on. +* Signals:: Signal-handling performed by Wget. @end menu @node Proxies, Distribution, Various, Various @@ -3674,9 +3752,9 @@ Other than that, Wget will not try to interfere with signals in any way. This chapter contains some references I consider useful. @menu -* Robot Exclusion:: Wget's support for RES. -* Security Considerations:: Security with Wget. -* Contributors:: People who helped. +* Robot Exclusion:: Wget's support for RES. +* Security Considerations:: Security with Wget. +* Contributors:: People who helped. @end menu @node Robot Exclusion, Security Considerations, Appendices, Appendices