curl_easy_setopt.3: proto updates + cleanups

- For all *FUNCTION options, they now all show the complete prototype in
  the description. Previously some of them would just refer to a
  typedef'ed function pointer in the curl.h header.

- I made the phrasing of that "Pass a pointer to a function that matches
  the following prototype" the same for all *FUNCTION option descriptions.

- I removed some uses of 'should'. I think I sometimes over-use this
  word as in many places I actually mean MUST or otherwise more specific
  and not-so-optional synonyms.

docs/libcurl/curl_easy_setopt.3

@@ -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
+Pass a pointer to a function that matches the following prototype:
-function( char *ptr, size_t size, size_t nmemb, void *userdata);\fP This
+\fBsize_t function( char *ptr, size_t size, size_t nmemb, void *userdata);\fP
-function gets called by libcurl as soon as there is data received that needs
+This function gets called by libcurl as soon as there is data received that
-to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP
+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
+Pass a pointer to a function that matches the following prototype:
-function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP This
+\fBsize_t function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP
-function gets called by libcurl as soon as it needs to read data in order to
+This function gets called by libcurl as soon as it needs to read data in order
-send it to the peer. The data area pointed at by the pointer \fIptr\fP may be
+to send it to the peer. The data area pointed at by the pointer \fIptr\fP may
-filled with at most \fIsize\fP multiplied with \fInmemb\fP number of
+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
+Pass a pointer to a function that matches the following prototype:
-found in \fI<curl/curl.h>\fP. This function gets called by libcurl when
+\fBcurlioerr function(CURL *handle, int cmd, void *clientp);\fP. This function
-something special I/O-related needs to be done that the library can't do by
+gets called by libcurl when something special I/O-related needs to be done
-itself. For now, rewinding the read data stream is the only action it can
+that the library can't do by itself. For now, rewinding the read data stream
-request. The rewinding of the read data stream may be necessary when doing a
+is the only action it can request. The rewinding of the read data stream may
-HTTP PUT or POST with a multi-pass authentication method.  (Option added in
+be necessary when doing a HTTP PUT or POST with a multi-pass authentication
-7.12.3).
+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
+Pass a pointer to a function that matches the following prototype: \fBint
-found in \fI<curl/curl.h>\fP. This function gets called by libcurl after the
+function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. This
-socket() call but before the connect() call. The callback's \fIpurpose\fP
+function gets called by libcurl after the socket() call but before the
-argument identifies the exact purpose for this particular socket, and
+connect() call. The callback's \fIpurpose\fP argument identifies the exact
-currently only one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the
+purpose for this particular socket, and currently only one value is supported:
-primary connection (meaning the control connection in the FTP case). Future
+\fICURLSOCKTYPE_IPCXN\fP for the primary connection (meaning the control
-versions of libcurl may support more purposes. It passes the newly created
+connection in the FTP case). Future versions of libcurl may support more
-socket descriptor so additional setsockopt() calls can be done at the user's
+purposes. It passes the newly created socket descriptor so additional
-discretion.  Return 0 (zero) from the callback on success. Return 1 from the
+setsockopt() calls can be done at the user's discretion.  Return 0 (zero) from
-callback function to signal an unrecoverable error to the library and it will
+the callback on success. Return 1 from the callback function to signal an
-close the socket and return \fICURLE_COULDNT_CONNECT\fP.  (Option added in
+unrecoverable error to the library and it will close the socket and return
-7.16.0)
+\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
+Pass a pointer to a function that matches the following prototype:
-prototype found in \fI<curl/curl.h>\fP. This function gets called by libcurl
+\fBcurl_socket_t function(void *clientp, curlsocktype purpose, struct
-instead of the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument
+curl_sockaddr *address);\fP. This function gets called by libcurl instead of
-identifies the exact purpose for this particular socket:
+the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument identifies the
-\fICURLSOCKTYPE_IPCXN\fP is for IP based connections. Future versions of
+exact purpose for this particular socket: \fICURLSOCKTYPE_IPCXN\fP is for IP
-libcurl may support more purposes. It passes the resolved peer address as a
+based connections. Future versions of libcurl may support more purposes. It
-\fIaddress\fP argument so the callback can modify the address or refuse to
+passes the resolved peer address as a \fIaddress\fP argument so the callback
-connect at all. The callback function should return the socket or
+can modify the address or refuse to connect at all. The callback function
-\fICURL_SOCKET_BAD\fP in case no connection should be established or any error
+should return the socket or \fICURL_SOCKET_BAD\fP in case no connection could
-detected. Any additional \fIsetsockopt(2)\fP calls can be done on the socket
+be established or another error was detected. Any additional
-at the user's discretion.  \fICURL_SOCKET_BAD\fP return value from the
+\fIsetsockopt(2)\fP calls can be done on the socket at the user's discretion.
-callback function will signal an unrecoverable error to the library and it
+\fICURL_SOCKET_BAD\fP return value from the callback function will signal an
-will return \fICURLE_COULDNT_CONNECT\fP.  This return code can be used for IP
+unrecoverable error to the library and it will return
-address blacklisting.  The default behavior is:
+\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
+Pass a pointer to a function that matches the following prototype: \fBint
-prototype found in \fI<curl/curl.h>\fP. This function gets called by libcurl
+function(void *clientp, curl_socket_t item);\fP. This function gets called by
-instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when sockets are
+libcurl instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when
-closed (not for any other file descriptors). This is pretty much the reverse
+sockets are closed (not for any other file descriptors). This is pretty much
-to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal success and
+the reverse to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal
-1 if there was an error.  (Option added in 7.21.7)
+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
+Pass a pointer to a function that matches the following prototype: \fBint
-found in \fI<curl/curl.h>\fP. This function gets called by libcurl instead of
+function(void *clientp, double dltotal, double dlnow, double ultotal, double
-its internal equivalent with a frequent interval during operation (roughly
+ulnow); \fP. This function gets called by libcurl instead of its internal
-once per second or sooner) no matter if data is being transfered or not.
+equivalent with a frequent interval during operation (roughly once per second
-Unknown/unused argument values passed to the callback will be set to zero
+or sooner) no matter if data is being transfered or not.  Unknown/unused
-(like if you only download data, the upload size will remain 0). Returning a
+argument values passed to the callback will be set to zero (like if you only
-non-zero value from this callback will cause libcurl to abort the transfer and
+download data, the upload size will remain 0). Returning a non-zero value from
-return \fICURLE_ABORTED_BY_CALLBACK\fP.
+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
+Pass a pointer to a function that matches the following prototype:
-function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP. This
+\fBsize_t function( void *ptr, size_t size, size_t nmemb, void
-function gets called by libcurl as soon as it has received header data. The
+*userdata);\fP. This function gets called by libcurl as soon as it has
-header callback will be called once for each header and only complete header
+received header data. The header callback will be called once for each header
-lines are passed on to the callback. Parsing headers is very easy using
+and only complete header lines are passed on to the callback. Parsing headers
-this. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied
+is very easy using this. The size of the data pointed to by \fIptr\fP is
-with \fInmemb\fP. Do not assume that the header line is zero terminated! The
+\fIsize\fP multiplied with \fInmemb\fP. Do not assume that the header line is
-pointer named \fIuserdata\fP is the one you set with the
+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
+Pass a pointer to a function that matches the following prototype:
-sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called
+\fBCURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function
-by libcurl just before the initialization of a SSL connection after having
+gets called by libcurl just before the initialization of a SSL connection
-processed all other SSL related options to give a last chance to an
+after having processed all other SSL related options to give a last chance to
-application to modify the behaviour of openssl's ssl initialization. The
+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
+Pass a pointer to a function that matches the following prototype:
-function(char *ptr, size_t length);
+\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,16 +492,17 @@ 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
+Pass a pointer to a function that matches the following prototype:
-function( void *ptr, size_t size, size_t nmemb, void *userdata)\fP. This
+\fBsize_t function( void *ptr, size_t size, size_t nmemb, void
-function gets called by libcurl as soon as it has received interleaved RTP
+*userdata)\fP. This function gets called by libcurl as soon as it has received
-data. This function gets called for each $ block and therefore contains
+interleaved RTP data. This function gets called for each $ block and therefore
-exactly one upper-layer protocol unit (e.g.  one RTP packet). Curl writes the
+contains exactly one upper-layer protocol unit (e.g.  one RTP packet). Curl
-interleaved header as well as the included data for each call. The first byte
+writes the interleaved header as well as the included data for each call. The
-is always an ASCII dollar sign. The dollar sign is followed by a one byte
+first byte is always an ASCII dollar sign. The dollar sign is followed by a
-channel identifier and then a 2 byte integer length in network byte order. See
+one byte channel identifier and then a 2 byte integer length in network byte
-\fIRFC2326 Section 10.12\fP for more information on how RTP interleaving
+order. See \fIRFC2326 Section 10.12\fP for more information on how RTP
-behaves. If unset or set to NULL, curl will use the default write function.
+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
 stream data is sharing the RTSP control connection, it is critical to service
