URL
***

This is the manual for the url Emacs Lisp library.

Copyright © 1993-1999, 2002, 2004-2012 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License''.

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.''

Introduction
************

A Uniform Resource Identifier (URI) is a specially-formatted name, such as an Internet address, that identifies some name or resource.  The format of URIs is described in RFC 3986, which updates and replaces the earlier RFCs 2732, 2396, 1808, and 1738.  A Uniform Resource Locator (URL) is an older but still-common term, which basically refers to a URI corresponding to a resource that can be accessed (usually over a network) in a specific way.

Here are some examples of URIs (taken from RFC 3986):

     ftp://ftp.is.co.za/rfc/rfc1808.txt
     http://www.ietf.org/rfc/rfc2396.txt
     ldap://[2001:db8::7]/c=GB?objectClass?one
     mailto:John.Doe@example.com
     news:comp.infosystems.www.servers.unix
     tel:+1-816-555-1212
     telnet://192.0.2.16:80/
     urn:oasis:names:specification:docbook:dtd:xml:4.1.2

This manual describes the url library, an Emacs Lisp library for parsing URIs and retrieving the resources to which they refer. (The library is so-named for historical reasons; nowadays, the ``URI'' terminology is regarded as the more general one, and ``URL'' is technically obsolete despite its widespread vernacular usage.)

URI Parsing
***********

A URI consists of several components, each having a different meaning.  For example, the URI

     http://www.gnu.org/software/emacs/

specifies the scheme component http, the hostname component www.gnu.org, and the path component /software/emacs/.

The format of URIs is specified by RFC 3986.  The url library provides the Lisp function url-generic-parse-url, a (mostly) standard-compliant URI parser, as well as function url-recreate-url, which converts a parsed URI back into a URI string.

 -- Function: url-generic-parse-url uri-string
     This function returns a parsed version of the string URI-STRING.

 -- Function: url-recreate-url uri-obj
     Given a parsed URI, this function returns the corresponding URI string.

The return value of url-generic-parse-url, and the argument expected by url-recreate-url, is a parsed URI: a CL structure whose slots hold the various components of the URI. See the CL Manual (GNU Emacs Common Lisp Emulation), for details about CL structures.  Most of the other functions in the url library act on parsed URIs.

Parsed URI structures
=====================

Each parsed URI structure contains the following slots:

type
     The URI scheme (a string, e.g., http).  See Supported URL Types, for a list of schemes that the url library knows how to process.  This slot can also be nil, if the URI is not fully specified.

user
     The user name (a string), or nil.

password
     The user password (a string), or nil.  The use of this URI component is strongly discouraged; nowadays, passwords are transmitted by other means, not as part of a URI.

host
     The host name (a string), or nil.  If present, this is typically a domain name or IP address.

port
     The port number (an integer), or nil.  Omitting this component usually means to use the ``standard'' port associated with the URI scheme.

filename
     The combination of the ``path'' and ``query'' components of the URI (a string), or nil.  If the query component is present, it is the substring following the first ? character, and the path component is the substring before the ?.  The meaning of these components is scheme-dependent; they do not necessarily refer to a file on a disk.

target
     The fragment component (a string), or nil.  The fragment component specifies a ``secondary resource'', such as a section of a webpage.

fullness
     This is t if the URI is fully specified, i.e., the hierarchical components of the URI (the hostname and/or username and/or password) are preceded by //.

These slots have accessors named url-PART, where PART is the slot name.  For example, the accessor for the host slot is the function url-host.  The url-port accessor returns the default port for the URI scheme if the parsed URI's PORT slot is nil.

The slots can be set using setf.  For example:

     (setf (url-port url) 80)

URI Encoding
============

The url-generic-parse-url parser does not obey RFC 3986 in one respect: it allows non-ASCII characters in URI strings.

