diff options
| -rw-r--r-- | docs/libcurl/curl_easy_setopt.3 | 77 |
1 files changed, 50 insertions, 27 deletions
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a68b65855..895d85bcd 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -419,7 +419,7 @@ 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 an SSL connection after having +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 @@ -434,7 +434,7 @@ the SSL negotiation. The SSL_CTX pointer will be a new one every time. To use this properly, a non-trivial amount of knowledge of the openssl libraries is necessary. For example, using this function allows you to use openssl callbacks to add additional validation code for certificates, and even -to change the actual URI of an HTTPS request (example used in the lib509 test +to change the actual URI of a HTTPS request (example used in the lib509 test case). See also the example section for a replacement of the key, certificate and trust file settings. .IP CURLOPT_SSL_CTX_DATA @@ -711,7 +711,7 @@ pop3://user:password@mail.domain.com/1 - This retrieves the first message .B SCP -The path part of an SCP request specifies the file to retrieve and from what +The path part of a SCP request specifies the file to retrieve and from what directory. The file part may not be omitted. The file is taken as an absolute path from the root directory on the server. To specify a path relative to the user's home directory on the server, prepend ~/ to the path portion. @@ -725,7 +725,7 @@ user's home directory on the server .B SFTP -The path part of an SFTP request specifies the file to retrieve and from what +The path part of a SFTP request specifies the file to retrieve and from what directory. If the file part is omitted then libcurl downloads the directory listing for the directory specified. If the path ends in a / then a directory listing is returned instead of a file. If the path is omitted entirely then @@ -778,7 +778,7 @@ proxy's port number may optionally be specified with the separate option. If not specified, libcurl will default to using port 1080 for proxies. \fICURLOPT_PROXYPORT\fP. -When you tell the library to use an HTTP proxy, libcurl will transparently +When you tell the library to use a HTTP proxy, libcurl will transparently convert operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as \fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you @@ -817,7 +817,7 @@ 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. The should be a comma separated +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 @@ -1129,7 +1129,7 @@ Pass a parameter set to 1 to enable this. When enabled, libcurl will automatically set the Referer: field in requests where it follows a Location: redirect. .IP CURLOPT_ACCEPT_ENCODING -Sets the contents of the Accept-Encoding: header sent in an HTTP request, and +Sets the contents of the Accept-Encoding: header sent in a HTTP request, and enables decoding of a response when a Content-Encoding: header is received. Three encodings are supported: \fIidentity\fP, which does nothing, \fIdeflate\fP which requests the server to compress its response using the @@ -1157,7 +1157,7 @@ by both HTTP clients and HTTP servers. (Added in 7.21.6) .IP CURLOPT_FOLLOWLOCATION A parameter set to 1 tells the library to follow any Location: header that the -server sends as part of an HTTP header. +server sends as part of a HTTP header. This means that the library will re-send the same request on the new location and follow new Location: headers all the way until no more such headers are @@ -1237,7 +1237,7 @@ If you issue a POST request and then want to make a HEAD or GET using the same re-used handle, you must explicitly set the new request type using \fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. .IP CURLOPT_POSTFIELDS -Pass a void * as parameter, which should be the full data to post in an HTTP +Pass a void * as parameter, which should be the full data to post in a HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded. @@ -1272,7 +1272,7 @@ Pass a curl_off_t as parameter. Use this to set the size of the data to figure out the size. This is the large file version of the \fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1) .IP CURLOPT_COPYPOSTFIELDS -Pass a char * as parameter, which should be the full data to post in an HTTP +Pass a char * as parameter, which should be the full data to post in a HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS\fP option, but the original data are copied by the library, allowing the application to overwrite the original data after setting this option. @@ -1444,25 +1444,48 @@ transfer decoding will be disabled, if set to 1 it is enabled option is set to zero. (added in 7.16.2) .SH SMTP OPTIONS .IP CURLOPT_MAIL_FROM -Pass a pointer to a zero terminated string as parameter. It will be used to -specify the sender address in a mail when sending an SMTP mail with libcurl. +Pass a pointer to a zero terminated string as parameter. This should be used +to specify the sender's email address when sending SMTP mail with libcurl. + +An originator email address should be specified with angled brackets (<>) +around it, which if not specified, will be added by libcurl from version +7.21.4 onwards. Failing to provide such brackets may cause the server to +reject the email. -An originator email address in SMTP lingo is specified within angle brackets -(<>) which libcurl will not add for you before version 7.21.4. Failing to -provide such brackets may cause the server to reject your mail. +If this parameter is not specified then an empty address will be sent to the +mail server which may or may not cause the email to be rejected. (Added in 7.20.0) .IP CURLOPT_MAIL_RCPT Pass a pointer to a linked list of recipients to pass to the server in your -SMTP mail request. The linked list should be a fully valid list of \fBstruct +SMTP mail request. The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. -Each recipient in SMTP lingo is specified with angle brackets (<>), but should -you not use an angle bracket as first letter libcurl will assume you provide a -single email address only and enclose that with angle brackets for you. +Each recipient should be specified within a pair of angled brackets (<>), +however, should you not use an angled bracket as the first character libcurl +will assume you provided a single email address and enclose that address +within brackets for you. (Added in 7.20.0) +.IP CURLOPT_MAIL_AUTH +Pass a pointer to a zero terminated string as parameter. This will be used +to specify the authentication address (identity) of a submitted message that +is being relayed to another server. + +This optional parameter allows co-operating agents in a trusted environment to +communicate the authentication of individual messages and should only be used +by the application program, using libcurl, if the application is itself a +mail server acting in such an environment. If the application is operating as +such and the AUTH address is not known or is invalid, then an empty string +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. + +(Added in 7.24.0) .SH TFTP OPTIONS .IP CURLOPT_TFTP_BLKSIZE Specify block size to use for TFTP data transmission. Valid range as per RFC @@ -1684,7 +1707,7 @@ needed for this method)\fP (Added in 7.20.0) When sent by a client, this method changes the description of the session. For example, if a client is using the server to record a meeting, the client can use Announce to inform the server of all the meta-information about the -session. ANNOUNCE acts like an HTTP PUT or POST just like +session. ANNOUNCE acts like a HTTP PUT or POST just like \fICURL_RTSPREQ_SET_PARAMETER\fP (Added in 7.20.0) .IP CURL_RTSPREQ_SETUP Setup is used to initialize the transport layer for the session. The @@ -1707,7 +1730,7 @@ different connections. (Added in 7.20.0) .IP CURL_RTSPREQ_GET_PARAMETER Retrieve a parameter from the server. By default, libcurl will automatically include a \fIContent-Type: text/parameters\fP header on all non-empty requests -unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST +unless a custom one is set. GET_PARAMETER acts just like a HTTP PUT or POST (see \fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat message (e.g. in the presence of a server-specified timeout) should send use an empty GET_PARAMETER request. @@ -1715,9 +1738,9 @@ server-specified timeout) should send use an empty GET_PARAMETER request. .IP CURL_RTSPREQ_SET_PARAMETER Set a parameter on the server. By default, libcurl will automatically include a \fIContent-Type: text/parameters\fP header unless a custom one is set. The -interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application -may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like an HTTP -PUT, or it may use \fICURLOPT_POSTFIELDS\fP like an HTTP POST. No chunked +interaction with SET_PARAMTER is much like a HTTP PUT or POST. An application +may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like a HTTP +PUT, or it may use \fICURLOPT_POSTFIELDS\fP like a HTTP POST. No chunked transfers are allowed, so the application must set the \fICURLOPT_INFILESIZE\fP in the former and \fICURLOPT_POSTFIELDSIZE\fP in the latter. Also, there is no use of multi-part POSTs within RTSP. (Added in @@ -1779,7 +1802,7 @@ over FTP. This is a known limitation/flaw that nobody has rectified. libcurl simply sets the mode to ASCII and performs a standard transfer. .IP CURLOPT_PROXY_TRANSFER_MODE Pass a long. If the value is set to 1 (one), it tells libcurl to set the -transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by +transfer mode (binary or ASCII) for FTP transfers done via a HTTP proxy, by appending ;type=a or ;type=i to the URL. Without this setting, or it being set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing FTP via a proxy. Beware that not all proxies support this feature. (Added in @@ -1817,7 +1840,7 @@ Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be used -instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST +instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST when doing a FTP directory listing. This is useful for doing DELETE or other more or less obscure HTTP requests. Don't do this at will, make sure your server supports the command first. @@ -2160,7 +2183,7 @@ Pass a long as parameter. By default, curl assumes a value of 1. This option determines whether curl verifies the authenticity of the peer's certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't. -When negotiating an SSL connection, the server sends a certificate indicating +When negotiating a SSL connection, the server sends a certificate indicating its identity. Curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority |