Imported Upstream version 7.27.0

1 files changed, 207 insertions, 176 deletions

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index bfe58347..25a7d5e6 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -69,7 +69,7 @@ output. This is only relevant for protocols that actually have headers
 preceding the data (like HTTP).
 .IP CURLOPT_NOPROGRESS
 Pass a long. If set to 1, it tells the library to shut off the progress meter
-completely. It will also present the \fICURLOPT_PROGRESSFUNCTION\fP from
+completely. It will also prevent the \fICURLOPT_PROGRESSFUNCTION\fP from
 getting called.
 
 Future versions of libcurl are likely to not have any built-in progress meter
@@ -147,10 +147,10 @@ Using the rules above, a file name pattern can be constructed:
 (This was added in 7.21.0)
 .SH CALLBACK OPTIONS
 .IP CURLOPT_WRITEFUNCTION
-Function pointer that should match the following prototype: \fBsize_t
-function( char *ptr, size_t size, size_t nmemb, void *userdata);\fP This
-function gets called by libcurl as soon as there is data received that needs
-to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP
+Pass a pointer to a function that matches the following prototype:
+\fBsize_t function( char *ptr, size_t size, size_t nmemb, void *userdata);\fP
+This function gets called by libcurl as soon as there is data received that
+needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP
 multiplied with \fInmemb\fP, it will not be zero terminated. Return the number
 of bytes actually taken care of. If that amount differs from the amount passed
 to your function, it'll signal an error to the library. This will abort the
@@ -193,11 +193,11 @@ crashes.
 This option is also known with the older name \fICURLOPT_FILE\fP, the name
 \fICURLOPT_WRITEDATA\fP was introduced in 7.9.7.
 .IP CURLOPT_READFUNCTION
-Function pointer that should match the following prototype: \fBsize_t
-function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP This
-function gets called by libcurl as soon as it needs to read data in order to
-send it to the peer. The data area pointed at by the pointer \fIptr\fP may be
-filled with at most \fIsize\fP multiplied with \fInmemb\fP number of
+Pass a pointer to a function that matches the following prototype:
+\fBsize_t function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP
+This function gets called by libcurl as soon as it needs to read data in order
+to send it to the peer. The data area pointed at by the pointer \fIptr\fP may
+be filled with at most \fIsize\fP multiplied with \fInmemb\fP number of
 bytes. Your function must return the actual number of bytes that you stored in
 that memory area. Returning 0 will signal end-of-file to the library and cause
 it to stop the current transfer.
@@ -234,13 +234,13 @@ If you're using libcurl as a win32 DLL, you MUST use a
 This option was also known by the older name \fICURLOPT_INFILE\fP, the name
 \fICURLOPT_READDATA\fP was introduced in 7.9.7.
 .IP CURLOPT_IOCTLFUNCTION
-Function pointer that should match the \fIcurl_ioctl_callback\fP prototype
-found in \fI<curl/curl.h>\fP. This function gets called by libcurl when
-something special I/O-related needs to be done that the library can't do by
-itself. For now, rewinding the read data stream is the only action it can
-request. The rewinding of the read data stream may be necessary when doing a
-HTTP PUT or POST with a multi-pass authentication method.  (Option added in
-7.12.3).
+Pass a pointer to a function that matches the following prototype:
+\fBcurlioerr function(CURL *handle, int cmd, void *clientp);\fP. This function
+gets called by libcurl when something special I/O-related needs to be done
+that the library can't do by itself. For now, rewinding the read data stream
+is the only action it can request. The rewinding of the read data stream may
+be necessary when doing a HTTP PUT or POST with a multi-pass authentication
+method.  (Option added in 7.12.3).
 
 Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking!
 .IP CURLOPT_IOCTLDATA
@@ -248,7 +248,7 @@ Pass a pointer that will be untouched by libcurl and passed as the 3rd
 argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP.  (Option
 added in 7.12.3)
 .IP CURLOPT_SEEKFUNCTION
