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 Emacs lisp libraries
17 * URL: (url). URL loading package.
21 This file documents the Emacs Lisp URL loading package.
23 Copyright @copyright{} 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2002,
24 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 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 @c Fixme: function v. option, but neither used.
734 @c @findex url-cache-expired
735 @c @defopt url-cache-expired
736 @c This is a function to decide whether or not a cache entry has expired.
737 @c It takes two times as it parameters and returns non-@code{nil} if the
738 @c second time is ``too old'' when compared with the first time.
741 @defopt url-cache-creation-function
742 The cache relies on a scheme for mapping URLs to files in the cache.
743 This variable names a function which sets the type of cache to use.
744 It takes a URL as argument and returns the absolute file name of the
745 corresponding cache file. The two supplied possibilities are
746 @code{url-cache-create-filename-using-md5} and
747 @code{url-cache-create-filename-human-readable}.
750 @defun url-cache-create-filename-using-md5 url
751 Creates a cache file name from @var{url} using MD5 hashing.
752 This is creates entries with very few cache collisions and is fast.
755 (url-cache-create-filename-using-md5 "http://www.example.com/foo/bar")
756 @result{} "/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f"
760 @defun url-cache-create-filename-human-readable url
761 Creates a cache file name from @var{url} more obviously connected to
762 @var{url} than for @code{url-cache-create-filename-using-md5}, but
763 more likely to conflict with other files.
765 (url-cache-create-filename-human-readable "http://www.example.com/foo/bar")
766 @result{} "/home/fx/.url/cache/fx/http/com/example/www/foo/bar"
770 @c Fixme: never actually used currently?
771 @c @defopt url-standalone-mode
772 @c @cindex Relying on cache
773 @c @cindex Cache only mode
774 @c @cindex Standalone mode
775 @c If this variable is non-@code{nil}, the library relies solely on the
776 @c cache for fetching documents and avoids checking if they have changed
777 @c on remote servers.
780 @c With a large cache of documents on the local disk, it can be very handy
781 @c when traveling, or any other time the network connection is not active
782 @c (a laptop with a dial-on-demand PPP connection, etc). Emacs/W3 can rely
783 @c solely on its cache, and avoid checking to see if the page has changed
784 @c on the remote server. In the case of a dial-on-demand PPP connection,
785 @c this will keep the phone line free as long as possible, only bringing up
786 @c the PPP connection when asking for a page that is not located in the
787 @c cache. This is very useful for demonstrations as well.
790 @section Proxies and Gatewaying
792 @c fixme: check/document url-ns stuff
793 @cindex proxy servers
795 @cindex environment variables
797 Proxy servers are commonly used to provide gateways through firewalls
798 or as caches serving some more-or-less local network. Each protocol
799 (HTTP, FTP, etc.)@: can have a different gateway server. Proxying is
800 conventionally configured commonly amongst different programs through
801 environment variables of the form @code{@var{protocol}_proxy}, where
802 @var{protocol} is one of the supported network protocols (@code{http},
803 @code{ftp} etc.). The library recognizes such variables in either
804 upper or lower case. Their values are of one of the forms:
806 @item @code{@var{host}:@var{port}}
808 @item Simply a host name.
812 The @code{NO_PROXY} environment variable specifies URLs that should be
813 excluded from proxying (on servers that should be contacted directly).
814 This should be a comma-separated list of hostnames, domain names, or a
815 mixture of both. Asterisks can be used as wildcards, but other
816 clients may not support that. Domain names may be indicated by a
817 leading dot. For example:
819 NO_PROXY="*.aventail.com,home.com,.seanet.com"
821 @noindent says to contact all machines in the @samp{aventail.com} and
822 @samp{seanet.com} domains directly, as well as the machine named
823 @samp{home.com}. If @code{NO_PROXY} isn't defined, @code{no_PROXY}
824 and @code{no_proxy} are also tried, in that order.
826 Proxies may also be specified directly in Lisp.
828 @defopt url-proxy-services
829 This variable is an alist of URL schemes and proxy servers that
830 gateway them. The items are of the form @w{@code{(@var{scheme}
831 . @var{host}:@var{portnumber})}}, says that the URL @var{scheme} is
832 gatewayed through @var{portnumber} on the specified @var{host}. An
833 exception is the pseudo scheme @code{"no_proxy"}, which is paired with
834 a regexp matching host names not to be proxied. This variable is
835 initialized from the environment as above.
838 (setq url-proxy-services
839 '(("http" . "proxy.aventail.com:80")
840 ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com")))
844 @node Gateways in general
845 @section Gateways in General
849 The library provides a general gateway layer through which all
850 networking passes. It can both control access to the network and
851 provide access through gateways in firewalls. This may make direct
852 connections in some cases and pass through some sort of gateway in
853 others.@footnote{Proxies (which only operate over HTTP) are
854 implemented using this.} The library's basic function responsible for
855 making connections is @code{url-open-stream}.
857 @defun url-open-stream name buffer host service
858 @cindex opening a stream
859 @cindex stream, opening
860 Open a stream to @var{host}, possibly via a gateway. The other
861 arguments are as for @code{open-network-stream}. This will not make a
862 connection if @code{url-gateway-unplugged} is non-@code{nil}.
865 @defvar url-gateway-local-host-regexp
866 This is a regular expression that matches local hosts that do not
867 require the use of a gateway. If @code{nil}, all connections are made
871 @defvar url-gateway-method
872 This variable controls which gateway method is used. It may be useful
873 to bind it temporarily in some applications. It has values taken from
874 a list of symbols. Possible values are:
878 @cindex @command{telnet}
879 Use this method if you must first telnet and log into a gateway host,
880 and then run telnet from that host to connect to outside machines.
883 @cindex @command{rlogin}
884 This method is identical to @code{telnet}, but uses @command{rlogin}
885 to log into the remote machine without having to send the username and
886 password over the wire every time.
890 Use if the firewall has a @sc{socks} gateway running on it. The
891 @sc{socks} v5 protocol is defined in RFC 1928.
894 @c This probably shouldn't be documented
895 @c Fixme: why not? -- fx
898 This method uses Emacs's builtin networking directly. This is the
899 default. It can be used only if there is no firewall blocking access.
903 The following variables control the gateway methods.
905 @defopt url-gateway-telnet-host
906 The gateway host to telnet to. Once logged in there, you then telnet
907 out to the hosts you want to connect to.
909 @defopt url-gateway-telnet-parameters
910 This should be a list of parameters to pass to the @command{telnet} program.
912 @defopt url-gateway-telnet-password-prompt
913 This is a regular expression that matches the password prompt when
916 @defopt url-gateway-telnet-login-prompt
917 This is a regular expression that matches the username prompt when
920 @defopt url-gateway-telnet-user-name
921 The username to log in with.
923 @defopt url-gateway-telnet-password
924 The password to send when logging in.
926 @defopt url-gateway-prompt-pattern
927 This is a regular expression that matches the shell prompt.
930 @defopt url-gateway-rlogin-host
931 Host to @samp{rlogin} to before telnetting out.
933 @defopt url-gateway-rlogin-parameters
934 Parameters to pass to @samp{rsh}.
936 @defopt url-gateway-rlogin-user-name
937 User name to use when logging in to the gateway.
939 @defopt url-gateway-prompt-pattern
940 This is a regular expression that matches the shell prompt.
944 This specifies the default server, it takes the form
945 @w{@code{("Default server" @var{server} @var{port} @var{version})}}
946 where @var{version} can be either 4 or 5.
948 @defvar socks-password
949 If this is @code{nil} then you will be asked for the password,
950 otherwise it will be used as the password for authenticating you to
951 the @sc{socks} server.
953 @defvar socks-username
954 This is the username to use when authenticating yourself to the
955 @sc{socks} server. By default this is your login name.
957 @defvar socks-timeout
958 This controls how long, in seconds, to wait for responses from the
959 @sc{socks} server; it is 5 by default.
961 @c fixme: these have been effectively commented-out in the code
962 @c @defopt socks-server-aliases
963 @c This a list of server aliases. It is a list of aliases of the form
964 @c @var{(alias hostname port version)}.
966 @c @defopt socks-network-aliases
967 @c This a list of network aliases. Each entry in the list takes the form
968 @c @var{(alias (network))} where @var{alias} is a string that names the
969 @c @var{network}. The networks can contain a pair (not a dotted pair) of
970 @c @sc{ip} addresses which specify a range of @sc{ip} addresses, an @sc{ip}
971 @c address and a netmask, a domain name or a unique hostname or @sc{ip}
974 @c @defopt socks-redirection-rules
975 @c This a list of redirection rules. Each rule take the form
976 @c @var{(Destination network Connection type)} where @var{Destination
977 @c network} is a network alias from @code{socks-network-aliases} and
978 @c @var{Connection type} can be @code{nil} in which case a direct
979 @c connection is used, or it can be an alias from
980 @c @code{socks-server-aliases} in which case that server is used as a
983 @defopt socks-nslookup-program
984 @cindex @command{nslookup}
985 This the @samp{nslookup} program. It is @code{"nslookup"} by default.
989 * Suppressing network connections::
991 @c * Broken hostname resolution::
993 @node Suppressing network connections
994 @subsection Suppressing Network Connections
996 @cindex network connections, suppressing
997 @cindex suppressing network connections
1000 In some circumstances it is desirable to suppress making network
1001 connections. A typical case is when rendering HTML in a mail user
1002 agent, when external URLs should not be activated, particularly to
1003 avoid `bugs' which `call home' by fetch single-pixel images and the
1004 like. To arrange this, bind the following variable for the duration
1007 @defvar url-gateway-unplugged
1008 If this variable is non-@code{nil} new network connections are never
1009 opened by the URL library.
1012 @c @node Broken hostname resolution
1013 @c @subsection Broken Hostname Resolution
1015 @c @cindex hostname resolver
1016 @c @cindex resolver, hostname
1017 @c Some C libraries do not include the hostname resolver routines in
1018 @c their static libraries. If Emacs was linked statically, and was not
1019 @c linked with the resolver libraries, it will not be able to get to any
1020 @c machines off the local network. This is characterized by being able
1021 @c to reach someplace with a raw ip number, but not its hostname
1022 @c (@url{http://129.79.254.191/} works, but
1023 @c @url{http://www.cs.indiana.edu/} doesn't). This used to happen on
1024 @c SunOS4 and Ultrix, but is now probably now rare. If Emacs can't be
1025 @c rebuilt linked against the resolver library, it can use the external
1026 @c @command{nslookup} program instead.
1028 @c @defopt url-gateway-broken-resolution
1029 @c @cindex @code{nslookup} program
1030 @c @cindex program, @code{nslookup}
1031 @c If non-@code{nil}, this variable says to use the program specified by
1032 @c @code{url-gateway-nslookup-program} program to do hostname resolution.
1035 @c @defopt url-gateway-nslookup-program
1036 @c The name of the program to do hostname lookup if Emacs can't do it
1037 @c directly. This program should expect a single argument on the command
1038 @c line---the hostname to resolve---and should produce output similar to
1039 @c the standard Unix @command{nslookup} program:
1041 @c Name: www.cs.indiana.edu
1042 @c Address: 129.79.254.191
1049 @findex url-do-setup
1050 The library can maintain a global history list tracking URLs accessed.
1051 URL completion can be done from it. The history mechanism is set up
1052 automatically via @code{url-do-setup} when it is configured to be on.
1053 Note that the size of the history list is currently not limited.
1055 @vindex url-history-hash-table
1056 The history `list' is actually a hash table,
1057 @code{url-history-hash-table}. It contains access times keyed by URL
1058 strings. The times are in the format returned by @code{current-time}.
1060 @defun url-history-update-url url time
1061 This function updates the history table with an entry for @var{url}
1062 accessed at the given @var{time}.
1065 @defopt url-history-track
1066 If non-@code{nil}, the library will keep track of all the URLs
1067 accessed. If it is @code{t}, the list is saved to disk at the end of
1068 each Emacs session. The default is @code{nil}.
1071 @defopt url-history-file
1072 The file storing the history list between sessions. It defaults to
1073 @file{history} in @code{url-configuration-directory}.
1076 @defopt url-history-save-interval
1077 @findex url-history-setup-save-timer
1078 The number of seconds between automatic saves of the history list.
1079 Default is one hour. Note that if you change this variable directly,
1080 rather than using Custom, after @code{url-do-setup} has been run, you
1081 need to run the function @code{url-history-setup-save-timer}.
1084 @defun url-history-parse-history &optional fname
1085 Parses the history file @var{fname} (default @code{url-history-file})
1086 and sets up the history list.
1089 @defun url-history-save-history &optional fname
1090 Saves the current history to file @var{fname} (default
1091 @code{url-history-file}).
1094 @defun url-completion-function string predicate function
1095 You can use this function to do completion of URLs from the history.
1099 @chapter Customization
1101 @section Environment Variables
1103 @cindex environment variables
1104 The following environment variables affect the library's operation at
1110 @vindex url-temporary-directory
1111 If this is defined, @var{url-temporary-directory} is initialized from
1115 @section General User Options
1117 The following user options, settable with Customize, affect the
1118 general operation of the package.
1122 Specifies the types of debug messages which are logged to
1123 the @code{*URL-DEBUG*} buffer.
1124 @code{t} means log all messages.
1125 A number means log all messages and show them with @code{message}.
1126 It may also be a list of the types of messages to be logged.
1128 @defopt url-personal-mail-address
1130 @defopt url-privacy-level
1132 @defopt url-uncompressor-alist
1134 @defopt url-passwd-entry-func
1136 @defopt url-standalone-mode
1138 @defopt url-bad-port-list
1140 @defopt url-max-password-attempts
1142 @defopt url-temporary-directory
1144 @defopt url-show-status
1146 @defopt url-confirmation-func
1147 The function to use for asking yes or no functions. This is normally
1148 either @code{y-or-n-p} or @code{yes-or-no-p}, but could be another
1149 function taking a single argument (the prompt) and returning @code{t}
1150 only if an affirmative answer is given.
1152 @defopt url-gateway-method
1153 @c fixme: describe gatewaying
1154 A symbol specifying the type of gateway support to use for connections
1155 from the local machine. The supported methods are:
1159 Run telnet in a subprocess to connect;
1161 Rlogin to another machine to connect;
1163 Connect through a socks server;
1171 @node GNU Free Documentation License
1172 @appendix GNU Free Documentation License
1173 @include doclicense.texi
1175 @node Function Index
1176 @unnumbered Command and Function Index
1179 @node Variable Index
1180 @unnumbered Variable Index
1184 @unnumbered Concept Index
1190 arch-tag: c96be356-7e2d-4196-bcda-b13246c5c3f0