@@ -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
+Pass a pointer to a function that matches the following prototype:
-(const void *transfer_info, void *ptr, int remains)\fP. This function gets
+\fBlong function (const void *transfer_info, void *ptr, int remains)\fP. This
-called by libcurl before a part of the stream is going to be transferred (if
+function gets called by libcurl before a part of the stream is going to be
-the transfer supports chunks).
+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
+Pass a pointer to a function that matches the following prototype:
-function(void *ptr)\fP. This function gets called by libcurl as soon as a part
+\fBlong function(void *ptr)\fP. This function gets called by libcurl as soon
-of the stream has been transferred (or skipped).
+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
+Pass a pointer to a function that matches the following prototype: \fBint
-*pattern, const char *string)\fP prototype (see \fIcurl/curl.h\fP). It is used
+function(void *ptr, const char *pattern, const char *string)\fP prototype (see
-internally for the wildcard matching feature.
+\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
+Therefore the (probably undefined) contents of the buffer is NOT copied by the
-by the library. You should keep the associated storage available until
+library. You must keep the associated storage available until libcurl no
-libcurl no longer needs it. Failing to do so will cause very odd behavior
+longer needs it. Failing to do so will cause very odd behavior or even
-or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP
+crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP or you
-or you set the same option again to use a different pointer.
+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,8 +595,9 @@ 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
+Pass in a pointer to the actual URL to deal with. The parameter should be a
-terminated string which must be URL-encoded in the following format:
+char * to a zero terminated string which must be URL-encoded in the following
+format:
 
 scheme://host:port/path
 
@@ -841,14 +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
+Pass a pointer to a zero terminated string. The string consists of a comma
-list of hosts which do not use a proxy, if one is specified.  The only
+separated list of host names that do not require a proxy to get reached, even
-wildcard is a single * character, which matches all hosts, and effectively
+if one is specified.  The only wildcard available is a single * character,
-disables the proxy. Each name in this list is matched as either a domain which
+which matches all hosts, and effectively disables the proxy. Each name in this
-contains the hostname, or the hostname itself. For example, example.com
+list is matched as either a domain which contains the hostname, or the
-would match example.com, example.com:80, and www.example.com, but not
+hostname itself. For example, example.com would match example.com,
-www.notanexample.com.
+example.com:80, and www.example.com, but not www.notanexample.com.  (Added in
-(Added in 7.19.4)
+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
@@ -883,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
@@ -922,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
+Pass a long specifying whether the TCP_NODELAY option is to be set or cleared
-cleared (1 = set, 0 = clear). The option is cleared by default. This
+(1 = set, 0 = clear). The option is cleared by default. This will have no
-will have no effect after the connection has been established.
+effect after the connection has been established.
 
-Setting this option will disable TCP's Nagle algorithm. The purpose of
+Setting this option will disable TCP's Nagle algorithm. The purpose of this
-this algorithm is to try to minimize the number of small packets on
+algorithm is to try to minimize the number of small packets on the network
-the network (where "small packets" means TCP segments less than the
+(where "small packets" means TCP segments less than the Maximum Segment Size
-Maximum Segment Size (MSS) for the network).
+(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
+amortizes the overhead of the send. However, in some cases (most notably
-notably telnet or rlogin) small segments may need to be sent
+telnet or rlogin) small segments may need to be sent without delay. This is
-without delay. This is less efficient than sending larger amounts of
+less efficient than sending larger amounts of data at a time, and can
-data at a time, and can contribute to congestion on the network if
+contribute to congestion on the network if overdone.
-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)