-Function pointer that should match the following prototype: \fIint
+Pass a pointer to a function that matches the following prototype: \fBint
 function(void *instream, curl_off_t offset, int origin);\fP This function gets
 called by libcurl to seek to a certain position in the input stream and can be
 used to fast forward a file in a resumed upload (instead of reading all
@@ -270,18 +270,18 @@ Data pointer to pass to the file seek function. If you use the
 \fICURLOPT_SEEKFUNCTION\fP option, this is the pointer you'll get as input. If
 you don't specify a seek callback, NULL is passed. (Option added in 7.18.0)
 .IP CURLOPT_SOCKOPTFUNCTION
-Function pointer that should match the \fIcurl_sockopt_callback\fP prototype
-found in \fI<curl/curl.h>\fP. This function gets called by libcurl after the
-socket() call but before the connect() call. The callback's \fIpurpose\fP
-argument identifies the exact purpose for this particular socket, and
-currently only one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the
-primary connection (meaning the control connection in the FTP case). Future
-versions of libcurl may support more purposes. It passes the newly created
-socket descriptor so additional setsockopt() calls can be done at the user's
-discretion.  Return 0 (zero) from the callback on success. Return 1 from the
-callback function to signal an unrecoverable error to the library and it will
-close the socket and return \fICURLE_COULDNT_CONNECT\fP.  (Option added in
-7.16.0)
+Pass a pointer to a function that matches the following prototype: \fBint
+function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. This
+function gets called by libcurl after the socket() call but before the
+connect() call. The callback's \fIpurpose\fP argument identifies the exact
+purpose for this particular socket, and currently only one value is supported:
+\fICURLSOCKTYPE_IPCXN\fP for the primary connection (meaning the control
+connection in the FTP case). Future versions of libcurl may support more
+purposes. It passes the newly created socket descriptor so additional
+setsockopt() calls can be done at the user's discretion.  Return 0 (zero) from
+the callback on success. Return 1 from the callback function to signal an
+unrecoverable error to the library and it will close the socket and return
+\fICURLE_COULDNT_CONNECT\fP.  (Option added in 7.16.0)
 
 Added in 7.21.5, the callback function may return
 \fICURL_SOCKOPT_ALREADY_CONNECTED\fP, which tells libcurl that the socket is
@@ -291,20 +291,21 @@ Pass a pointer that will be untouched by libcurl and passed as the first
 argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP.
 (Option added in 7.16.0)
 .IP CURLOPT_OPENSOCKETFUNCTION
-Function pointer that should match the \fIcurl_opensocket_callback\fP
-prototype found in \fI<curl/curl.h>\fP. This function gets called by libcurl
-instead of the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument
-identifies the exact purpose for this particular socket:
-\fICURLSOCKTYPE_IPCXN\fP is for IP based connections. Future versions of
-libcurl may support more purposes. It passes the resolved peer address as a
-\fIaddress\fP argument so the callback can modify the address or refuse to
-connect at all. The callback function should return the socket or
-\fICURL_SOCKET_BAD\fP in case no connection should be established or any error
-detected. Any additional \fIsetsockopt(2)\fP calls can be done on the socket
-at the user's discretion.  \fICURL_SOCKET_BAD\fP return value from the
-callback function will signal an unrecoverable error to the library and it
-will return \fICURLE_COULDNT_CONNECT\fP.  This return code can be used for IP
-address blacklisting.  The default behavior is:
+Pass a pointer to a function that matches the following prototype:
+\fBcurl_socket_t function(void *clientp, curlsocktype purpose, struct
+curl_sockaddr *address);\fP. This function gets called by libcurl instead of
+the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument identifies the
+exact purpose for this particular socket: \fICURLSOCKTYPE_IPCXN\fP is for IP
+based connections. Future versions of libcurl may support more purposes. It
+passes the resolved peer address as a \fIaddress\fP argument so the callback
+can modify the address or refuse to connect at all. The callback function
+should return the socket or \fICURL_SOCKET_BAD\fP in case no connection could
+be established or another error was detected. Any additional
+\fIsetsockopt(2)\fP calls can be done on the socket at the user's discretion.
+\fICURL_SOCKET_BAD\fP return value from the callback function will signal an
+unrecoverable error to the library and it will return
+\fICURLE_COULDNT_CONNECT\fP.  This return code can be used for IP address
+blacklisting.  The default behavior is:
 .nf
    return socket(addr->family, addr->socktype, addr->protocol);
 .fi
@@ -314,25 +315,26 @@ Pass a pointer that will be untouched by libcurl and passed as the first
 argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP.
 (Option added in 7.17.1.)
 .IP CURLOPT_CLOSESOCKETFUNCTION
-Function pointer that should match the \fIcurl_closesocket_callback\fP
-prototype found in \fI<curl/curl.h>\fP. This function gets called by libcurl
-instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when sockets are
-closed (not for any other file descriptors). This is pretty much the reverse
-to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal success and
-1 if there was an error.  (Option added in 7.21.7)
+Pass a pointer to a function that matches the following prototype: \fBint
+function(void *clientp, curl_socket_t item);\fP. This function gets called by
+libcurl instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when
+sockets are closed (not for any other file descriptors). This is pretty much
+the reverse to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal
+success and 1 if there was an error.  (Option added in 7.21.7)
 .IP CURLOPT_CLOSESOCKETDATA
 Pass a pointer that will be untouched by libcurl and passed as the first
 argument in the closesocket callback set with
 \fICURLOPT_CLOSESOCKETFUNCTION\fP.  (Option added in 7.21.7)
 .IP CURLOPT_PROGRESSFUNCTION
-Function pointer that should match the \fIcurl_progress_callback\fP prototype
-found in \fI<curl/curl.h>\fP. This function gets called by libcurl instead of
-its internal equivalent with a frequent interval during operation (roughly
-once per second or sooner) no matter if data is being transfered or not.
-Unknown/unused argument values passed to the callback will be set to zero
-(like if you only download data, the upload size will remain 0). Returning a
-non-zero value from this callback will cause libcurl to abort the transfer and
-return \fICURLE_ABORTED_BY_CALLBACK\fP.
+Pass a pointer to a function that matches the following prototype: \fBint
+function(void *clientp, double dltotal, double dlnow, double ultotal, double
+ulnow); \fP. This function gets called by libcurl instead of its internal
+equivalent with a frequent interval during operation (roughly once per second
+or sooner) no matter if data is being transferred or not.  Unknown/unused
+argument values passed to the callback will be set to zero (like if you only
+download data, the upload size will remain 0). Returning a non-zero value from
+this callback will cause libcurl to abort the transfer and return
+\fICURLE_ABORTED_BY_CALLBACK\fP.
 
 If you transfer data with the multi interface, this function will not be
 called during periods of idleness unless you call the appropriate libcurl
@@ -344,14 +346,14 @@ get called.
 Pass a pointer that will be untouched by libcurl and passed as the first
 argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP.
 .IP CURLOPT_HEADERFUNCTION
-Function pointer that should match the following prototype: \fIsize_t
-function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP. This
-function gets called by libcurl as soon as it has received header data. The
-header callback will be called once for each header and only complete header
-lines are passed on to the callback. Parsing headers is very easy using
-this. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied
-with \fInmemb\fP. Do not assume that the header line is zero terminated! The
-pointer named \fIuserdata\fP is the one you set with the
+Pass a pointer to a function that matches the following prototype:
+\fBsize_t function( void *ptr, size_t size, size_t nmemb, void
+*userdata);\fP. This function gets called by libcurl as soon as it has
+received header data. The header callback will be called once for each header
+and only complete header lines are passed on to the callback. Parsing headers
+is very easy using this. The size of the data pointed to by \fIptr\fP is
+\fIsize\fP multiplied with \fInmemb\fP. Do not assume that the header line is
+zero terminated! The pointer named \fIuserdata\fP is the one you set with the
 \fICURLOPT_WRITEHEADER\fP option. The callback function must return the number
 of bytes actually taken care of. If that amount differs from the amount passed
 to your function, it'll signal an error to the library. This will abort the
@@ -391,7 +393,7 @@ the writing, this must be a valid FILE * as the internal default will then be
 a plain fwrite(). See also the \fICURLOPT_HEADERFUNCTION\fP option above on
 how to set a custom get-all-headers callback.
 .IP CURLOPT_DEBUGFUNCTION
-Function pointer that should match the following prototype: \fIint
+Pass a pointer to a function that matches the following prototype: \fBint
 curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP
 \fICURLOPT_DEBUGFUNCTION\fP replaces the standard debug function used when
 \fICURLOPT_VERBOSE \fP is in effect. This callback receives debug information,
@@ -420,11 +422,11 @@ used by libcurl, it is only passed to the callback.
 This option does only function for libcurl powered by OpenSSL. If libcurl was
 built against another SSL library, this functionality is absent.
 
-Function pointer that should match the following prototype: \fBCURLcode
-sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called
-by libcurl just before the initialization of a SSL connection after having
-processed all other SSL related options to give a last chance to an
-application to modify the behaviour of openssl's ssl initialization. The
+Pass a pointer to a function that matches the following prototype:
+\fBCURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function
+gets called by libcurl just before the initialization of a SSL connection
+after having processed all other SSL related options to give a last chance to
+an application to modify the behaviour of openssl's ssl initialization. The
 \fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If
 an error is returned no attempt to establish a connection is made and the
 perform operation will return the error code from this callback function.  Set
@@ -447,8 +449,8 @@ parameter, otherwise \fBNULL\fP. (Added in 7.11.0)
 .IP CURLOPT_CONV_TO_NETWORK_FUNCTION
 .IP CURLOPT_CONV_FROM_NETWORK_FUNCTION
 .IP CURLOPT_CONV_FROM_UTF8_FUNCTION
-Function pointers that should match the following prototype: CURLcode
-function(char *ptr, size_t length);
+Pass a pointer to a function that matches the following prototype:
+\fBCURLcode function(char *ptr, size_t length);\fP
 
 These three options apply to non-ASCII platforms only.  They are available
 only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. When
@@ -490,18 +492,19 @@ follows:
 You will need to override these definitions if they are different on your
 system.
 .IP CURLOPT_INTERLEAVEFUNCTION
-Function pointer that should match the following prototype: \fIsize_t
-function( void *ptr, size_t size, size_t nmemb, void *userdata)\fP. This
-function gets called by libcurl as soon as it has received interleaved RTP
-data. This function gets called for each $ block and therefore contains
-exactly one upper-layer protocol unit (e.g.  one RTP packet). Curl writes the
-interleaved header as well as the included data for each call. The first byte
-is always an ASCII dollar sign. The dollar sign is followed by a one byte
-channel identifier and then a 2 byte integer length in network byte order. See
-\fIRFC 2326 Section 10.12\fP for more information on how RTP interleaving
-behaves. If unset or set to NULL, curl will use the default write function.
-
-Interleaved RTP poses some challeneges for the client application. Since the
+Pass a pointer to a function that matches the following prototype:
+\fBsize_t function( void *ptr, size_t size, size_t nmemb, void
+*userdata)\fP. This function gets called by libcurl as soon as it has received
+interleaved RTP data. This function gets called for each $ block and therefore
+contains exactly one upper-layer protocol unit (e.g.  one RTP packet). Curl
+writes the interleaved header as well as the included data for each call. The
+first byte is always an ASCII dollar sign. The dollar sign is followed by a
+one byte channel identifier and then a 2 byte integer length in network byte
+order. See \fIRFC2326 Section 10.12\fP for more information on how RTP
+interleaving behaves. If unset or set to NULL, curl will use the default write
+function.
+
+Interleaved RTP poses some challenges for the client application. Since the
 stream data is sharing the RTSP control connection, it is critical to service
 the RTP in a timely fashion. If the RTP data is not handled quickly,
 subsequent response processing may become unreasonably delayed and the
@@ -515,10 +518,10 @@ This is the userdata pointer that will be passed to
 \fICURLOPT_INTERLEAVEFUNCTION\fP when interleaved RTP data is received. (Added
 in 7.20.0)
 .IP CURLOPT_CHUNK_BGN_FUNCTION
-Function pointer that should match the following prototype: \fBlong function
-(const void *transfer_info, void *ptr, int remains)\fP. This function gets
-called by libcurl before a part of the stream is going to be transferred (if
-the transfer supports chunks).
+Pass a pointer to a function that matches the following prototype:
+\fBlong function (const void *transfer_info, void *ptr, int remains)\fP. This
+function gets called by libcurl before a part of the stream is going to be
+transferred (if the transfer supports chunks).
 
 This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH\fP
 option for now.
@@ -535,9 +538,9 @@ Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine,
 \fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred.
 (This was added in 7.21.0)
 .IP CURLOPT_CHUNK_END_FUNCTION
-Function pointer that should match the following prototype: \fBlong
-function(void *ptr)\fP. This function gets called by libcurl as soon as a part
-of the stream has been transferred (or skipped).
+Pass a pointer to a function that matches the following prototype:
+\fBlong function(void *ptr)\fP. This function gets called by libcurl as soon
+as a part of the stream has been transferred (or skipped).
 
 Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or
 \fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred.
@@ -547,9 +550,9 @@ Pass a pointer that will be untouched by libcurl and passed as the ptr
 argument to the \fICURL_CHUNK_BGN_FUNTION\fP and \fICURL_CHUNK_END_FUNTION\fP.
 (This was added in 7.21.0)
 .IP CURLOPT_FNMATCH_FUNCTION
-Function pointer that should match \fBint function(void *ptr, const char
-*pattern, const char *string)\fP prototype (see \fIcurl/curl.h\fP). It is used
-internally for the wildcard matching feature.
+Pass a pointer to a function that matches the following prototype: \fBint
+function(void *ptr, const char *pattern, const char *string)\fP prototype (see
+\fIcurl/curl.h\fP). It is used internally for the wildcard matching feature.
 
 Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string,
 \fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an
@@ -563,11 +566,11 @@ Pass a char * to a buffer that the libcurl may store human readable error
 messages in. This may be more helpful than just the return code from
 \fIcurl_easy_perform\fP. The buffer must be at least CURL_ERROR_SIZE big.
 Although this argument is a 'char *', it does not describe an input string.
-Therefore the (probably undefined) contents of the buffer is NOT copied
-by the library. You should keep the associated storage available until
-libcurl no longer needs it. Failing to do so will cause very odd behavior
-or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP
-or you set the same option again to use a different pointer.
+Therefore the (probably undefined) contents of the buffer is NOT copied by the
+library. You must keep the associated storage available until libcurl no
+longer needs it. Failing to do so will cause very odd behavior or even
+crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP or you
+set the same option again to use a different pointer.
 
 Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better
 debug/trace why errors happen.
@@ -592,13 +595,13 @@ detected, like when a "100-continue" is received as a response to a
 POST/PUT and a 401 or 407 is received immediately afterwards.
 .SH NETWORK OPTIONS
 .IP CURLOPT_URL
-The actual URL to deal with. The parameter should be a char * to a zero
-terminated string which must be URL-encoded in the following format:
+Pass in a pointer to the actual URL to deal with. The parameter should be a
+char * to a zero terminated string which must be URL-encoded in the following
+format:
 
 scheme://host:port/path
 
-For a greater explanation of the format please see RFC 3986
-(http://curl.haxx.se/rfc/rfc3986.txt).
+For a greater explanation of the format please see RFC3986.
 
 If the given URL lacks the scheme, or protocol, part ("http://" or "ftp://"
 etc), libcurl will attempt to resolve which protocol to use based on the
@@ -626,18 +629,20 @@ authentication.
 
 For example the following types of authentication support this:
 
-http://user:password@www.domain.com
-ftp://user:password@ftp.domain.com
-pop3://user:password@mail.domain.com
+http://user:password@www.example.com
+
+ftp://user:password@ftp.example.com
+
+pop3://user:password@mail.example.com
 
 The port is optional and when not specified libcurl will use the default port
-based on the determined or specified protocol: 80 for http, 21 for ftp and 25
-for smtp, etc. The following examples show how to specify the port:
+based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25
+for SMTP, etc. The following examples show how to specify the port:
 
-http://www.weirdserver.com:8080/ - This will connect to a web server using
-port 8080.
+http://www.example.com:8080/ - This will connect to a web server using port
+8080 rather than 80.
 
-smtp://mail.domain.com:587/ - This will connect to a smtp server on the
+smtp://mail.example.com:587/ - This will connect to a SMTP server on the
 alternative mail port.
 
 The path part of the URL is protocol specific and whilst some examples are
@@ -652,13 +657,12 @@ retrieved for either the directory specified or the root directory. The
 exact resource returned for each URL is entirely dependent on the server's
 configuration.
 
-http://www.netscape.com - This gets the main page (index.html in this
-example) from Netscape's web server.
+http://www.example.com - This gets the main page from the web server.
 
-http://www.netscape.com/index.html - This returns the main page from Netscape
-by specifying the page to get.
+http://www.example.com/index.html - This returns the main page by explicitly
+requesting it.
 
-http://www.netscape.com/contactus/ - This returns the default document from
+http://www.example.com/contactus/ - This returns the default document from
 the contactus directory.
 
 .B FTP
@@ -668,15 +672,16 @@ directory. If the file part is omitted then libcurl downloads the directory
 listing for the directory specified. If the directory is omitted then
 the directory listing for the root / home directory will be returned.
 
-ftp://cool.haxx.se - This retrieves the directory listing for our FTP server.
+ftp://ftp.example.com - This retrieves the directory listing for the root
+directory.
 
-ftp://cool.haxx.se/readme.txt - This downloads the file readme.txt from the
+ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the
 root directory.
 
-ftp://cool.haxx.se/libcurl/readme.txt - This downloads readme.txt from the
+ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the
 libcurl directory.
 
-ftp://user:password@my.example.com/readme.txt - This retrieves the readme.txt
+ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt
 file from the user's home directory. When a username and password is
 specified, everything that is specified in the path part is relative to the
 user's home directory. To retrieve files from the root directory or a
@@ -684,7 +689,7 @@ directory underneath the root directory then the absolute path must be
 specified by prepending an additional forward slash to the beginning of the
 path.
 
-ftp://user:password@my.example.com//readme.txt - This retrieves the readme.txt
+ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt
 from the root directory when logging in as a specified user.
 
 .B SMTP
@@ -697,11 +702,11 @@ and specifying this path allows you to set an alternative name, such as
 your machine's fully qualified domain name, which you might have obtained
 from an external function such as gethostname or getaddrinfo.
 
-smtp://mail.domain.com - This connects to the mail server at domain.com and
+smtp://mail.example.com - This connects to the mail server at example.com and
 sends your local computer's host name in the HELO / EHLO command.
 
-smtp://mail.domain.com/client.domain.com - This will send client.domain.com in
-the HELO / EHLO command to the mail server at domain.com.
+smtp://mail.example.com/client.example.com - This will send client.example.com in
+the HELO / EHLO command to the mail server at example.com.
 
 .B POP3
 
@@ -709,8 +714,8 @@ The path part of a POP3 request specifies the mailbox (message) to retrieve.
 If the mailbox is not specified then a list of waiting messages is returned
 instead.
 
-pop3://user:password@mail.domain.com - This lists the available messages
-pop3://user:password@mail.domain.com/1 - This retrieves the first message
+pop3://user:password@mail.example.com - This lists the available messages
+pop3://user:password@mail.example.com/1 - This retrieves the first message
 
 .B SCP
 
@@ -745,6 +750,26 @@ user's home directory
 sftp://ssh.example.com/~/Documents/ - This requests a directory listing
 of the Documents directory under the user's home directory
 
+.B LDAP
+
+The path part of a LDAP request can be used to specify the: Distinguished
+Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field
+is separated by a question mark and when that field is not required an empty
+string with the question mark separator should be included.
+
+ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search
+with the DN as My Organisation.
+
+ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform
+the same search but will only return postalAddress attributes.
+
+ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN
+and requests information about the rootDomainNamingContext attribute for an
+Active Directory server.
+
+For more information about the individual components of a LDAP URL please
+see RFC4516.
+
 .B NOTES
 
 Starting with version 7.20.0, the fragment part of the URI will not be sent as
@@ -820,13 +845,14 @@ affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version
 used for "regular" HTTP requests is instead controlled with
 \fICURLOPT_HTTP_VERSION\fP.
 .IP CURLOPT_NOPROXY
-Pass a pointer to a zero terminated string. This should be a comma separated
-list of hosts which do not use a proxy, if one is specified.  The only
-wildcard is a single * character, which matches all hosts, and effectively
-disables the proxy. Each name in this list is matched as either a domain which
-contains the hostname, or the hostname itself. For example, local.com would
-match local.com, local.com:80, and www.local.com, but not www.notlocal.com.
-(Added in 7.19.4)
+Pass a pointer to a zero terminated string. The string consists of a comma
+separated list of host names that do not require a proxy to get reached, even
+if one is specified.  The only wildcard available is a single * character,
+which matches all hosts, and effectively disables the proxy. Each name in this
+list is matched as either a domain which contains the hostname, or the
+hostname itself. For example, example.com would match example.com,
+example.com:80, and www.example.com, but not www.notanexample.com.  (Added in
+7.19.4)
 .IP CURLOPT_HTTPPROXYTUNNEL
 Set the parameter to 1 to make the library tunnel all operations through a
 given HTTP proxy. There is a big difference between using a proxy and to
@@ -838,7 +864,7 @@ default service name for a SOCKS5 server is rcmd/server-fqdn. This option
 allows you to change it. (Added in 7.19.4)
 .IP CURLOPT_SOCKS5_GSSAPI_NEC
 Pass a long set to 1 to enable or 0 to disable. As part of the gssapi
-negotiation a protection mode is negotiated. The rfc1961 says in section
+negotiation a protection mode is negotiated. The RFC1961 says in section
 4.3/4.4 it should be protected, but the NEC reference implementation does not.
 If enabled, this option allows the unprotected exchange of the protection mode
 negotiation. (Added in 7.19.4).
@@ -861,7 +887,7 @@ connection. This can be used in combination with \fICURLOPT_INTERFACE\fP and
 you are recommended to use \fICURLOPT_LOCALPORTRANGE\fP as well when this is
 set. Valid port numbers are 1 - 65535. (Added in 7.15.2)
 .IP CURLOPT_LOCALPORTRANGE
-Pass a long. This is the number of attempts libcurl should make to find a
+Pass a long. This is the number of attempts libcurl will make to find a
 working local port number. It starts with the given \fICURLOPT_LOCALPORT\fP
 and adds one to the number for each retry. Setting this to 1 or below will
 make libcurl do only one try for the exact port number. Port numbers by nature
@@ -900,21 +926,20 @@ only makes sense to use this option if you want it smaller.
 Pass a long specifying what remote port number to connect to, instead of the
 one specified in the URL or the default port for the used protocol.
 .IP CURLOPT_TCP_NODELAY
-Pass a long specifying whether the TCP_NODELAY option should be set or
-cleared (1 = set, 0 = clear). The option is cleared by default. This
-will have no effect after the connection has been established.
+Pass a long specifying whether the TCP_NODELAY option is to be set or cleared
+(1 = set, 0 = clear). The option is cleared by default. This will have no
+effect after the connection has been established.
 
-Setting this option will disable TCP's Nagle algorithm. The purpose of
-this algorithm is to try to minimize the number of small packets on
-the network (where "small packets" means TCP segments less than the
-Maximum Segment Size (MSS) for the network).
+Setting this option will disable TCP's Nagle algorithm. The purpose of this
+algorithm is to try to minimize the number of small packets on the network
+(where "small packets" means TCP segments less than the Maximum Segment Size
+(MSS) for the network).
 
 Maximizing the amount of data sent per TCP segment is good because it
-amortizes the overhead of the send. However, in some cases (most
-notably telnet or rlogin) small segments may need to be sent
-without delay. This is less efficient than sending larger amounts of
-data at a time, and can contribute to congestion on the network if
-overdone.
+amortizes the overhead of the send. However, in some cases (most notably
+telnet or rlogin) small segments may need to be sent without delay. This is
+less efficient than sending larger amounts of data at a time, and can
+contribute to congestion on the network if overdone.
 .IP CURLOPT_ADDRESS_SCOPE
 Pass a long specifying the scope_id value to use when connecting to IPv6
 link-local or site-local addresses. (Added in 7.19.0)
@@ -1099,7 +1124,7 @@ authentication method(s) you want it to use for TLS authentication.
 .RS
 .IP CURLOPT_TLSAUTH_SRP
 TLS-SRP authentication. Secure Remote Password authentication for TLS is
-defined in RFC 5054 and provides mutual authentication if both sides have a
+defined in RFC5054 and provides mutual authentication if both sides have a
 shared secret. To use TLS-SRP, you must also set the
 \fICURLOPT_TLSAUTH_USERNAME\fP and \fICURLOPT_TLSAUTH_PASSWORD\fP options.
 
@@ -1148,8 +1173,8 @@ the server is ignored. See the special file lib/README.encoding for details.
 .IP CURLOPT_TRANSFER_ENCODING
 Adds a request for compressed Transfer Encoding in the outgoing HTTP
 request. If the server supports this and so desires, it can respond with the
-HTTP resonse sent using a compressed Transfer-Encoding that will be
-automatically uncompressed by libcurl on receival.
+HTTP response sent using a compressed Transfer-Encoding that will be
+automatically uncompressed by libcurl on reception.
 
 Transfer-Encoding differs slightly from the Content-Encoding you ask for with
 \fBCURLOPT_ACCEPT_ENCODING\fP in that a Transfer-Encoding is strictly meant to
@@ -1184,19 +1209,19 @@ an infinite number of redirects (which is the default)
 .IP CURLOPT_POSTREDIR
 Pass a bitmask to control how libcurl acts on redirects after POSTs that get a
 301, 302 or 303 response back.  A parameter with bit 0 set (value
-\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 2616/10.3.2 and
-not convert POST requests into GET requests when following a 301
-redirection. Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain
-the request method after a 302 redirect. Setting bit 2 (value
-\fBCURL_REDIR_POST_303) makes libcurl maintain the request method after a 302
-redirect. CURL_REDIR_POST_ALL is a convenience define that sets both bits.
+\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC2616/10.3.2 and not
+convert POST requests into GET requests when following a 301 redirection.
+Setting bit 1 (value \fBCURL_REDIR_POST_302\fP) makes libcurl maintain the
+request method after a 302 redirect whilst setting bit 2 (value
+\fBCURL_REDIR_POST_303\fP) makes libcurl maintain the request method after a
+303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience define that
+sets all three bits.
 
 The non-RFC behaviour is ubiquitous in web browsers, so the library does the
 conversion by default to maintain consistency. However, a server may require a
 POST to remain a POST after such a redirection. This option is meaningful only
 when setting \fICURLOPT_FOLLOWLOCATION\fP.  (Added in 7.17.1) (This option was
-known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 way before
-then)
+known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 then)
 .IP CURLOPT_PUT
 A parameter set to 1 tells the library to use HTTP PUT to transfer data. The
 data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP.
@@ -1487,16 +1512,16 @@ should be used for this parameter.
 Unlike CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT, the address should not be
 specified within a pair of angled brackets (<>). However, if an empty string
 is used then a pair of brackets will be sent by libcurl as required by
-RFC-2554.
+RFC2554.
 
-(Added in 7.24.0)
+(Added in 7.25.0)
 .SH TFTP OPTIONS
 .IP CURLOPT_TFTP_BLKSIZE
-Specify block size to use for TFTP data transmission. Valid range as per RFC
-2348 is 8-65464 bytes. The default of 512 bytes will be used if this option is
-not specified. The specified block size will only be used pending support by
-the remote server. If the server does not return an option acknowledgement or
-returns an option acknowledgement with no blksize, the default of 512 bytes
+Specify block size to use for TFTP data transmission. Valid range as per
+RFC2348 is 8-65464 bytes. The default of 512 bytes will be used if this option
+is not specified. The specified block size will only be used pending support
+by the remote server. If the server does not return an option acknowledgement
+or returns an option acknowledgement with no blksize, the default of 512 bytes
 will be used. (added in 7.19.4)
 .SH FTP OPTIONS
 .IP CURLOPT_FTPPORT
@@ -1611,7 +1636,7 @@ already exists or lack of permissions prevents creation. (Added in 7.16.3)
 
 Starting with 7.19.4, you can also set this value to 2, which will make
 libcurl retry the CWD command again if the subsequent MKD command fails. This
-is especially useful if you're doing many simultanoes connections against the
+is especially useful if you're doing many simultaneous connections against the
 same server and they all have this option enabled, as then CWD may first fail
 but then another connection does MKD before this connection and thus MKD fails
 but trying CWD works! 7.19.4 also introduced the \fICURLFTP_CREATE_DIR\fP and
@@ -1698,7 +1723,7 @@ initialized. (Added in 7.20.0)
 .RS
 .IP CURL_RTSPREQ_OPTIONS
 Used to retrieve the available methods of the server. The application is
-responsbile for parsing and obeying the response. \fB(The session ID is not
+responsible for parsing and obeying the response. \fB(The session ID is not
 needed for this method.)\fP  (Added in 7.20.0)
 .IP CURL_RTSPREQ_DESCRIBE
 Used to get the low level description of a stream. The application should note
@@ -1821,7 +1846,7 @@ want. It should be in the format "X-Y", where X or Y may be left out. HTTP
 transfers also support several intervals, separated with commas as in
 \fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP
 server to send the response document in pieces (using standard MIME separation
-techniques). For RTSP, the formatting of a range should follow RFC 2326
+techniques). For RTSP, the formatting of a range should follow RFC2326
 Section 12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges
 should be given in npt, utc, or smpte formats.
 
@@ -1858,12 +1883,18 @@ something, you don't actually change how libcurl behaves or acts in regards
 to the particular request method, it will only change the actual string sent
 in the request.
 
-For example: if you tell libcurl to do a HEAD request, but then change the
-request to a "GET" with \fBCURLOPT_CUSTOMREQUEST\fP you'll still see libcurl
-act as if it sent a HEAD even when it does send a GET.
+For example:
+
+With the HTTP protocol when you tell libcurl to do a HEAD request, but then
+specify a GET though a custom request libcurl will still act as if it sent a
+HEAD. To switch to a proper HEAD use \fICURLOPT_NOBODY\fP, to switch to a
+proper POST use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and to switch
+to a proper GET use CURLOPT_HTTPGET.
 
-To switch to a proper HEAD, use \fICURLOPT_NOBODY\fP, to switch to a proper
-POST, use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and so on.
+With the POP3 protocol when you tell libcurl to use a custom request it will
+behave like a LIST or RETR command was sent where it expects data to be
+returned by the server. As such \fICURLOPT_NOBODY\fP should be used when
+specifying commands such as DELE and NOOP for example.
 
 Restore to the internal default by setting this to NULL.
 
@@ -2348,7 +2379,7 @@ require you to disable this in order for you to succeed. (Added in 7.16.0)
 Pass a long with a bitmask to tell libcurl about specific SSL behaviors.
 
 CURLSSLOPT_ALLOW_BEAST is the only supported bit and by setting this the user
-will tell libcurl to not attempt to use any work-arounds for a security flaw
+will tell libcurl to not attempt to use any workarounds for a security flaw
 in the SSL3 and TLS1.0 protocols.  If this option isn't used or this bit is
 set to 0, the SSL layer libcurl uses may use a work-around for this flaw
 although it might cause interoperability problems with some (older) SSL