2 @setfilename ../../info/url
3 @settitle URL Programmer's Manual
8 @c @setchapternewpage odd
13 %\global\baselineskip 30pt % for printing in double space
15 @dircategory World Wide Web
18 * URL: (url). URL loading package.
22 This file documents the Emacs Lisp URL loading package.
24 Copyright @copyright{} 1993-1999, 2002, 2004-2011 Free Software Foundation, Inc.
27 Permission is granted to copy, distribute and/or modify this document
28 under the terms of the GNU Free Documentation License, Version 1.3 or
29 any later version published by the Free Software Foundation; with no
30 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
31 and with the Back-Cover Texts as in (a) below. A copy of the license
32 is included in the section entitled ``GNU Free Documentation License''.
34 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
35 modify this GNU manual. Buying copies from the FSF supports it in
36 developing GNU and promoting software freedom.''
42 @title URL Programmer's Manual
43 @subtitle First Edition, URL Version 2.0
44 @author William M. Perry @email{wmperry@@gnu.org}
45 @author David Love @email{fx@@gnu.org}
47 @vskip 0pt plus 1filll
61 * Getting Started:: Preparing your program to use URLs.
62 * Retrieving URLs:: How to use this package to retrieve a URL.
63 * Supported URL Types:: Descriptions of URL types currently supported.
64 * Defining New URLs:: How to define a URL loader for a new protocol.
65 * General Facilities:: URLs can be cached, accessed via a gateway
66 and tracked in a history list.
67 * Customization:: Variables you can alter.
68 * GNU Free Documentation License:: The license for this documentation.
75 @chapter Getting Started
76 @cindex URLs, definition
79 @dfn{Uniform Resource Locators} (URLs) are a specific form of
80 @dfn{Uniform Resource Identifiers} (URI) described in RFC 2396 which
81 updates RFC 1738 and RFC 1808. RFC 2016 defines uniform resource
84 URIs have the form @var{scheme}:@var{scheme-specific-part}, where the
85 @var{scheme}s supported by this library are described below.
86 @xref{Supported URL Types}.
88 FTP, NFS, HTTP, HTTPS, @code{rlogin}, @code{telnet}, tn3270,
89 IRC and gopher URLs all have the form
92 @var{scheme}://@r{[}@var{userinfo}@@@r{]}@var{hostname}@r{[}:@var{port}@r{]}@r{[}/@var{path}@r{]}
95 where @samp{@r{[}} and @samp{@r{]}} delimit optional parts.
96 @var{userinfo} sometimes takes the form @var{username}:@var{password}
97 but you should beware of the security risks of sending cleartext
98 passwords. @var{hostname} may be a domain name or a dotted decimal
99 address. If the @samp{:@var{port}} is omitted then the library will
100 use the `well known' port for that service when accessing URLs. With
101 the possible exception of @code{telnet}, it is rare for ports to be
102 specified, and it is possible using a non-standard port may have
103 undesired consequences if a different service is listening on that
104 port (e.g., an HTTP URL specifying the SMTP port can cause mail to be
105 sent). @c , but @xref{Other Variables, url-bad-port-list}.
106 The meaning of the @var{path} component depends on the service.
110 * Parsed URLs:: URLs are parsed into vector structures.
114 @section Configuration
116 @defvar url-configuration-directory
117 @cindex @file{~/.url}
118 @cindex configuration files
119 The directory in which URL configuration files, the cache etc.,
120 reside. Default @file{~/.url}.
126 The library functions typically operate on @dfn{parsed} versions of
127 URLs. These are actually vectors of the form:
130 [@var{type} @var{user} @var{password} @var{host} @var{port} @var{file} @var{target} @var{attributes} @var{full}]
136 is the type of the URL scheme, e.g., @code{http}
138 is the username associated with it, or @code{nil};
140 is the user password associated with it, or @code{nil};
142 is the host name associated with it, or @code{nil};
144 is the port number associated with it, or @code{nil};
146 is the `file' part of it, or @code{nil}. This doesn't necessarily
147 actually refer to a file;
149 is the target part, or @code{nil};
151 is the attributes associated with it, or @code{nil};
153 is @code{t} for a fully-specified URL, with a host part indicated by
154 @samp{//} after the scheme part.
164 @findex url-attributes
168 @findex url-set-password
172 @findex url-set-target
173 @findex url-set-attributes
175 These attributes have accessors named @code{url-@var{part}}, where
176 @var{part} is the name of one of the elements above, e.g.,
177 @code{url-host}. Similarly, there are setters of the form
178 @code{url-set-@var{part}}.
180 There are functions for parsing and unparsing between the string and
183 @defun url-generic-parse-url url
184 Return a parsed version of the string @var{url}.
187 @defun url-recreate-url url
188 @cindex unparsing URLs
189 Recreates a URL string from the parsed @var{url}.
192 @node Retrieving URLs
193 @chapter Retrieving URLs
195 @defun url-retrieve-synchronously url
196 Retrieve @var{url} synchronously and return a buffer containing the
197 data. @var{url} is either a string or a parsed URL structure. Return
198 @code{nil} if there are no data associated with it (the case for dired,
199 info, or mailto URLs that need no further processing).
202 @defun url-retrieve url callback &optional cbargs
203 Retrieve @var{url} asynchronously and call @var{callback} with args
204 @var{cbargs} when finished. The callback is called when the object
205 has been completely retrieved, with the current buffer containing the
206 object and any MIME headers associated with it. @var{url} is either a
207 string or a parsed URL structure. Returns the buffer @var{url} will
208 load into, or @code{nil} if the process has already completed.
211 @node Supported URL Types
212 @chapter Supported URL Types
215 * http/https:: Hypertext Transfer Protocol.
216 * file/ftp:: Local files and FTP archives.
217 * info:: Emacs `Info' pages.
218 * mailto:: Sending email.
219 * news/nntp/snews:: Usenet news.
220 * rlogin/telnet/tn3270:: Remote host connectivity.
221 * irc:: Internet Relay Chat.
222 * data:: Embedded data URLs.
223 * nfs:: Networked File System
230 * ldap:: Lightweight Directory Access Protocol
231 * imap:: IMAP mailboxes.
232 * man:: Unix man pages.
236 @section @code{http} and @code{https}
238 The scheme @code{http} is Hypertext Transfer Protocol. The library
239 supports version 1.1, specified in RFC 2616. (This supersedes 1.0,
240 defined in RFC 1945) HTTP URLs have the following form, where most of
241 the parts are optional:
243 http://@var{user}:@var{password}@@@var{host}:@var{port}/@var{path}?@var{searchpart}#@var{fragment}
245 @c The @code{:@var{port}} part is optional, and @var{port} defaults to
246 @c 80. The @code{/@var{path}} part, if present, is a slash-separated
247 @c series elements. The @code{?@var{searchpart}}, if present, is the
248 @c query for a search or the content of a form submission. The
249 @c @code{#fragment} part, if present, is a location in the document.
251 The scheme @code{https} is a secure version of @code{http}, with
252 transmission via SSL. It is defined in RFC 2069. Its default port is
253 443. This scheme depends on SSL support in Emacs via the
254 @file{ssl.el} library and is actually implemented by forcing the
255 @code{ssl} gateway method to be used. @xref{Gateways in general}.
257 @defopt url-honor-refresh-requests
258 This controls honoring of HTTP @samp{Refresh} headers by which
259 servers can direct clients to reload documents from the same URL or a
260 or different one. @code{nil} means they will not be honored,
261 @code{t} (the default) means they will always be honored, and
262 otherwise the user will be asked on each request.
268 * HTTP language/coding::
270 * Dealing with HTTP documents::
276 @defopt url-cookie-file
277 The file in which cookies are stored, defaulting to @file{cookies} in
278 the directory specified by @code{url-configuration-directory}.
281 @defopt url-cookie-confirmation
282 Specifies whether confirmation is require to accept cookies.
285 @defopt url-cookie-multiple-line
286 Specifies whether to put all cookies for the server on one line in the
287 HTTP request to satisfy broken servers like
288 @url{http://www.hotmail.com}.
291 @defopt url-cookie-trusted-urls
292 A list of regular expressions matching URLs from which to accept
296 @defopt url-cookie-untrusted-urls
297 A list of regular expressions matching URLs from which to reject
301 @defopt url-cookie-save-interval
302 The number of seconds between automatic saves of cookies to disk.
307 @node HTTP language/coding
308 @subsection Language and Encoding Preferences
310 HTTP allows clients to express preferences for the language and
311 encoding of documents which servers may honor. For each of these
312 variables, the value is a string; it can specify a single choice, or
313 it can be a comma-separated list.
315 Normally, this list is ordered by descending preference. However, each
316 element can be followed by @samp{;q=@var{priority}} to specify its
317 preference level, a decimal number from 0 to 1; e.g., for
318 @code{url-mime-language-string}, @w{@code{"de, en-gb;q=0.8,
319 en;q=0.7"}}. An element that has no @samp{;q} specification has
322 @defopt url-mime-charset-string
323 @cindex character sets
324 @cindex coding systems
325 This variable specifies a preference for character sets when documents
326 can be served in more than one encoding.
328 HTTP allows specifying a series of MIME charsets which indicate your
329 preferred character set encodings, e.g., Latin-9 or Big5, and these
330 can be weighted. The default series is generated automatically from
331 the associated MIME types of all defined coding systems, sorted by the
332 coding system priority specified in Emacs. @xref{Recognize Coding, ,
333 Recognizing Coding Systems, emacs, The GNU Emacs Manual}.
336 @defopt url-mime-language-string
337 @cindex language preferences
338 A string specifying the preferred language when servers can serve
339 files in several languages. Use RFC 1766 abbreviations, e.g.,
340 @samp{en} for English, @samp{de} for German.
342 The string can be @code{"*"} to get the first available language (as
343 opposed to the default).
346 @node HTTP URL Options
347 @subsection HTTP URL Options
349 HTTP supports an @samp{OPTIONS} method describing things supported by
352 @defun url-http-options url
353 Returns a property list describing options available for URL. The
354 property list members are:
358 A list of symbols specifying what HTTP methods the resource
363 A list of numbers specifying what DAV protocol/schema versions are
368 A list of supported DASL search types supported (string form).
371 A list of the units available for use in partial document fetches.
375 The @dfn{Platform For Privacy Protection} description for the resource.
376 Currently this is just the raw header contents.
381 @node Dealing with HTTP documents
382 @subsection Dealing with HTTP documents
384 HTTP URLs are retrieved into a buffer containing the HTTP headers
385 followed by the body. Since the headers are quasi-MIME, they may be
386 processed using the MIME library. @xref{Top,, Emacs MIME,
387 emacs-mime, The Emacs MIME Manual}. The URL package provides a
388 function to do this in general:
390 @defun url-decode-text-part handle &optional coding
391 This function decodes charset-encoded text in the current buffer. In
392 Emacs, the buffer is expected to be unibyte initially and is set to
393 multibyte after decoding.
394 HANDLE is the MIME handle of the original part. CODING is an explicit
395 coding to use, overriding what the MIME headers specify.
396 The coding system used for the decoding is returned.
398 Note that this function doesn't deal with @samp{http-equiv} charset
399 specifications in HTML @samp{<meta>} elements.
403 @section file and ftp
406 @cindex File Transfer Protocol
407 @cindex compressed files
411 ftp://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
412 file://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
415 These schemes are defined in RFC 1808.
416 @samp{ftp:} and @samp{file:} are synonymous in this library. They
417 allow reading arbitrary files from hosts. Either @samp{ange-ftp}
418 (Emacs) or @samp{efs} (XEmacs) is used to retrieve them from remote
419 hosts. Local files are accessed directly.
421 Compressed files are handled, but support is hard-coded so that
422 @code{jka-compr-compression-info-list} and so on have no affect.
423 Suffixes recognized are @samp{.z}, @samp{.gz}, @samp{.Z} and
426 @defopt url-directory-index-file
427 The filename to look for when indexing a directory, default
428 @samp{"index.html"}. If this file exists, and is readable, then it
429 will be viewed instead of using @code{dired} to view the directory.
436 @findex Info-goto-node
439 info:@var{file}#@var{node}
442 Info URLs are not officially defined. They invoke
443 @code{Info-goto-node} with argument @samp{(@var{file})@var{node}}.
444 @samp{#@var{node}} is optional, defaulting to @samp{Top}.
451 A mailto URL will send an email message to the address in the
452 URL, for example @samp{mailto:foo@@bar.com} would compose a
453 message to @samp{foo@@bar.com}.
455 @defopt url-mail-command
456 @vindex mail-user-agent
457 The function called whenever url needs to send mail. This should
458 normally be left to default from @var{mail-user-agent}. @xref{Mail
459 Methods, , Mail-Composition Methods, emacs, The GNU Emacs Manual}.
462 An @samp{X-Url-From} header field containing the URL of the document
463 that contained the mailto URL is added if that URL is known.
465 RFC 2368 extends the definition of mailto URLs in RFC 1738.
466 The form of a mailto URL is
468 @samp{mailto:@var{mailbox}[?@var{header}=@var{contents}[&@var{header}=@var{contents}]]}
470 @noindent where an arbitrary number of @var{header}s can be added. If the
471 @var{header} is @samp{body}, then @var{contents} is put in the body
472 otherwise a @var{header} header field is created with @var{contents}
473 as its contents. Note that the URL library does not consider any
474 headers `dangerous' so you should check them before sending the
478 Email messages are defined in @sc{rfc}822.
480 @node news/nntp/snews
481 @section @code{news}, @code{nntp} and @code{snews}
488 @c draft-gilman-news-url-01
489 The network news URL scheme take the following forms following RFC
490 1738 except that for compatibility with other clients, host and port
491 fields may be included in news URLs though they are properly only
492 allowed for nntp an snews.
495 @item news:@var{newsgroup}
496 Retrieves a list of messages in @var{newsgroup};
497 @item news:@var{message-id}
498 Retrieves the message with the given @var{message-id};
500 Retrieves a list of all available newsgroups;
501 @item nntp://@var{host}:@var{port}/@var{newsgroup}
502 @itemx nntp://@var{host}:@var{port}/@var{message-id}
503 @itemx nntp://@var{host}:@var{port}/*
504 Similar to the @samp{news} versions.
507 @samp{:@var{port}} is optional and defaults to :119.
509 @samp{snews} is the same as @samp{nntp} except that the default port
512 (It is tunneled through SSL.)
514 An @samp{nntp} URL is the same as a news URL, except that the URL may
515 specify an article by its number.
517 @defopt url-news-server
518 This variable can be used to override the default news server.
519 Usually this will be set by the Gnus package, which is used to fetch
521 @cindex environment variable
523 It may be set from the conventional environment variable
527 @node rlogin/telnet/tn3270
528 @section rlogin, telnet and tn3270
532 @cindex terminal emulation
533 @findex terminal-emulator
535 These URL schemes from RFC 1738 for logon via a terminal emulator have
538 telnet://@var{user}:@var{password}@@@var{host}:@var{port}
540 but the @code{:@var{password}} component is ignored.
542 To handle rlogin, telnet and tn3270 URLs, a @code{rlogin},
543 @code{telnet} or @code{tn3270} (the program names and arguments are
544 hardcoded) session is run in a @code{terminal-emulator} buffer.
545 Well-known ports are used if the URL does not specify a port.
550 @cindex Internet Relay Chat
554 @c Fixme: reference (was http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt)
555 @dfn{Internet Relay Chat} (IRC) is handled by handing off the @sc{irc}
556 session to a function named in @code{url-irc-function}.
558 @defopt url-irc-function
559 A function to actually open an IRC connection.
561 must take five arguments, @var{host}, @var{port}, @var{channel},
562 @var{user} and @var{password}. The @var{channel} argument specifies the
563 channel to join immediately, this can be @code{nil}. By default this is
564 @code{url-irc-rcirc}.
566 @defun url-irc-rcirc host port channel user password
567 Processes the arguments and lets @code{rcirc} handle the session.
569 @defun url-irc-erc host port channel user password
570 Processes the arguments and lets @code{ERC} handle the session.
572 @defun url-irc-zenirc host port channel user password
573 Processes the arguments and lets @code{zenirc} handle the session.
581 data:@r{[}@var{media-type}@r{]}@r{[};@var{base64}@r{]},@var{data}
584 Data URLs contain MIME data in the URL itself. They are defined in
587 @var{media-type} is a MIME @samp{Content-Type} string, possibly
588 including parameters. It defaults to
589 @samp{text/plain;charset=US-ASCII}. The @samp{text/plain} can be
590 omitted but the charset parameter supplied. If @samp{;base64} is
591 present, the @var{data} are base64-encoded.
596 @cindex Network File System
600 nfs://@var{user}:@var{password}@@@var{host}:@var{port}/@var{file}
603 The @samp{nfs:} scheme is defined in RFC 2224. It is similar to
604 @samp{ftp:} except that it points to a file on a remote host that is
605 handled by the automounter on the local host.
607 @defvar url-nfs-automounter-directory-spec
609 A string saying how to invoke the NFS automounter. Certain @samp{%}
610 sequences are recognized:
614 The hostname of the NFS server;
616 The port number of the NFS server;
618 The username to use to authenticate;
620 The password to use to authenticate;
622 The filename on the remote server;
627 Each can be used any number of times.
641 @cindex Lightweight Directory Access Protocol
643 The LDAP scheme is defined in RFC 2255.
653 @cindex @command{man}
654 @cindex Unix man pages
658 @samp{man:@var{page-spec}}
661 This is a non-standard scheme. @var{page-spec} is passed directly to
662 the Lisp @code{man} function.
664 @node Defining New URLs
665 @chapter Defining New URLs
668 * Naming conventions::
669 * Required functions::
670 * Optional functions::
671 * Asynchronous fetching::
672 * Supporting file-name-handlers::
675 @node Naming conventions
676 @section Naming conventions
678 @node Required functions
679 @section Required functions
681 @node Optional functions
682 @section Optional functions
684 @node Asynchronous fetching
685 @section Asynchronous fetching
687 @node Supporting file-name-handlers
688 @section Supporting file-name-handlers
690 @node General Facilities
691 @chapter General Facilities
696 * Gateways in general::
701 @section Disk Caching
703 @cindex Persistent Cache
706 The disk cache stores retrieved documents locally, whence they can be
707 retrieved more quickly. When requesting a URL that is in the cache,
708 the library checks to see if the page has changed since it was last
709 retrieved from the remote machine. If not, the local copy is used,
710 saving the transmission over the network.
711 @cindex Cleaning the cache
712 @cindex Clearing the cache
713 @cindex Cache cleaning
714 Currently the cache isn't cleared automatically.
715 @c Running the @code{clean-cache} shell script
716 @c fist is recommended, to allow for future cleaning of the cache. This
717 @c shell script will remove all files that have not been accessed since it
718 @c was last run. To keep the cache pared down, it is recommended that this
719 @c script be run from @i{at} or @i{cron} (see the manual pages for
720 @c crontab(5) or at(1) for more information)
722 @defopt url-automatic-caching
723 Setting this variable non-@code{nil} causes documents to be cached
727 @defopt url-cache-directory
728 This variable specifies the
729 directory to store the cache files. It defaults to sub-directory
730 @file{cache} of @code{url-configuration-directory}.
733 @defopt url-cache-creation-function
734 The cache relies on a scheme for mapping URLs to files in the cache.
735 This variable names a function which sets the type of cache to use.
736 It takes a URL as argument and returns the absolute file name of the
737 corresponding cache file. The two supplied possibilities are
738 @code{url-cache-create-filename-using-md5} and
739 @code{url-cache-create-filename-human-readable}.
742 @defun url-cache-create-filename-using-md5 url
743 Creates a cache file name from @var{url} using MD5 hashing.
744 This is creates entries with very few cache collisions and is fast.
747 (url-cache-create-filename-using-md5 "http://www.example.com/foo/bar")
748 @result{} "/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f"
752 @defun url-cache-create-filename-human-readable url
753 Creates a cache file name from @var{url} more obviously connected to
754 @var{url} than for @code{url-cache-create-filename-using-md5}, but
755 more likely to conflict with other files.
757 (url-cache-create-filename-human-readable "http://www.example.com/foo/bar")
758 @result{} "/home/fx/.url/cache/fx/http/com/example/www/foo/bar"
762 @defun url-cache-expired
763 This function returns non-nil if a cache entry has expired (or is absent).
764 The arguments are a URL and optional expiration delay in seconds
765 (default @var{url-cache-expire-time}).
768 @defopt url-cache-expire-time
769 This variable is the default number of seconds to use for the
770 expire-time argument of the function @code{url-cache-expired}.
773 @defun url-fetch-from-cache
774 This function takes a URL as its argument and returns a buffer
775 containing the data cached for that URL.
778 @c Fixme: never actually used currently?
779 @c @defopt url-standalone-mode
780 @c @cindex Relying on cache
781 @c @cindex Cache only mode
782 @c @cindex Standalone mode
783 @c If this variable is non-@code{nil}, the library relies solely on the
784 @c cache for fetching documents and avoids checking if they have changed
785 @c on remote servers.
788 @c With a large cache of documents on the local disk, it can be very handy
789 @c when traveling, or any other time the network connection is not active
790 @c (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3 can rely
791 @c solely on its cache, and avoid checking to see if the page has changed
792 @c on the remote server. In the case of a dial-on-demand PPP connection,
793 @c this will keep the phone line free as long as possible, only bringing up
794 @c the PPP connection when asking for a page that is not located in the
795 @c cache. This is very useful for demonstrations as well.
798 @section Proxies and Gatewaying
800 @c fixme: check/document url-ns stuff
801 @cindex proxy servers
803 @cindex environment variables
805 Proxy servers are commonly used to provide gateways through firewalls
806 or as caches serving some more-or-less local network. Each protocol
807 (HTTP, FTP, etc.)@: can have a different gateway server. Proxying is
808 conventionally configured commonly amongst different programs through
809 environment variables of the form @code{@var{protocol}_proxy}, where
810 @var{protocol} is one of the supported network protocols (@code{http},
811 @code{ftp} etc.). The library recognizes such variables in either
812 upper or lower case. Their values are of one of the forms:
814 @item @code{@var{host}:@var{port}}
816 @item Simply a host name.
820 The @code{NO_PROXY} environment variable specifies URLs that should be
821 excluded from proxying (on servers that should be contacted directly).
822 This should be a comma-separated list of hostnames, domain names, or a
823 mixture of both. Asterisks can be used as wildcards, but other
824 clients may not support that. Domain names may be indicated by a
825 leading dot. For example:
827 NO_PROXY="*.aventail.com,home.com,.seanet.com"
829 @noindent says to contact all machines in the @samp{aventail.com} and
830 @samp{seanet.com} domains directly, as well as the machine named
831 @samp{home.com}. If @code{NO_PROXY} isn't defined, @code{no_PROXY}
832 and @code{no_proxy} are also tried, in that order.
834 Proxies may also be specified directly in Lisp.
836 @defopt url-proxy-services
837 This variable is an alist of URL schemes and proxy servers that
838 gateway them. The items are of the form @w{@code{(@var{scheme}
839 . @var{host}:@var{portnumber})}}, says that the URL @var{scheme} is
840 gatewayed through @var{portnumber} on the specified @var{host}. An
841 exception is the pseudo scheme @code{"no_proxy"}, which is paired with
842 a regexp matching host names not to be proxied. This variable is
843 initialized from the environment as above.
846 (setq url-proxy-services
847 '(("http" . "proxy.aventail.com:80")
848 ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com")))
852 @node Gateways in general
853 @section Gateways in General
857 The library provides a general gateway layer through which all
858 networking passes. It can both control access to the network and
859 provide access through gateways in firewalls. This may make direct
860 connections in some cases and pass through some sort of gateway in
861 others.@footnote{Proxies (which only operate over HTTP) are
862 implemented using this.} The library's basic function responsible for
863 making connections is @code{url-open-stream}.
865 @defun url-open-stream name buffer host service
866 @cindex opening a stream
867 @cindex stream, opening
868 Open a stream to @var{host}, possibly via a gateway. The other
869 arguments are as for @code{open-network-stream}. This will not make a
870 connection if @code{url-gateway-unplugged} is non-@code{nil}.
873 @defvar url-gateway-local-host-regexp
874 This is a regular expression that matches local hosts that do not
875 require the use of a gateway. If @code{nil}, all connections are made
879 @defvar url-gateway-method
880 This variable controls which gateway method is used. It may be useful
881 to bind it temporarily in some applications. It has values taken from
882 a list of symbols. Possible values are:
886 @cindex @command{telnet}
887 Use this method if you must first telnet and log into a gateway host,
888 and then run telnet from that host to connect to outside machines.
891 @cindex @command{rlogin}
892 This method is identical to @code{telnet}, but uses @command{rlogin}
893 to log into the remote machine without having to send the username and
894 password over the wire every time.
898 Use if the firewall has a @sc{socks} gateway running on it. The
899 @sc{socks} v5 protocol is defined in RFC 1928.
902 @c This probably shouldn't be documented
903 @c Fixme: why not? -- fx
906 This method uses Emacs's builtin networking directly. This is the
907 default. It can be used only if there is no firewall blocking access.
911 The following variables control the gateway methods.
913 @defopt url-gateway-telnet-host
914 The gateway host to telnet to. Once logged in there, you then telnet
915 out to the hosts you want to connect to.
917 @defopt url-gateway-telnet-parameters
918 This should be a list of parameters to pass to the @command{telnet} program.
920 @defopt url-gateway-telnet-password-prompt
921 This is a regular expression that matches the password prompt when
924 @defopt url-gateway-telnet-login-prompt
925 This is a regular expression that matches the username prompt when
928 @defopt url-gateway-telnet-user-name
929 The username to log in with.
931 @defopt url-gateway-telnet-password
932 The password to send when logging in.
934 @defopt url-gateway-prompt-pattern
935 This is a regular expression that matches the shell prompt.
938 @defopt url-gateway-rlogin-host
939 Host to @samp{rlogin} to before telnetting out.
941 @defopt url-gateway-rlogin-parameters
942 Parameters to pass to @samp{rsh}.
944 @defopt url-gateway-rlogin-user-name
945 User name to use when logging in to the gateway.
947 @defopt url-gateway-prompt-pattern
948 This is a regular expression that matches the shell prompt.
952 This specifies the default server, it takes the form
953 @w{@code{("Default server" @var{server} @var{port} @var{version})}}
954 where @var{version} can be either 4 or 5.
956 @defvar socks-password
957 If this is @code{nil} then you will be asked for the password,
958 otherwise it will be used as the password for authenticating you to
959 the @sc{socks} server.
961 @defvar socks-username
962 This is the username to use when authenticating yourself to the
963 @sc{socks} server. By default this is your login name.
965 @defvar socks-timeout
966 This controls how long, in seconds, to wait for responses from the
967 @sc{socks} server; it is 5 by default.
969 @c fixme: these have been effectively commented-out in the code
970 @c @defopt socks-server-aliases
971 @c This a list of server aliases. It is a list of aliases of the form
972 @c @var{(alias hostname port version)}.
974 @c @defopt socks-network-aliases
975 @c This a list of network aliases. Each entry in the list takes the form
976 @c @var{(alias (network))} where @var{alias} is a string that names the
977 @c @var{network}. The networks can contain a pair (not a dotted pair) of
978 @c @sc{ip} addresses which specify a range of @sc{ip} addresses, an @sc{ip}
979 @c address and a netmask, a domain name or a unique hostname or @sc{ip}
982 @c @defopt socks-redirection-rules
983 @c This a list of redirection rules. Each rule take the form
984 @c @var{(Destination network Connection type)} where @var{Destination
985 @c network} is a network alias from @code{socks-network-aliases} and
986 @c @var{Connection type} can be @code{nil} in which case a direct
987 @c connection is used, or it can be an alias from
988 @c @code{socks-server-aliases} in which case that server is used as a
991 @defopt socks-nslookup-program
992 @cindex @command{nslookup}
993 This the @samp{nslookup} program. It is @code{"nslookup"} by default.
997 * Suppressing network connections::
999 @c * Broken hostname resolution::
1001 @node Suppressing network connections
1002 @subsection Suppressing Network Connections
1004 @cindex network connections, suppressing
1005 @cindex suppressing network connections
1008 In some circumstances it is desirable to suppress making network
1009 connections. A typical case is when rendering HTML in a mail user
1010 agent, when external URLs should not be activated, particularly to
1011 avoid `bugs' which `call home' by fetch single-pixel images and the
1012 like. To arrange this, bind the following variable for the duration
1015 @defvar url-gateway-unplugged
1016 If this variable is non-@code{nil} new network connections are never
1017 opened by the URL library.
1020 @c @node Broken hostname resolution
1021 @c @subsection Broken Hostname Resolution
1023 @c @cindex hostname resolver
1024 @c @cindex resolver, hostname
1025 @c Some C libraries do not include the hostname resolver routines in
1026 @c their static libraries. If Emacs was linked statically, and was not
1027 @c linked with the resolver libraries, it will not be able to get to any
1028 @c machines off the local network. This is characterized by being able
1029 @c to reach someplace with a raw ip number, but not its hostname
1030 @c (@url{http://129.79.254.191/} works, but
1031 @c @url{http://www.cs.indiana.edu/} doesn't). This used to happen on
1032 @c SunOS4 and Ultrix, but is now probably now rare. If Emacs can't be
1033 @c rebuilt linked against the resolver library, it can use the external
1034 @c @command{nslookup} program instead.
1036 @c @defopt url-gateway-broken-resolution
1037 @c @cindex @code{nslookup} program
1038 @c @cindex program, @code{nslookup}
1039 @c If non-@code{nil}, this variable says to use the program specified by
1040 @c @code{url-gateway-nslookup-program} program to do hostname resolution.
1043 @c @defopt url-gateway-nslookup-program
1044 @c The name of the program to do hostname lookup if Emacs can't do it
1045 @c directly. This program should expect a single argument on the command
1046 @c line---the hostname to resolve---and should produce output similar to
1047 @c the standard Unix @command{nslookup} program:
1049 @c Name: www.cs.indiana.edu
1050 @c Address: 129.79.254.191
1057 @findex url-do-setup
1058 The library can maintain a global history list tracking URLs accessed.
1059 URL completion can be done from it. The history mechanism is set up
1060 automatically via @code{url-do-setup} when it is configured to be on.
1061 Note that the size of the history list is currently not limited.
1063 @vindex url-history-hash-table
1064 The history `list' is actually a hash table,
1065 @code{url-history-hash-table}. It contains access times keyed by URL
1066 strings. The times are in the format returned by @code{current-time}.
1068 @defun url-history-update-url url time
1069 This function updates the history table with an entry for @var{url}
1070 accessed at the given @var{time}.
1073 @defopt url-history-track
1074 If non-@code{nil}, the library will keep track of all the URLs
1075 accessed. If it is @code{t}, the list is saved to disk at the end of
1076 each Emacs session. The default is @code{nil}.
1079 @defopt url-history-file
1080 The file storing the history list between sessions. It defaults to
1081 @file{history} in @code{url-configuration-directory}.
1084 @defopt url-history-save-interval
1085 @findex url-history-setup-save-timer
1086 The number of seconds between automatic saves of the history list.
1087 Default is one hour. Note that if you change this variable directly,
1088 rather than using Custom, after @code{url-do-setup} has been run, you
1089 need to run the function @code{url-history-setup-save-timer}.
1092 @defun url-history-parse-history &optional fname
1093 Parses the history file @var{fname} (default @code{url-history-file})
1094 and sets up the history list.
1097 @defun url-history-save-history &optional fname
1098 Saves the current history to file @var{fname} (default
1099 @code{url-history-file}).
1102 @defun url-completion-function string predicate function
1103 You can use this function to do completion of URLs from the history.
1107 @chapter Customization
1109 @section Environment Variables
1111 @cindex environment variables
1112 The following environment variables affect the library's operation at
1118 @vindex url-temporary-directory
1119 If this is defined, @var{url-temporary-directory} is initialized from
1123 @section General User Options
1125 The following user options, settable with Customize, affect the
1126 general operation of the package.
1130 Specifies the types of debug messages which are logged to
1131 the @code{*URL-DEBUG*} buffer.
1132 @code{t} means log all messages.
1133 A number means log all messages and show them with @code{message}.
1134 It may also be a list of the types of messages to be logged.
1136 @defopt url-personal-mail-address
1138 @defopt url-privacy-level
1140 @defopt url-uncompressor-alist
1142 @defopt url-passwd-entry-func
1144 @defopt url-standalone-mode
1146 @defopt url-bad-port-list
1148 @defopt url-max-password-attempts
1150 @defopt url-temporary-directory
1152 @defopt url-show-status
1154 @defopt url-confirmation-func
1155 The function to use for asking yes or no functions. This is normally
1156 either @code{y-or-n-p} or @code{yes-or-no-p}, but could be another
1157 function taking a single argument (the prompt) and returning @code{t}
1158 only if an affirmative answer is given.
1160 @defopt url-gateway-method
1161 @c fixme: describe gatewaying
1162 A symbol specifying the type of gateway support to use for connections
1163 from the local machine. The supported methods are:
1167 Run telnet in a subprocess to connect;
1169 Rlogin to another machine to connect;
1171 Connect through a socks server;
1179 @node GNU Free Documentation License
1180 @appendix GNU Free Documentation License
1181 @include doclicense.texi
1183 @node Function Index
1184 @unnumbered Command and Function Index
1187 @node Variable Index
1188 @unnumbered Variable Index
1192 @unnumbered Concept Index