Strictly speaking, RFC 3986 compatible URIs may only consist of ASCII characters; non-ASCII characters are represented by converting them to UTF-8 byte sequences, and performing percent encoding on the bytes.  For example, the o-umlaut character is converted to the UTF-8 byte sequence \xD3\xA7, then percent encoded to %D3%A7.  (Certain ``reserved'' ASCII characters must also be percent encoded when they appear in URI components.)

The function url-encode-url can be used to convert a URI string containing arbitrary characters to one that is properly percent-encoded in accordance with RFC 3986.

 -- Function: url-encode-url url-string
     This function return a properly URI-encoded version of URL-STRING.  It also performs URI normalization, e.g., converting the scheme component to lowercase if it was previously uppercase.

To convert between a string containing arbitrary characters and a percent-encoded all-ASCII string, use the functions url-hexify-string and url-unhex-string:

 -- Function: url-hexify-string string &optional allowed-chars
     This function performs percent-encoding on STRING, and returns the result.

     If STRING is multibyte, it is first converted to a UTF-8 byte string.  Each byte corresponding to an allowed character is left as-is, while all other bytes are converted to a three-character sequence: % followed by two upper-case hex digits.

     The allowed characters are specified by ALLOWED-CHARS.  If this argument is nil, the allowed characters are those specified as unreserved characters by RFC 3986 (see the variable url-unreserved-chars).  Otherwise, ALLOWED-CHARS should be a vector whose N-th element is non-nil if character N is allowed.

 -- Function: url-unhex-string string &optional allow-newlines
     This function replaces percent-encoding sequences in STRING with their character equivalents, and returns the resulting string.

     If ALLOW-NEWLINES is non-nil, it allows the decoding of carriage returns and line feeds, which are normally forbidden in URIs.

Retrieving URLs
***************

The url library defines the following three functions for retrieving the data specified by a URL.  The actual retrieval protocol depends on the URL's URI scheme, and is performed by lower-level scheme-specific functions.  (Those lower-level functions are not documented here, and generally should not be called directly.)

In each of these functions, the URL argument can be either a string or a parsed URL structure.  If it is a string, that string is passed through url-encode-url before using it, to ensure that it is properly URI-encoded (see URI Encoding).

 -- Function: url-retrieve-synchronously url
     This function synchronously retrieves the data specified by URL, and returns a buffer containing the data.  The return value is nil if there is no data associated with the URL (as is the case for dired, info, and mailto URLs).

 -- Function: url-retrieve url callback &optional cbargs silent no-cookies
     This function retrieves URL asynchronously, calling the function CALLBACK when the object has been completely retrieved.  The return value is the buffer into which the data will be inserted, or nil if the process has already completed.

     The callback function is called this way:

          (apply CALLBACK STATUS CBARGS)

     where STATUS is a plist representing what happened during the retrieval, with most recent events first, or an empty list if no events have occurred.  Each pair in the plist is one of:

     (:redirect REDIRECTED-TO)
          This means that the request was redirected to the URL REDIRECTED-TO.

     (:error (ERROR-SYMBOL . DATA))
          This means that an error occurred.  If so desired, the error can be signaled with (signal ERROR-SYMBOL DATA).

     When the callback function is called, the current buffer is the one containing the retrieved data (if any).  The buffer also contains any MIME headers associated with the data retrieval.

     If the optional argument SILENT is non-nil, progress messages are suppressed.  If the optional argument NO-COOKIES is non-nil, cookies are not stored or sent.

 -- Function: url-queue-retrieve url callback &optional cbargs silent no-cookies
     This function acts like url-retrieve, but with limits on the number of concurrently-running network processes.  The option url-queue-parallel-processes controls the number of concurrent processes, and the option url-queue-timeout sets a timeout in seconds.

     To use this function, you must (require 'url-queue).

 -- User Option: url-queue-parallel-processes
     The value of this option is an integer specifying the maximum number of concurrent url-queue-retrieve network processes.  If the number of url-queue-retrieve calls is larger than this number, later ones are queued until ealier ones are finished.

 -- User Option: url-queue-timeout
     The value of this option is a number specifying the maximum lifetime of a url-queue-retrieve network process, once it is started. If a process is not finished by then, it is killed and removed from the queue.

Supported URL Types
*******************

This chapter describes functions and variables affecting URL retrieval for specific schemes.

http and https
==============

The http scheme refers to the Hypertext Transfer Protocol.  The url library supports HTTP version 1.1, specified in RFC 2616. Its default port is 80.

The https scheme is a secure version of http, with transmission via SSL.  It is defined in RFC 2069, and its default port is 443.  When using https, the url library performs SSL encryption via the ssl library, by forcing the ssl gateway method to be used.  See Gateways in general.

 -- User Option: url-honor-refresh-requests
     If this option is non-nil (the default), the url library honors the HTTP Refresh header, which is used by servers to direct clients to reload documents from the same URL or a or different one.  If the value is nil, the Refresh header is ignored; any other value means to ask the user on each request.

Cookies
-------

 -- User Option: url-cookie-file
     The file in which cookies are stored, defaulting to cookies in the directory specified by url-configuration-directory.

 -- User Option: url-cookie-confirmation
     Specifies whether confirmation is require to accept cookies.

 -- User Option: url-cookie-multiple-line
     Specifies whether to put all cookies for the server on one line in the HTTP request to satisfy broken servers like http://www.hotmail.com.

 -- User Option: url-cookie-trusted-urls
     A list of regular expressions matching URLs from which to accept cookies always.

 -- User Option: url-cookie-untrusted-urls
     A list of regular expressions matching URLs from which to reject cookies always.

 -- User Option: url-cookie-save-interval
     The number of seconds between automatic saves of cookies to disk. Default is one hour.

Language and Encoding Preferences
---------------------------------

HTTP allows clients to express preferences for the language and encoding of documents which servers may honor.  For each of these variables, the value is a string; it can specify a single choice, or it can be a comma-separated list.

Normally, this list is ordered by descending preference.  However, each element can be followed by ;q=PRIORITY to specify its preference level, a decimal number from 0 to 1; e.g., for url-mime-language-string, "de, en-gb;q=0.8, en;q=0.7".  An element that has no ;q specification has preference level 1.

 -- User Option: url-mime-charset-string
     This variable specifies a preference for character sets when documents can be served in more than one encoding.

     HTTP allows specifying a series of MIME charsets which indicate your preferred character set encodings, e.g., Latin-9 or Big5, and these can be weighted.  The default series is generated automatically from the associated MIME types of all defined coding systems, sorted by the coding system priority specified in Emacs.  See Recognizing Coding Systems (The GNU Emacs Manual).

 -- User Option: url-mime-language-string
     A string specifying the preferred language when servers can serve files in several languages.  Use RFC 1766 abbreviations, e.g., en for English, de for German.

     The string can be "*" to get the first available language (as opposed to the default).

HTTP URL Options
----------------

HTTP supports an OPTIONS method describing things supported by the URL.

 -- Function: url-http-options url
     Returns a property list describing options available for URL.  The property list members are:

     methods
          A list of symbols specifying what HTTP methods the resource supports.

     dav
          A list of numbers specifying what DAV protocol/schema versions are supported.

     dasl
          A list of supported DASL search types supported (string form).

     ranges
          A list of the units available for use in partial document fetches.

     p3p
          The Platform For Privacy Protection description for the resource. Currently this is just the raw header contents.

Dealing with HTTP documents
---------------------------

HTTP URLs are retrieved into a buffer containing the HTTP headers followed by the body.  Since the headers are quasi-MIME, they may be processed using the MIME library.  See Emacs MIME (The Emacs MIME Manual).

file and ftp
============

The ftp and file schemes are defined in RFC 1808.  The url library treats ftp: and file: as synonymous. Such URLs have the form

     ftp://USER:PASSWORD@HOST:PORT/FILE
     file://USER:PASSWORD@HOST:PORT/FILE

If the URL specifies a local file, it is retrieved by reading the file contents in the usual way.  If it specifies a remote file, it is retrieved using the Ange-FTP package.  See Remote Files (The GNU Emacs Manual).

When retrieving a compressed file, it is automatically uncompressed if it has the file suffix .z, .gz, .Z, .bz2, or .xz.  (The list of supported suffixes is hard-coded, and cannot be altered by customizing jka-compr-compression-info-list.)

 -- User Option: url-directory-index-file
     This option specifies the filename to look for when a file or ftp URL specifies a directory.  The default is index.html.  If this file exists and is readable, it is viewed. Otherwise, Emacs visits the directory using Dired.

info
====

The info scheme is non-standard.  Such URLs have the form

     info:FILE#NODE

and are retrieved by invoking Info-goto-node with argument (FILE)NODE.  If #NODE is omitted, the Top node is opened.

mailto
======

A mailto URL specifies an email message to be sent to a given email address.  For example, mailto:foo@bar.com specifies sending a message to foo@bar.com.  The ``retrieval method'' for such URLs is to open a mail composition buffer in which the appropriate content (e.g., the recipient address) has been filled in.

As defined in RFC 2368, a mailto URL has the form

     mailto:MAILBOX[?HEADER=CONTENTS[&HEADER=CONTENTS]]

where an arbitrary number of HEADERs can be added.  If the HEADER is body, then CONTENTS is put in the message body; otherwise, a HEADER header field is created with CONTENTS as its contents.  Note that the url library does not perform any checking of HEADER or CONTENTS, so you should check them before sending the message.

 -- User Option: url-mail-command
     The value of this variable is the function called whenever url needs to send mail.  This should normally be left its default, which is the standard mail-composition command compose-mail.  See Sending Mail (The GNU Emacs Manual).

If the document containing the mailto URL itself possessed a known URL, Emacs automatically inserts an X-Url-From header field into the mail buffer, specifying that URL.

news, nntp and snews
====================

The news, nntp, and snews schemes, defined in RFC 1738, are used for reading Usenet newsgroups.  For compatibility with non-standard-compliant news clients, the url library allows host and port fields to be included in news URLs, even though they are properly only allowed for nntp and snews.

news and nntp URLs have the following form:

news:NEWSGROUP
     Retrieves a list of messages in NEWSGROUP;

news:MESSAGE-ID
     Retrieves the message with the given MESSAGE-ID;

news:*
     Retrieves a list of all available newsgroups;

nntp://HOST:PORT/NEWSGROUP
nntp://HOST:PORT/MESSAGE-ID
nntp://HOST:PORT/*
     Similar to the news versions.

The default port for nntp (and news) is 119.  The difference between an nntp URL and a news URL is that an nttp URL may specify an article by its number.  The snews scheme is the same as nntp, except that it is tunneled through SSL and has default port 563.

These URLs are retrieved via the Gnus package.

 -- User Option: url-news-server
     This variable specifies the default news server from which to fetch news, if no server was specified in the URL.  The default value, nil, means to use the server specified by the standard environment variable NNTPSERVER, or news if that environment variable is unset.

rlogin, telnet and tn3270
=========================

These URL schemes are defined in RFC 1738, and are used for logging in via a terminal emulator.  They have the form

     telnet://USER:PASSWORD@HOST:PORT

but the PASSWORD component is ignored.

To handle rlogin, telnet and tn3270 URLs, a rlogin, telnet or tn3270 (the program names and arguments are hardcoded) session is run in a terminal-emulator buffer. Well-known ports are used if the URL does not specify a port.

irc
===

The irc scheme is defined in the Internet Draft at http://www.w3.org/Addressing/draft-mirashi-url-irc-01.txt (which was never approved as an RFC).  Such URLs have the form

     irc://HOST:PORT/TARGET,NEEDPASS

and are retrieved by opening an IRC session using the function specified by url-irc-function.

 -- User Option: url-irc-function
     The value of this option is a function, which is called to open an IRC connection for irc URLs.  This function must take five arguments, HOST, PORT, CHANNEL, USER and PASSWORD.  The CHANNEL argument specifies the channel to join immediately, and may be nil.

     The default is url-irc-rcirc, which uses the Rcirc package. Other options are url-irc-erc (which uses ERC) and url-irc-zenirc (which uses ZenIRC).

data
====

The data scheme, defined in RFC 2397, contains MIME data in the URL itself.  Such URLs have the form

     data:[MEDIA-TYPE][;BASE64],DATA

MEDIA-TYPE is a MIME Content-Type string, possibly including parameters.  It defaults to text/plain;charset=US-ASCII.  The text/plain can be omitted but the charset parameter supplied.  If ;base64 is present, the DATA are base64-encoded.

nfs
===

The nfs scheme, defined in RFC 2224, is similar to ftp except that it points to a file on a remote host that is handled by an NFS automounter on the local host.  Such URLs have the form

     nfs://USER:PASSWORD@HOST:PORT/FILE

 -- Variable: url-nfs-automounter-directory-spec

A string saying how to invoke the NFS automounter.  Certain % sequences are recognized:

%h
     The hostname of the NFS server;

%n
     The port number of the NFS server;

%u
     The username to use to authenticate;

%p
     The password to use to authenticate;

%f
     The filename on the remote server;

%%
     A literal %.

Each can be used any number of times.

ldap
====

The LDAP scheme is defined in RFC 2255.

man
===

The man scheme is a non-standard one.  Such URLs have the form

     man:PAGE-SPEC

and are retrieved by passing PAGE-SPEC to the Lisp function man.

General Facilities
******************

Disk Caching
============

The disk cache stores retrieved documents locally, whence they can be retrieved more quickly.  When requesting a URL that is in the cache, the library checks to see if the page has changed since it was last retrieved from the remote machine.  If not, the local copy is used, saving the transmission over the network. Currently the cache isn't cleared automatically.

 -- User Option: url-automatic-caching
     Setting this variable non-nil causes documents to be cached automatically.

 -- User Option: url-cache-directory
     This variable specifies the directory to store the cache files.  It defaults to sub-directory cache of url-configuration-directory.

 -- User Option: url-cache-creation-function
     The cache relies on a scheme for mapping URLs to files in the cache. This variable names a function which sets the type of cache to use. It takes a URL as argument and returns the absolute file name of the corresponding cache file.  The two supplied possibilities are url-cache-create-filename-using-md5 and url-cache-create-filename-human-readable.

 -- Function: url-cache-create-filename-using-md5 url
     Creates a cache file name from URL using MD5 hashing. This is creates entries with very few cache collisions and is fast.

          (url-cache-create-filename-using-md5 "http://www.example.com/foo/bar")
            => "/home/fx/.url/cache/fx/http/com/example/www/b8a35774ad20db71c7c3409a5410e74f"

 -- Function: url-cache-create-filename-human-readable url
     Creates a cache file name from URL more obviously connected to URL than for url-cache-create-filename-using-md5, but more likely to conflict with other files.

          (url-cache-create-filename-human-readable "http://www.example.com/foo/bar")
            => "/home/fx/.url/cache/fx/http/com/example/www/foo/bar"

 -- Function: url-cache-expired
     This function returns non-nil if a cache entry has expired (or is absent). The arguments are a URL and optional expiration delay in seconds (default URL-CACHE-EXPIRE-TIME).

 -- User Option: url-cache-expire-time
     This variable is the default number of seconds to use for the expire-time argument of the function url-cache-expired.

 -- Function: url-fetch-from-cache
     This function takes a URL as its argument and returns a buffer containing the data cached for that URL.

Proxies and Gatewaying
======================

Proxy servers are commonly used to provide gateways through firewalls or as caches serving some more-or-less local network.  Each protocol (HTTP, FTP, etc.) can have a different gateway server.  Proxying is conventionally configured commonly amongst different programs through environment variables of the form PROTOCOL_proxy, where PROTOCOL is one of the supported network protocols (http, ftp etc.).  The library recognizes such variables in either upper or lower case.  Their values are of one of the forms:

  * HOST:PORT

  * A full URL;

  * Simply a host name.

The NO_PROXY environment variable specifies URLs that should be excluded from proxying (on servers that should be contacted directly). This should be a comma-separated list of hostnames, domain names, or a mixture of both.  Asterisks can be used as wildcards, but other clients may not support that.  Domain names may be indicated by a leading dot.  For example:

     NO_PROXY="*.aventail.com,home.com,.seanet.com"

says to contact all machines in the aventail.com and seanet.com domains directly, as well as the machine named home.com.  If NO_PROXY isn't defined, no_PROXY and no_proxy are also tried, in that order.

Proxies may also be specified directly in Lisp.

 -- User Option: url-proxy-services
     This variable is an alist of URL schemes and proxy servers that gateway them.  The items are of the form (SCHEME . HOST:PORTNUMBER), says that the URL SCHEME is gatewayed through PORTNUMBER on the specified HOST.  An exception is the pseudo scheme "no_proxy", which is paired with a regexp matching host names not to be proxied.  This variable is initialized from the environment as above.

          (setq url-proxy-services
                '(("http"     . "proxy.aventail.com:80")
                  ("no_proxy" . "^.*\\(aventail\\|seanet\\)\\.com")))

Gateways in General
===================

The library provides a general gateway layer through which all networking passes.  It can both control access to the network and provide access through gateways in firewalls.  This may make direct connections in some cases and pass through some sort of gateway in others. (Proxies (which only operate over HTTP) are implemented using this.)  The library's basic function responsible for making connections is url-open-stream.

 -- Function: url-open-stream name buffer host service
     Open a stream to HOST, possibly via a gateway.  The other arguments are as for open-network-stream.  This will not make a connection if url-gateway-unplugged is non-nil.

 -- Variable: url-gateway-local-host-regexp
     This is a regular expression that matches local hosts that do not require the use of a gateway.  If nil, all connections are made through the gateway.

 -- Variable: url-gateway-method
     This variable controls which gateway method is used.  It may be useful to bind it temporarily in some applications.  It has values taken from a list of symbols.  Possible values are:

     telnet
          Use this method if you must first telnet and log into a gateway host, and then run telnet from that host to connect to outside machines.

     rlogin
          This method is identical to telnet, but uses rlogin to log into the remote machine without having to send the username and password over the wire every time.

     socks
          Use if the firewall has a SOCKS gateway running on it.  The SOCKS v5 protocol is defined in RFC 1928.

     native
          This method uses Emacs's builtin networking directly.  This is the default.  It can be used only if there is no firewall blocking access.

The following variables control the gateway methods.

 -- User Option: url-gateway-telnet-host
     The gateway host to telnet to.  Once logged in there, you then telnet out to the hosts you want to connect to.

 -- User Option: url-gateway-telnet-parameters
     This should be a list of parameters to pass to the telnet program.

 -- User Option: url-gateway-telnet-password-prompt
     This is a regular expression that matches the password prompt when logging in.

 -- User Option: url-gateway-telnet-login-prompt
     This is a regular expression that matches the username prompt when logging in.

 -- User Option: url-gateway-telnet-user-name
     The username to log in with.

 -- User Option: url-gateway-telnet-password
     The password to send when logging in.

 -- User Option: url-gateway-prompt-pattern
     This is a regular expression that matches the shell prompt.

 -- User Option: url-gateway-rlogin-host
     Host to rlogin to before telnetting out.

 -- User Option: url-gateway-rlogin-parameters
     Parameters to pass to rsh.

 -- User Option: url-gateway-rlogin-user-name
     User name to use when logging in to the gateway.

 -- User Option: url-gateway-prompt-pattern
     This is a regular expression that matches the shell prompt.

 -- User Option: socks-server
     This specifies the default server, it takes the form ("Default server" SERVER PORT VERSION) where VERSION can be either 4 or 5.

 -- Variable: socks-password
     If this is nil then you will be asked for the password, otherwise it will be used as the password for authenticating you to the SOCKS server.

 -- Variable: socks-username
     This is the username to use when authenticating yourself to the SOCKS server.  By default this is your login name.

 -- Variable: socks-timeout
     This controls how long, in seconds, to wait for responses from the SOCKS server; it is 5 by default.

 -- User Option: socks-nslookup-program
     This the nslookup program.  It is "nslookup" by default.

Suppressing Network Connections
-------------------------------

In some circumstances it is desirable to suppress making network connections.  A typical case is when rendering HTML in a mail user agent, when external URLs should not be activated, particularly to avoid ``bugs'' which ``call home'' by fetch single-pixel images and the like.  To arrange this, bind the following variable for the duration of such processing.

 -- Variable: url-gateway-unplugged
     If this variable is non-nil new network connections are never opened by the URL library.

History
=======

The library can maintain a global history list tracking URLs accessed. URL completion can be done from it.  The history mechanism is set up automatically via url-do-setup when it is configured to be on. Note that the size of the history list is currently not limited.

The history ``list'' is actually a hash table, url-history-hash-table.  It contains access times keyed by URL strings.  The times are in the format returned by current-time.

 -- Function: url-history-update-url url time
     This function updates the history table with an entry for URL accessed at the given TIME.

 -- User Option: url-history-track
     If non-nil, the library will keep track of all the URLs accessed.  If it is t, the list is saved to disk at the end of each Emacs session.  The default is nil.

 -- User Option: url-history-file
     The file storing the history list between sessions.  It defaults to history in url-configuration-directory.

 -- User Option: url-history-save-interval
     The number of seconds between automatic saves of the history list. Default is one hour.  Note that if you change this variable directly, rather than using Custom, after url-do-setup has been run, you need to run the function url-history-setup-save-timer.

 -- Function: url-history-parse-history &optional fname
     Parses the history file FNAME (default url-history-file) and sets up the history list.

 -- Function: url-history-save-history &optional fname
     Saves the current history to file FNAME (default url-history-file).

 -- Function: url-completion-function string predicate function
     You can use this function to do completion of URLs from the history.

Customization
*************

The following environment variables affect the url library's operation at startup.

TMPDIR
     If this is defined, URL-TEMPORARY-DIRECTORY is initialized from it.

The following user options affect the general operation of url library.

 -- User Option: url-configuration-directory
     The value of this variable specifies the name of the directory where the url library stores its various configuration files, cache files, etc.

     The default value specifies a subdirectory named url/ in the standard Emacs user data directory specified by the variable user-emacs-directory (normally ~/.emacs.d).  However, the old default was ~/.url, and this directory is used instead if it exists.

 -- User Option: url-debug
     Specifies the types of debug messages which are logged to the *URL-DEBUG* buffer. t means log all messages. A number means log all messages and show them with message. It may also be a list of the types of messages to be logged.

 -- User Option: url-personal-mail-address

 -- User Option: url-privacy-level

 -- User Option: url-uncompressor-alist

 -- User Option: url-passwd-entry-func

 -- User Option: url-standalone-mode

 -- User Option: url-bad-port-list

 -- User Option: url-max-password-attempts

 -- User Option: url-temporary-directory

 -- User Option: url-show-status

 -- User Option: url-confirmation-func
     The function to use for asking yes or no functions.  This is normally either y-or-n-p or yes-or-no-p, but could be another function taking a single argument (the prompt) and returning t only if an affirmative answer is given.

 -- User Option: url-gateway-method
     A symbol specifying the type of gateway support to use for connections from the local machine.  The supported methods are:

     telnet
          Run telnet in a subprocess to connect;

     rlogin
          Rlogin to another machine to connect;

     socks
          Connect through a socks server;

     ssl
          Connect with SSL;

     native
          Connect directly.

GNU Free Documentation License
******************************

     [file doclicense.texi not included]