diff options
Diffstat (limited to 'docs/libcurl')
-rw-r--r-- | docs/libcurl/curl_easy_pause.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/curl_easy_setopt.3 | 163 | ||||
-rw-r--r-- | docs/libcurl/curl_formfree.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/curl_formget.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/curl_getdate.3 | 6 | ||||
-rw-r--r-- | docs/libcurl/curl_getenv.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/curl_global_init.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/curl_mprintf.3 | 6 | ||||
-rw-r--r-- | docs/libcurl/curl_multi_assign.3 | 4 | ||||
-rw-r--r-- | docs/libcurl/curl_multi_fdset.3 | 6 | ||||
-rw-r--r-- | docs/libcurl/curl_multi_info_read.3 | 4 | ||||
-rw-r--r-- | docs/libcurl/curl_multi_init.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/curl_multi_perform.3 | 6 | ||||
-rw-r--r-- | docs/libcurl/curl_multi_setopt.3 | 8 | ||||
-rw-r--r-- | docs/libcurl/curl_multi_socket.3 | 10 | ||||
-rw-r--r-- | docs/libcurl/curl_share_init.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/curl_share_setopt.3 | 4 | ||||
-rw-r--r-- | docs/libcurl/curl_strequal.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/curl_version_info.3 | 12 | ||||
-rw-r--r-- | docs/libcurl/libcurl-errors.3 | 60 | ||||
-rw-r--r-- | docs/libcurl/libcurl-multi.3 | 2 | ||||
-rw-r--r-- | docs/libcurl/libcurl-tutorial.3 | 92 |
22 files changed, 199 insertions, 200 deletions
diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3 index 6208c79ad..1eb89347f 100644 --- a/docs/libcurl/curl_easy_pause.3 +++ b/docs/libcurl/curl_easy_pause.3 @@ -31,7 +31,7 @@ the connection you want to pause or unpause. The \fBbitmask\fP argument is a set of bits that sets the new state of the connection. The following bits can be used: .IP CURLPAUSE_RECV -Pause receiving data. There will be no data received on this conneciton until +Pause receiving data. There will be no data received on this connection until this function is called again without this bit set. Thus, the write callback (\fICURLOPT_WRITEFUNCTION\fP) won't be called. .IP CURLPAUSE_SEND diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 59d2da26e..d46ab9426 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -72,7 +72,7 @@ preceding the data (like HTTP). A parameter set to 1 tells the library to shut off the built-in progress meter completely. -Future versions of libcurl is likely to not have any built-in progress meter +Future versions of libcurl are likely to not have any built-in progress meter at all. .IP CURLOPT_NOSIGNAL Pass a long. If it is 1, libcurl will not use any functions that @@ -83,7 +83,7 @@ to still set/use all timeout options etc, without risking getting signals. If this option is set and libcurl has been built with the standard name resolver, timeouts will not occur while the name resolve takes place. -Consider building libcurl with ares support to enable asynchronous DNS +Consider building libcurl with c-ares support to enable asynchronous DNS lookups, which enables nice timeouts for name resolves without signals. .PP .SH CALLBACK OPTIONS @@ -101,7 +101,7 @@ From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which then will cause writing to this connection to become paused. See \fIcurl_easy_pause(3)\fP for further details. -This function may be called with zero bytes data if the transfered file is +This function may be called with zero bytes data if the transferred file is empty. Set this option to NULL to get the internal default function. The internal @@ -140,7 +140,7 @@ that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer. If you stop the current transfer by returning 0 "pre-maturely" (i.e before the -server expected it, like when you've told you will upload N bytes and you +server expected it, like when you've said you will upload N bytes and you upload less than N bytes), you may experience that the server "hangs" waiting for the rest of the data that won't come. @@ -152,7 +152,7 @@ From 7.18.0, the function can return CURL_READFUNC_PAUSE which then will cause reading from this connection to become paused. See \fIcurl_easy_pause(3)\fP for further details. -If you set the callback pointer to NULL, or doesn't set it at all, the default +If you set the callback pointer to NULL, or don't set it at all, the default internal read function will be used. It is simply doing an fread() on the FILE * stream set with \fICURLOPT_READDATA\fP. .IP CURLOPT_READDATA @@ -164,7 +164,7 @@ read function, this data must be a valid readable FILE *. If you're using libcurl as a win32 DLL, you MUST use a \fICURLOPT_READFUNCTION\fP if you set this option. -This option is also known with the older name \fICURLOPT_INFILE\fP, the name +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 @@ -336,7 +336,7 @@ This function will get called on all new connections made to a server, during 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. Using this function allows for example to use 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 case). See also the example section for a replacement of the key, certificate @@ -421,7 +421,7 @@ response codes will slip through, especially when authentication is involved (response codes 401 and 407). You might get some amounts of headers transferred before this situation is -detected, like for when a "100-continue" is received as a response to a +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 @@ -433,9 +433,9 @@ attempt to guess which protocol to use based on the given host name. If the given protocol of the set URL is not supported, libcurl will return on error (\fICURLE_UNSUPPORTED_PROTOCOL\fP) when you call \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info -on which protocols that are supported. +on which protocols are supported. -The string given to CURLOPT_URL must be url-encoded and following the RFC 2396 +The string given to CURLOPT_URL must be url-encoded and follow RFC 2396 (http://curl.haxx.se/rfc/rfc2396.txt). \fICURLOPT_URL\fP is the only option that \fBmust\fP be set before @@ -456,7 +456,7 @@ tunnel through the HTTP proxy. Such tunneling is activated with \fICURLOPT_HTTPPROXYTUNNEL\fP. libcurl respects the environment variables \fBhttp_proxy\fP, \fBftp_proxy\fP, -\fBall_proxy\fP etc, if any of those is set. The \fICURLOPT_PROXY\fP option +\fBall_proxy\fP etc, if any of those are set. The \fICURLOPT_PROXY\fP option does however override any possibly set environment variables. Setting the proxy string to "" (an empty string) will explicitly disable the @@ -480,16 +480,16 @@ given HTTP proxy. There is a big difference between using a proxy and to tunnel through it. If you don't know what this means, you probably don't want this tunneling option. .IP CURLOPT_INTERFACE -Pass a char * as parameter. This set the interface name to use as outgoing -network interface. The name can be an interface name, an IP address or a host +Pass a char * as parameter. This sets the interface name to use as outgoing +network interface. The name can be an interface name, an IP address, or a host name. .IP CURLOPT_LOCALPORT Pass a long. This sets the local port number of the socket used for 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. Note that port numbers are only valid 1 - 65535. (Added in 7.15.2) +set. Note that the only 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 do to find a +Pass a long. This is the number of attempts libcurl should 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. Note that port numbers @@ -503,8 +503,8 @@ caching, or set to -1 to make the cached entries remain forever. By default, libcurl caches this info for 60 seconds. NOTE: the name resolve functions of various libc implementations don't re-read -name server information unless explicitly told so (by for example calling -\fIres_init(3)\fP. This may cause libcurl to keep using the older server even +name server information unless explicitly told so (for example, by calling +\fIres_init(3)\fP). This may cause libcurl to keep using the older server even if DHCP has updated the server info, and this may look like a DNS cache issue to the casual libcurl-app user. .IP CURLOPT_DNS_USE_GLOBAL_CACHE @@ -560,8 +560,8 @@ Pass a long, set to one of the values described below. .RS .IP CURL_NETRC_OPTIONAL The use of your \fI~/.netrc\fP file is optional, and information in the URL is -to be preferred. The file will be scanned with the host and user name (to -find the password only) or with the host only, to find the first user name and +to be preferred. The file will be scanned for the host and user name (to +find the password only) or for the host only, to find the first user name and password after that \fImachine\fP, which ever information is not specified in the URL. @@ -572,7 +572,7 @@ The library will ignore the file and use only the information in the URL. This is the default. .IP CURL_NETRC_REQUIRED This value tells the library that use of the file is required, to ignore the -information in the URL, and to search the file with the host only. +information in the URL, and to search the file for the host only. .RE Only machine name, user name and password are taken into account (init macros and similar things aren't supported). @@ -586,9 +586,9 @@ option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to find a .netrc file in the current user's home directory. (Added in 7.10.9) .IP CURLOPT_USERPWD Pass a char * as parameter, which should be [user name]:[password] to use for -the connection. Use \fICURLOPT_HTTPAUTH\fP to decide authentication method. +the connection. Use \fICURLOPT_HTTPAUTH\fP to decide the authentication method. -When using NTLM, you can set domain by prepending it to the user name and +When using NTLM, you can set the domain by prepending it to the user name and separating the domain and name with a forward (/) or backward slash (\\). Like this: "domain/user:password" or "domain\\user:password". Some HTTP servers (on Windows) support this style even for Basic authentication. @@ -602,14 +602,14 @@ to prevent accidental information leakage. .IP CURLOPT_PROXYUSERPWD Pass a char * as parameter, which should be [user name]:[password] to use for the connection to the HTTP proxy. Use \fICURLOPT_PROXYAUTH\fP to decide -authentication method. +the authentication method. .IP CURLOPT_USERNAME Pass a char * as parameter, which should be pointing to the zero terminated user name to use for the transfer. -The CURLOPT_USERNAME option should be used in same way as the +The CURLOPT_USERNAME option should be used in the same way that \fICURLOPT_USERPWD\fP is used. In comparison to \fICURLOPT_USERPWD\fP the -CURLOPT_USERNAME allows the username to contain colon, like in following +CURLOPT_USERNAME allows the username to contain a colon, like in the following example: "sip:user@example.com". Note the CURLOPT_USERNAME option is an alternative way to set the user name. There is no meaning to use it together with the \fICURLOPT_USERPWD\fP option. @@ -621,15 +621,15 @@ Pass a char * as parameter, which should be pointing to the zero terminated password to use for the transfer. The CURLOPT_PASSWORD option should be used in conjunction with -as the \fICURLOPT_USERNAME\fP option. (Added in 7.19.1) +the \fICURLOPT_USERNAME\fP option. (Added in 7.19.1) .IP CURLOPT_PROXYUSERNAME Pass a char * as parameter, which should be pointing to the zero terminated user name to use for the transfer while connecting to Proxy. The CURLOPT_PROXYUSERNAME option should be used in same way as the \fICURLOPT_PROXYUSERPWD\fP is used. In comparison to \fICURLOPT_PROXYUSERPWD\fP -the CURLOPT_PROXYUSERNAME allows the username to contain colon, -like in following example: "sip:user@example.com". +the CURLOPT_PROXYUSERNAME allows the username to contain a colon, +like in the following example: "sip:user@example.com". Note the CURLOPT_PROXYUSERNAME option is an alternative way to set the user name while connecting to Proxy. There is no meaning to use it together with the \fICURLOPT_PROXYUSERPWD\fP option. @@ -641,12 +641,12 @@ Pass a char * as parameter, which should be pointing to the zero terminated password to use for the transfer while connecting to Proxy. The CURLOPT_PROXYPASSWORD option should be used in conjunction with -as the \fICURLOPT_PROXYUSERNAME\fP option. (Added in 7.19.1) +the \fICURLOPT_PROXYUSERNAME\fP option. (Added in 7.19.1) .IP CURLOPT_HTTPAUTH -Pass a long as parameter, which is set to a bitmask, to tell libcurl what +Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use. The available bits are listed below. If more than one bit is set, libcurl will first query the site to see -what authentication methods it supports and then pick the best one you allow +which authentication methods it supports and then pick the best one you allow it to use. For some methods, this will induce an extra network round-trip. Set the actual name and password with the \fICURLOPT_USERPWD\fP option or with the \fICURLOPT_USERNAME\fP and the \fICURLOPT_USERPASSWORD\fP options. @@ -654,7 +654,7 @@ with the \fICURLOPT_USERNAME\fP and the \fICURLOPT_USERPASSWORD\fP options. .RS .IP CURLAUTH_BASIC HTTP Basic authentication. This is the default choice, and the only method -that is in wide-spread use and supported virtually everywhere. This is sending +that is in wide-spread use and supported virtually everywhere. This sends the user name and password over the network in plain text, easily captured by others. .IP CURLAUTH_DIGEST @@ -672,7 +672,7 @@ added in 7.19.3) HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain \&"Negotiate") method was designed by Microsoft and is used in their web applications. It is primarily meant as a support for Kerberos5 authentication -but may be also used along with another authentication methods. For more +but may also be used along with other authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. You need to build libcurl with a suitable GSS-API library for this to work. @@ -693,7 +693,7 @@ libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. .RE .IP CURLOPT_PROXYAUTH -Pass a long as parameter, which is set to a bitmask, to tell libcurl what +Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use for your proxy authentication. If more than one bit is set, libcurl will first query the site to see what authentication methods it supports and then pick the best one you allow it to @@ -748,11 +748,11 @@ the request method after a 302 redirect. CURL_REDIR_POST_ALL is a convenience define that sets both 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 requires -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) +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) .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. @@ -850,7 +850,7 @@ copy. In any case, the size must not be changed after .IP CURLOPT_HTTPPOST Tells libcurl you want a multipart/formdata HTTP POST to be made and you instruct what data to pass on to the server. Pass a pointer to a linked list -of curl_httppost structs as parameter. . The easiest way to create such a +of curl_httppost structs as parameter. The easiest way to create such a list, is to use \fIcurl_formadd(3)\fP as documented. The data in this list must remain intact until you close this curl handle again with \fIcurl_easy_cleanup(3)\fP. @@ -877,10 +877,10 @@ 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. If you add a header that is otherwise generated and used by libcurl internally, your added one will be used instead. If you add a header with no -contents as in 'Accept:' (no data on the right side of the colon), the +content as in 'Accept:' (no data on the right side of the colon), the internally used header will get disabled. Thus, using this option you can add new headers, replace internal headers and remove internal headers. To add a -header with no contents, make the contents be two quotes: \&"". The headers +header with no content, make the content be two quotes: \&"". The headers included in the linked list must not be CRLF-terminated, because curl adds CRLF after each header item. Failure to comply with this will result in strange bugs because the server will most likely ignore part of the headers @@ -934,7 +934,7 @@ dumped to a file. Given an empty or non-existing file or by passing the empty string (""), this option will enable cookies for this curl handle, making it understand and -parse received cookies and then use matching cookies in future request. +parse received cookies and then use matching cookies in future requests. If you use this option multiple times, you just add more files to read. Subsequent files will add more cookies. @@ -955,7 +955,7 @@ about this possibly lethal situation. Pass a long set to 1 to mark this as a new cookie "session". It will force libcurl to ignore all cookies it is about to load that are "session cookies" from the previous session. By default, libcurl always stores and loads all -cookies, independent if they are session cookies are not. Session cookies are +cookies, independent if they are session cookies or not. Session cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only. .IP CURLOPT_COOKIELIST @@ -969,7 +969,7 @@ all cookies known by cURL to the file specified by \fICURLOPT_COOKIEJAR\fP. (Added in 7.17.1) .IP CURLOPT_HTTPGET Pass a long. If the long is 1, this forces the HTTP request to get back -to GET. usable if a POST, HEAD, PUT or a custom request have been used +to GET. Usable if a POST, HEAD, PUT, or a custom request has been used previously using the same curl handle. When setting \fICURLOPT_HTTPGET\fP to 1, it will automatically set @@ -1006,17 +1006,17 @@ option is set to zero. (added in 7.16.2) .SH FTP OPTIONS .IP CURLOPT_FTPPORT Pass a pointer to a zero terminated string as parameter. It will be used to -get the IP address to use for the ftp PORT instruction. The PORT instruction +get the IP address to use for the FTP PORT instruction. The PORT instruction tells the remote server to connect to our specified IP address. The string may -be a plain IP address, a host name, an network interface name (under Unix) or -just a '-' letter to let the library use your systems default IP +be a plain IP address, a host name, a network interface name (under Unix) or +just a '-' symbol to let the library use your system's default IP address. Default FTP operations are passive, and thus won't use PORT. You disable PORT again and go back to using the passive version by setting this option to NULL. .IP CURLOPT_QUOTE Pass a pointer to a linked list of FTP or SFTP commands to pass to -the server prior to your ftp request. This will be done before any +the server prior to your FTP request. This will be done before any other commands are issued (even before the CWD command for FTP). The linked list should be a fully valid list of 'struct curl_slist' structs properly filled in with text strings. Use \fIcurl_slist_append(3)\fP @@ -1031,7 +1031,7 @@ rename, rm, rmdir, symlink (see (SFTP support added in 7.16.3) .IP CURLOPT_POSTQUOTE Pass a pointer to a linked list of FTP or SFTP commands to pass to the -server after your ftp transfer request. The linked list should be a +server after your FTP transfer request. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for \fICURLOPT_QUOTE\fP. Disable this operation again by setting a NULL to this option. @@ -1054,7 +1054,7 @@ might not include subdirectories and symbolic links. (This option was known as CURLOPT_FTPLISTONLY up to 7.16.4) .IP CURLOPT_APPEND A parameter set to 1 tells the library to append to the remote file instead of -overwrite it. This is only useful when uploading to an ftp site. +overwrite it. This is only useful when uploading to an FTP site. (This option was known as CURLOPT_FTPAPPEND up to 7.16.4) .IP CURLOPT_FTP_USE_EPRT @@ -1105,7 +1105,7 @@ from the 227-response. (Added in 7.14.2) This option has no effect if PORT, EPRT or EPSV is used instead of PASV. .IP CURLOPT_USE_SSL Pass a long using one of the values from below, to make libcurl use your -desired level of SSL for the ftp transfer. (Added in 7.11.0) +desired level of SSL for the FTP transfer. (Added in 7.11.0) (This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants were known as CURLFTPSSL_*) @@ -1125,11 +1125,11 @@ Pass a long using one of the values from below, to alter how libcurl issues \fICURLOPT_USE_SSL\fP). (Added in 7.12.2) .RS .IP CURLFTPAUTH_DEFAULT -Allow libcurl to decide +Allow libcurl to decide. .IP CURLFTPAUTH_SSL -Try "AUTH SSL" first, and only if that fails try "AUTH TLS" +Try "AUTH SSL" first, and only if that fails try "AUTH TLS". .IP CURLFTPAUTH_TLS -Try "AUTH TLS" first, and only if that fails try "AUTH SSL" +Try "AUTH TLS" first, and only if that fails try "AUTH SSL". .RE .IP CURLOPT_FTP_SSL_CCC If enabled, this option makes libcurl use CCC (Clear Command Channel). It @@ -1157,7 +1157,7 @@ argument should be one of the following alternatives: .RS .IP CURLFTPMETHOD_MULTICWD libcurl does a single CWD operation for each path part in the given URL. For -deep hierarchies this means very many commands. This is how RFC1738 says it +deep hierarchies this means many commands. This is how RFC1738 says it should be done. This is the default but the slowest behavior. .IP CURLFTPMETHOD_NOCWD libcurl does no CWD at all. libcurl will do SIZE, RETR, STOR etc and give a @@ -1169,7 +1169,7 @@ compliant than 'nocwd' but without the full penalty of 'multicwd'. .RE .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT -A parameter set to 1 tells the library to use ASCII mode for ftp transfers, +A parameter set to 1 tells the library to use ASCII mode for FTP transfers, instead of the default binary transfer. For win32 systems it does not set the stdout to binary mode. This option can be usable when transferring text data between systems with different views on certain characters, such as newlines @@ -1177,7 +1177,7 @@ or similar. libcurl does not do a complete ASCII conversion when doing ASCII transfers over FTP. This is a known limitation/flaw that nobody has rectified. libcurl -simply sets the mode to ascii and performs a standard transfer. +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 @@ -1208,7 +1208,7 @@ 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 -when doing an ftp directory listing. This is useful for doing DELETE or other +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. @@ -1298,10 +1298,10 @@ value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP or \fICURL_TIMECOND_IFUNMODSINCE\fP. This feature applies to HTTP and FTP. The last modification time of a file is not always known and in such instances -this feature will have no effect even if the given time condition would have -not been met. +this feature will have no effect even if the given time condition would not have +been met. .IP CURLOPT_TIMEVALUE -Pass a long as parameter. This should be the time in seconds since 1 jan 1970, +Pass a long as parameter. This should be the time in seconds since 1 Jan 1970, and the time will be used in a condition as specified with \fICURLOPT_TIMECONDITION\fP. .SH CONNECTION OPTIONS @@ -1342,19 +1342,19 @@ value. Defaults to unlimited speed. (Added in 7.15.5) Pass a long. The set number will be the persistent connection cache size. The set amount will be the maximum amount of simultaneously open connections that libcurl may cache in this easy handle. Default is 5, and there isn't much -point in changing this value unless you are perfectly aware of how this work -and changes libcurl's behaviour. This concerns connection using any of the +point in changing this value unless you are perfectly aware of how this works +and changes libcurl's behaviour. This concerns connections using any of the protocols that support persistent connections. When reaching the maximum limit, curl closes the oldest one in the cache to -prevent the number of open connections to increase. +prevent increasing the number of open connections. If you already have performed transfers with this curl handle, setting a smaller MAXCONNECTS than before may cause open connections to get closed unnecessarily. Note that if you add this easy handle to a multi handle, this setting is not -being acknowledged, but you must instead use \fIcurl_multi_setopt(3)\fP and +acknowledged, and you must instead use \fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_MAXCONNECTS\fP option. .IP CURLOPT_CLOSEPOLICY (Obsolete) This option does nothing. @@ -1367,10 +1367,10 @@ what it does. Set this to 0 to have libcurl attempt re-using an existing connection (default behavior). .IP CURLOPT_FORBID_REUSE Pass a long. Set to 1 to make the next transfer explicitly close the -connection when done. Normally, libcurl keep all connections alive when done -with one transfer in case there comes a succeeding one that can re-use them. +connection when done. Normally, libcurl keeps all connections alive when done +with one transfer in case a succeeding one follows that can re-use them. This option should be used with caution and only if you understand what it -does. Set to 0 to have libcurl keep the connection open for possibly later +does. Set to 0 to have libcurl keep the connection open for possible later re-use (default behavior). .IP CURLOPT_CONNECTTIMEOUT Pass a long. It should contain the maximum time in seconds that you allow the @@ -1395,9 +1395,9 @@ resolve addresses using more than one version of IP. The allowed values are: .IP CURL_IPRESOLVE_WHATEVER Default, resolves addresses to all IP versions that your system allows. .IP CURL_IPRESOLVE_V4 -Resolve to ipv4 addresses. +Resolve to IPv4 addresses. .IP CURL_IPRESOLVE_V6 -Resolve to ipv6 addresses. +Resolve to IPv6 addresses. .RE .IP CURLOPT_CONNECT_ONLY Pass a long. If the parameter equals 1, it tells the library to perform all @@ -1507,14 +1507,14 @@ even indicate an accessible file. Note that option is by default set to the system path where libcurl's cacert bundle is assumed to be stored, as established at build time. -When built against NSS this is the directory that the NSS certificate +When built against NSS, this is the directory that the NSS certificate database resides in. .IP CURLOPT_ISSUERCERT Pass a char * to a zero terminated string naming a file holding a CA certificate in PEM format. If the option is set, an additional check against the peer certificate is performed to verify the issuer is indeed the one associated with the certificate provided by the option. This additional check -is useful in multi-level PKI where one need to enforce the peer certificate is +is useful in multi-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree. This option makes sense only when used in combination with the @@ -1555,7 +1555,7 @@ found in the CRL does not trigger this specific error. (Added in 7.19.0) .IP CURLOPT_CERTINFO Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With this enabled, libcurl (if built with OpenSSL) will extract lots of information -and data about the certificate's in the certificate chain used in the SSL +and data about the certificates in the certificate chain used in the SSL connection. This data is then possible to extract after a transfer using \fIcurl_easy_getinfo(3)\fP and its option \fICURLINFO_CERTINFO\fP. (Added in 7.19.1) @@ -1572,7 +1572,7 @@ Pass a long as parameter. This option determines whether libcurl verifies that the server cert is for the server it is known as. -When negotiating an SSL connection, the server sends a certificate indicating +When negotiating a SSL connection, the server sends a certificate indicating its identity. When \fICURLOPT_SSL_VERIFYHOST\fP is 2, that certificate must indicate that @@ -1591,9 +1591,8 @@ certificate. The default, since 7.10, is 2. -The checking this option controls is of the identity that the server -\fIclaims\fP. The server could be lying. To control lying, see -\fICURLOPT_SSL_VERIFYPEER\fP. +This option controls checking the server's claimed identity. The server could +be lying. To control lying, see \fICURLOPT_SSL_VERIFYPEER\fP. .IP CURLOPT_SSL_CIPHER_LIST Pass a char *, pointing to a zero terminated string holding the list of ciphers to use for the SSL connection. The list must be syntactically correct, @@ -1608,7 +1607,7 @@ compile OpenSSL. You'll find more details about cipher lists on this URL: \fIhttp://www.openssl.org/docs/apps/ciphers.html\fP -For NSS valid examples of cipher lists include 'rsa_rc4_128_md5', +For NSS, valid examples of cipher lists include 'rsa_rc4_128_md5', \'rsa_aes_128_sha\', etc. With NSS you don't add/remove ciphers. If one uses this option then all known ciphers are disabled and only those passed in are enabled. @@ -1666,7 +1665,7 @@ share handle. See \fIcurl_share_setopt(3)\fP for details. If you add a share that is set to share cookies, your easy handle will use that cookie cache and get the cookie engine enabled. If you unshare an object -that were using cookies (or change to another object that doesn't share +that was using cookies (or change to another object that doesn't share cookies), the easy handle will get its cookie engine disabled. Data that the share object is not set to share will be dealt with the usual @@ -1675,12 +1674,12 @@ way, as if no share was used. Pass a long as a parameter, containing the value of the permissions that will be assigned to newly created files on the remote server. The default value is \fI0644\fP, but any valid value can be used. The only protocols that can use -this are \fIsftp://\fP, \fIscp://\fP and \fIfile://\fP. (Added in 7.16.4) +this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. (Added in 7.16.4) .IP CURLOPT_NEW_DIRECTORY_PERMS Pass a long as a parameter, containing the value of the permissions that will be assigned to newly created directories on the remote server. The default value is \fI0755\fP, but any valid value can be used. The only protocols that -can use this are \fIsftp://\fP, \fIscp://\fP and \fIfile://\fP. +can use this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. (Added in 7.16.4) .SH TELNET OPTIONS .IP CURLOPT_TELNETOPTIONS diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 31c74e2dd..191cbc215 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -13,7 +13,7 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain .SH DESCRIPTION curl_formfree() is used to clean up data previously built/appended with \fIcurl_formadd(3)\fP. This must be called when the data has been used, which -typically means after the \fIcurl_easy_perform(3)\fP has been called. +typically means after \fIcurl_easy_perform(3)\fP has been called. .SH RETURN VALUE None .SH "SEE ALSO" diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index 4350af352..83996cbe0 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -4,7 +4,7 @@ .\" .TH curl_formget 3 "20 June 2006" "libcurl 7.15.5" "libcurl Manual" .SH NAME -curl_formget - serialize a previously build multipart/formdata HTTP POST chain +curl_formget - serialize a previously built multipart/formdata HTTP POST chain .SH SYNOPSIS .B #include <curl/curl.h> .sp diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 0cd26e677..d1152ebc0 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -4,7 +4,7 @@ .\" .TH curl_getdate 3 "12 Aug 2005" "libcurl 7.0" "libcurl Manual" .SH NAME -curl_getdate - Convert an date string to number of seconds since January 1, +curl_getdate - Convert a date string to number of seconds since January 1, 1970 .SH SYNOPSIS .B #include <curl/curl.h> @@ -27,7 +27,7 @@ items: .TP 0.8i .B calendar date items Can be specified several ways. Month names can only be three-letter english -abbrivations, numbers can be zero-prefixed and the year may use 2 or 4 digits. +abbreviations, numbers can be zero-prefixed and the year may use 2 or 4 digits. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. .TP .B time of the day items @@ -96,5 +96,5 @@ The former version of this function was built with yacc and was not only very large, it was also never quite understood and it wasn't possible to build with non-GNU tools since only GNU Bison could make it thread-safe! -The rewrite was done for 7.12.2. The new one is much smaller and use simpler +The rewrite was done for 7.12.2. The new one is much smaller and uses simpler code. diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index 37a5979a7..5d672710d 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -24,7 +24,7 @@ to find the specified name, it returns a null pointer. .SH NOTE Under unix operating systems, there isn't any point in returning an allocated memory, although other systems won't work properly if this isn't done. The -unix implementation thus have to suffer slightly from the drawbacks of other +unix implementation thus has to suffer slightly from the drawbacks of other systems. .SH "SEE ALSO" .BR getenv "(3C), " diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index ba15ad4e0..fad153b6f 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -23,7 +23,7 @@ effect as one call. The flags option is a bit pattern that tells libcurl exactly what features to init, as described below. Set the desired bits by ORing the values together. In normal operation, you must specify CURL_GLOBAL_ALL. Don't use any other -value unless you are familiar with and mean to control internal operations of +value unless you are familiar with it and mean to control internal operations of libcurl. \fBThis function is not thread safe.\fP You must not call it when any other diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index c7c7d598c..8b27815c5 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -28,7 +28,7 @@ curl_mvsprintf - formatted output conversion .br .BI "char *curl_mvaprintf(const char *" format ", va_list " args ");" .SH DESCRIPTION -These are all functions that produces output according to a format string and +These are all functions that produce output according to a format string and given arguments. These are mostly clones of the well-known C-style functions and there will be no detailed explanation of all available formatting rules and usage here. @@ -83,8 +83,8 @@ future. They will instead be made "available" by source code access only, and then as curlx_-prefixed functions. See lib/README.curlx for further details. .SH RETURN VALUE The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to -a newly allocated string, or NULL it it failed. +a newly allocated string, or NULL if it failed. -All other functions return the number of character they actually outputed. +All other functions return the number of characters they actually outputted. .SH "SEE ALSO" .BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) " diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3 index cb47a5e25..83dc7b72d 100644 --- a/docs/libcurl/curl_multi_assign.3 +++ b/docs/libcurl/curl_multi_assign.3 @@ -2,7 +2,7 @@ .\" .TH curl_multi_assign 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME -curl_multi_assign \- set data to associated with an internal socket +curl_multi_assign \- set data to association with an internal socket .SH SYNOPSIS #include <curl/curl.h> @@ -34,7 +34,7 @@ In a typical application you allocate a struct or at least use some kind of semi-dynamic data for each socket that we must wait for action on when using the \fIcurl_multi_socket(3)\fP approach. -When our socket-callback get called by libcurl and we get to know about yet +When our socket-callback gets called by libcurl and we get to know about yet another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out the particular data so that when we get updates about this same socket again, we don't have to find the struct associated with this socket by ourselves. diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 5f3cf1891..7e54dfeac 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -17,9 +17,9 @@ CURLMcode curl_multi_fdset(CURLM *multi_handle, This function extracts file descriptor information from a given multi_handle. libcurl returns its fd_set sets. The application can use these to select() on, but be sure to FD_ZERO them before calling this function as -\fIcurl_multi_fdset(3)\fP only adds its own descriptors it doesn't zero or -otherwise remove any other. The \fIcurl_multi_perform(3)\fP function should be -called as soon as one of them are ready to be read from or written to. +\fIcurl_multi_fdset(3)\fP only adds its own descriptors, it doesn't zero or +otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should be +called as soon as one of them is ready to be read from or written to. If no file descriptors are set by libcurl, \fImax_fd\fP will contain -1 when this function returns. Otherwise it will contain the higher descriptor number diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 1d97cf9a5..e5539c1dc 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -29,7 +29,7 @@ is emptied. calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or \fIcurl_easy_cleanup(3)\fP. -The 'CURLMsg' struct is very simple and only contain very basic information. +The 'CURLMsg' struct is very simple and only contains very basic information. If more involved information is wanted, the particular "easy handle" in present in that struct and can thus be used in subsequent regular \fIcurl_easy_getinfo(3)\fP calls (or similar): @@ -48,7 +48,7 @@ When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that is done, and then \fBresult\fP contains the return code for the easy handle that just completed. -At this point, there is no other \fBmsg\fP types defined. +At this point, there are no other \fBmsg\fP types defined. .SH "RETURN VALUE" A pointer to a filled-in struct, or NULL if it failed or ran out of structs. It also writes the number of messages left in the queue (after this diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index 59f845b15..393d13ae7 100644 --- a/docs/libcurl/curl_multi_init.3 +++ b/docs/libcurl/curl_multi_init.3 @@ -10,7 +10,7 @@ curl_multi_init - create a multi handle .ad .SH DESCRIPTION This function returns a CURLM handle to be used as input to all the other -multi-functions, sometimes referred to as a multi handle on some places in the +multi-functions, sometimes referred to as a multi handle in some places in the documentation. This init call MUST have a corresponding call to \fIcurl_multi_cleanup(3)\fP when the operation is complete. .SH RETURN VALUE diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 9baa77c6c..087f46466 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -32,12 +32,12 @@ actions. You don't have to do it immediately, but the return code means that libcurl may have more data available to return or that there may be more data to send off before it is "satisfied". Do note that \fIcurl_multi_perform(3)\fP will return \fICURLM_CALL_MULTI_PERFORM\fP only when it wants to be called -again \fBimmediately\fP. When things are fine and there are nothing immediate +again \fBimmediately\fP. When things are fine and there is nothing immediate it wants done, it'll return \fICURLM_OK\fP and you need to wait for \&"action" and then call this function again. -NOTE that this only returns errors etc regarding the whole multi stack. There -might still have occurred problems on individual transfers even when this +NOTE that this only returns errors etc regarding the whole multi stack. Problems +still might have occurred on individual transfers even when this function returns \fICURLM_OK\fP. .SH "TYPICAL USAGE" Most applications will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index c3e4dd76c..da4a8d367 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -21,7 +21,7 @@ You can only set one option in each function call. .IP CURLMOPT_SOCKETFUNCTION Pass a pointer to a function matching the \fBcurl_socket_callback\fP prototype. The \fIcurl_multi_socket(3)\fP functions inform the application -about updates in the socket (file descriptor) status by doing none, one or +about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the curl_socket_callback given in the \fBparam\fP argument. They update the status with changes since the previous time a \fIcurl_multi_socket(3)\fP function was called. If the given callback pointer @@ -38,7 +38,7 @@ Pass a long set to 1 to enable or 0 to disable. Enabling pipelining on a multi handle will make it attempt to perform HTTP Pipelining as far as possible for transfers using this handle. This means that if you add a second request that can use an already existing connection, the second request will be \&"piped" -on the same connection rather than being executed in parallell. (Added in +on the same connection rather than being executed in parallel. (Added in 7.16.0) .IP CURLMOPT_TIMERFUNCTION Pass a pointer to a function matching the \fBcurl_multi_timer_callback\fP @@ -63,11 +63,11 @@ simultaneously open connections that libcurl may cache. Default is 10, and libcurl will enlarge the size for each added easy handle to make it fit 4 times the number of added easy handles. -By setting this option, you can prevent the cache size to grow beyond the +By setting this option, you can prevent the cache size from growing beyond the limit set by you. When the cache is full, curl closes the oldest one in the cache to prevent the -number of open connections to increase. +number of open connections from increasing. This option is for the multi handle's use only, when using the easy interface you should instead use the \fICURLOPT_MAXCONNECTS\fP option. diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 38fe60013..a38532d23 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -44,7 +44,7 @@ is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed. The \fBcurl_multi_socket_action(3)\fP functions inform the application about -updates in the socket (file descriptor) status by doing none, one or multiple +updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket callback function set with the CURLMOPT_SOCKETFUNCTION option to \fIcurl_multi_setopt(3)\fP. They update the status with changes since the previous time the callback was called. @@ -64,7 +64,7 @@ equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to Force libcurl to (re-)check all its internal sockets and transfers instead of just a single one by calling \fBcurl_multi_socket_all(3)\fP. Note that there -should not exist any reasons to use this function! +should not be any reason to use this function! .SH "CALLBACK DETAILS" The socket \fBcallback\fP function uses a prototype like this @@ -121,8 +121,8 @@ In modern libcurls, \fICURLM_CALL_MULTI_PERFORM\fP or \fICURLM_CALL_MULTI_SOKCET\fP should not be returned and no application needs to care about them. -NOTE that the return code is for the whole multi stack. There might still have -occurred problems on individual transfers even when one of these functions +NOTE that the return code is for the whole multi stack. Problems still might have +occurred on individual transfers even when one of these functions return OK. .SH "TYPICAL USAGE" 1. Create a multi handle @@ -147,7 +147,7 @@ call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP 8. Go back to step 6. .SH AVAILABILITY -This function was added in libcurl 7.15.4, although deemed stable since +This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0. \fIcurl_multi_socket(3)\fP is deprecated, use diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index ead7f4b81..70f307f7a 100644 --- a/docs/libcurl/curl_share_init.3 +++ b/docs/libcurl/curl_share_init.3 @@ -10,7 +10,7 @@ curl_share_init - Create a shared object .ad .SH DESCRIPTION This function returns a CURLSH handle to be used as input to all the other -share-functions, sometimes referred to as a share handle on some places in the +share-functions, sometimes referred to as a share handle in some places in the documentation. This init call MUST have a corresponding call to \fIcurl_share_cleanup\fP when all operations using the share are complete. diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index e6be1b4ee..43d4b29c4 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -31,7 +31,7 @@ prototype: void unlock_function(CURL *handle, curl_lock_data data, void *userptr); \fIdata\fP defines what data libcurl wants to unlock, and you must make sure -that only one lick is given at any time for each kind of data. +that only one lock is given at any time for each kind of data. \fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP. .IP CURLSHOPT_SHARE @@ -51,7 +51,7 @@ This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that the specified \fIparameter\fP will no longer be shared. Valid values are the same as those for \fICURLSHOPT_SHARE\fP. .IP CURLSHOPT_USERDATA -The \fIparameter\fP allows you to specify a pointer to data that will passed +The \fIparameter\fP allows you to specify a pointer to data that will be passed to the lock_function and unlock_function each time it is called. .SH RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non-zero means an diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index 2b99467f1..1442a70f6 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -21,7 +21,7 @@ first \fIlen\fP characters of \fIstr1\fP. .sp These functions are provided by libcurl to enable applications to compare strings in a truly portable manner. There are no standard portable case -insensitive string comparison functions. These two works on all platforms. +insensitive string comparison functions. These two work on all platforms. .SH AVAILABILITY These functions will be removed from the public libcurl API in a near future. They will instead be made "available" by source code access only, and diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 21f72aebe..e090e6066 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -34,7 +34,7 @@ Returns a pointer to a filled in struct with information about various run-time features in libcurl. \fItype\fP should be set to the version of this functionality by the time you write your program. This way, libcurl will always return a proper struct that your program understands, while programs in -the future might get an different struct. CURLVERSION_NOW will be the most +the future might get a different struct. CURLVERSION_NOW will be the most recent one for the library you have installed: data = curl_version_info(CURLVERSION_NOW); @@ -74,8 +74,8 @@ typedef struct { } curl_version_info_data; .fi -\fIage\fP describes what age of this struct this is. The number depends on how -new libcurl you're using. You are however guaranteed to get a struct that you +\fIage\fP describes what the age of this struct is. The number depends on how +new the libcurl you're using is. You are however guaranteed to get a struct that you have a matching struct for in the header, as you tell libcurl your "age" with the input argument. @@ -126,15 +126,15 @@ allows libcurl to use the current user and the current user's password without the app having to pass them on. (Added in 7.13.2) .IP CURL_VERSION_CONV libcurl was built with support for character conversions, as provided by the -CUURLOPT_CONV_* callbacks. (Added in 7.15.4) +CURLOPT_CONV_* callbacks. (Added in 7.15.4) .RE -\fIssl_version\fP is an ascii string for the OpenSSL version used. If libcurl +\fIssl_version\fP is an ASCII string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. \fIssl_version_num\fP is the numerical OpenSSL version value as defined by the OpenSSL project. If libcurl has no SSL support, this is 0. -\fIlibz_version\fP is an ascii string (there is no numerical version). If +\fIlibz_version\fP is an ASCII string (there is no numerical version). If libcurl has no libz support, this is NULL. \fIprotocols\fP is a pointer to an array of char * pointers, containing the diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 4fb87ad56..6a3d74ac6 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -26,13 +26,13 @@ libcurl-errors \- error codes in libcurl .SH DESCRIPTION This man page includes most, if not all, available error codes in libcurl. -Why they occur and possibly what you can do to fix the problem. +Why they occur and possibly what you can do to fix the problem are also included. .SH "CURLcode" Almost all "easy" interface functions return a CURLcode error code. No matter what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER\fP is a good idea as it will give you a human readable error string that may offer -more details about the error cause than just the error code -does. \fIcurl_easy_strerror(3)\fP can be called to get an error string from a +more details about the cause of the error than just the error code. +\fIcurl_easy_strerror(3)\fP can be called to get an error string from a given CURLcode number. CURLcode is one of the following: @@ -55,7 +55,7 @@ Couldn't resolve host. The given remote host was not resolved. .IP "CURLE_COULDNT_CONNECT (7)" Failed to connect() to host or proxy. .IP "CURLE_FTP_WEIRD_SERVER_REPLY (8)" -After connecting to an FTP server, libcurl expects to get a certain reply +After connecting to a FTP server, libcurl expects to get a certain reply back. This error code implies that it got a strange or bad reply. The given remote server is probably not an OK FTP server. .IP "CURLE_REMOTE_ACCESS_DENIED (9)" @@ -73,7 +73,7 @@ fails to parse that line, this return code is passed back. .IP "CURLE_FTP_CANT_GET_HOST (15)" An internal failure to lookup the host used for the new connection. .IP "CURLE_FTP_COULDNT_SET_TYPE (17)" -Received an error when trying to set the transfer mode to binary or ascii. +Received an error when trying to set the transfer mode to binary or ASCII. .IP "CURLE_PARTIAL_FILE (18)" A file transfer was shorter or larger than expected. This happens when the server first reports an expected transfer size, and then delivers data that @@ -94,19 +94,19 @@ An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback. .IP "CURLE_UPLOAD_FAILED (25)" Failed starting the upload. For FTP, the server typically denied the STOR -command. The error buffer usually contains the server's explanation to this. +command. The error buffer usually contains the server's explanation for this. (This error code was formerly known as CURLE_FTP_COULDNT_STOR_FILE.) .IP "CURLE_READ_ERROR (26)" There was a problem reading a local file or an error returned by the read callback. .IP "CURLE_OUT_OF_MEMORY (27)" A memory allocation request failed. This is serious badness and -things are severely screwed up if this ever occur. +things are severely screwed up if this ever occurs. .IP "CURLE_OPERATION_TIMEDOUT (28)" Operation timeout. The specified time-out period was reached according to the conditions. .IP "CURLE_FTP_PORT_FAILED (30)" -The FTP PORT command returned error. This mostly happen when you haven't +The FTP PORT command returned error. This mostly happens when you haven't specified a good enough address for libcurl to use. See \fICURLOPT_FTPPORT\fP. .IP "CURLE_FTP_COULDNT_USE_REST (31)" The FTP REST command returned error. This should never happen if the server is @@ -162,52 +162,52 @@ Failed sending network data. .IP "CURLE_RECV_ERROR (56)" Failure with receiving network data. .IP "CURLE_SSL_CERTPROBLEM (58)" -problem with the local client certificate +problem with the local client certificate. .IP "CURLE_SSL_CIPHER (59)" -Couldn't use specified cipher +Couldn't use specified cipher. .IP "CURLE_SSL_CACERT (60)" -Peer certificate cannot be authenticated with known CA certificates +Peer certificate cannot be authenticated with known CA certificates. .IP "CURLE_BAD_CONTENT_ENCODING (61)" -Unrecognized transfer encoding +Unrecognized transfer encoding. .IP "CURLE_LDAP_INVALID_URL (62)" -Invalid LDAP URL +Invalid LDAP URL. .IP "CURLE_FILESIZE_EXCEEDED (63)" -Maximum file size exceeded +Maximum file size exceeded. .IP "CURLE_USE_SSL_FAILED (64)" -Requested FTP SSL level failed +Requested FTP SSL level failed. .IP "CURLE_SEND_FAIL_REWIND (65)" When doing a send operation curl had to rewind the data to retransmit, but the -rewinding operation failed +rewinding operation failed. .IP "CURLE_SSL_ENGINE_INITFAILED (66)" -Initiating the SSL Engine failed +Initiating the SSL Engine failed. .IP "CURLE_LOGIN_DENIED (67)" The remote server denied curl to login (Added in 7.13.1) .IP "CURLE_TFTP_NOTFOUND (68)" -File not found on TFTP server +File not found on TFTP server. .IP "CURLE_TFTP_PERM (69)" -Permission problem on TFTP server +Permission problem on TFTP server. .IP "CURLE_REMOTE_DISK_FULL (70)" -Out of disk space on the server +Out of disk space on the server. .IP "CURLE_TFTP_ILLEGAL (71)" -Illegal TFTP operation +Illegal TFTP operation. .IP "CURLE_TFTP_UNKNOWNID (72)" -Unknown TFTP transfer ID +Unknown TFTP transfer ID. .IP "CURLE_REMOTE_FILE_EXISTS (73)" -File already exists and will not be overwritten +File already exists and will not be overwritten. .IP "CURLE_TFTP_NOSUCHUSER (74)" -This error should never be returned by a properly functioning TFTP server +This error should never be returned by a properly functioning TFTP server. .IP "CURLE_CONV_FAILED (75)" -Character conversion failed +Character conversion failed. .IP "CURLE_CONV_REQD (76)" -Caller must register conversion callbacks +Caller must register conversion callbacks. .IP "CURLE_SSL_CACERT_BADFILE (77)" Problem with reading the SSL CA cert (path? access rights?) .IP "CURLE_REMOTE_FILE_NOT_FOUND (78)" -The resource referenced in the URL does not exist +The resource referenced in the URL does not exist. .IP "CURLE_SSH (79)" -An unspecified error occurred during the SSH session +An unspecified error occurred during the SSH session. .IP "CURLE_SSL_SHUTDOWN_FAILED (80)" -Failed to shut down the SSL connection +Failed to shut down the SSL connection. .IP "CURLE_AGAIN (81)" Socket is not ready for send/recv wait till it's ready and try again. This return code is only returned from \fIcurl_easy_recv(3)\fP and @@ -217,7 +217,7 @@ Failed to load CRL file (Added in 7.19.0) .IP "CURLE_SSL_ISSUER_ERROR (83)" Issuer check failed (Added in 7.19.0) .IP "CURLE_OBSOLETE*" -These error codes will never be returned. They used to be used in an old libcurl +These error codes will never be returned. They were used in an old libcurl version and are currently unused. .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 6e33581d1..0b70ae943 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -121,7 +121,7 @@ again (possibly after having altered some options at your own choice). .SH "MULTI_SOCKET" Since 7.16.0, the \fIcurl_multi_socket(3)\fP function offers a way for applications to not only avoid being forced to use select(), but it also -offers a much more high-performing API that will make a significant difference +offers a much more high-performance API that will make a significant difference for applications using large numbers of simultaneous connections. \fIcurl_multi_socket(3)\fP (and \fIcurl_multi_socket_all(3)\fP) is then used diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index dd4be66c4..10474be4a 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -36,7 +36,7 @@ What will be generally referred to as 'the program' will be the collected source code that you write that is using libcurl for transfers. The program is outside libcurl and libcurl is outside of the program. -To get the more details on all options and functions described herein, please +To get more details on all options and functions described herein, please refer to their respective man pages. .SH "Building" @@ -72,8 +72,8 @@ if an installed libcurl has been built with SSL support enabled, use $ curl-config --feature And if SSL is supported, the keyword 'SSL' will be written to stdout, -possibly together with a few other features that can be on and off on -different libcurls. +possibly together with a few other features that could be either on or off on +for different libcurls. See also the "Features libcurl Provides" further down. .IP "autoconf macro" @@ -87,7 +87,7 @@ The people behind libcurl have put a considerable effort to make libcurl work on a large amount of different operating systems and environments. You program libcurl the same way on all platforms that libcurl runs on. There -are only very few minor considerations that differs. If you just make sure to +are only very few minor considerations that differ. If you just make sure to write your code portable enough, you may very well create yourself a very portable program. libcurl shouldn't stop you from that. @@ -113,7 +113,7 @@ should not tell libcurl to do this as well. .IP CURL_GLOBAL_SSL which only does anything on libcurls compiled and built SSL-enabled. On these systems, this will make libcurl initialize the SSL library properly for this -application. This is only needed to do once for each application so if your +application. This only needs to be done once for each application so if your program or another library already does this, this bit should not be needed. .RE @@ -256,7 +256,7 @@ one thread at a time. libcurl is completely thread safe, except for two issues: signals and SSL/TLS handlers. Signals are used for timing out name resolves (during DNS lookup) - -when built without c-ares support and not on Windows.. +when built without c-ares support and not on Windows. If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are then of course using the underlying SSL library multi-threaded and those libs @@ -274,11 +274,11 @@ GnuTLS NSS - is claimed to be thread-safe already without anything required + is claimed to be thread-safe already without anything required. yassl - Required actions unknown + Required actions unknown. When using multiple threads you should set the CURLOPT_NOSIGNAL option to 1 for all handles. Everything will or might work fine except that timeouts are @@ -303,9 +303,9 @@ received output to study is also a clever way to get a better understanding why the server behaves the way it does. Include headers in the normal body output with CURLOPT_HEADER set 1. -Of course there are bugs left. We need to get to know about them to be able +Of course, there are bugs left. We need to know about them to be able to fix them, so we're quite dependent on your bug reports! When you do report -suspected bugs in libcurl, please include as much details you possibly can: a +suspected bugs in libcurl, please include as many details as you possibly can: a protocol dump that CURLOPT_VERBOSE produces, library version, as much as possible of your code that uses libcurl, operating system name and version, compiler name and version etc. @@ -424,11 +424,11 @@ To pass the known private key password to libcurl: The previous chapter showed how to set user name and password for getting URLs that require authentication. When using the HTTP protocol, there are many different ways a client can provide those credentials to the server and -you can control what way libcurl will (attempt to) use. The default HTTP +you can control which way libcurl will (attempt to) use them. The default HTTP authentication method is called 'Basic', which is sending the name and password in clear-text in the HTTP request, base64-encoded. This is insecure. -At the time of this writing libcurl can be built to use: Basic, Digest, NTLM, +At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use with CURLOPT_HTTPAUTH as in: @@ -475,7 +475,7 @@ CURLOPT_POSTFIELDS, this automatically switches the handle to use POST in the upcoming request. Ok, so what if you want to post binary data that also requires you to set the -Content-Type: header of the post? Well, binary posts prevents libcurl from +Content-Type: header of the post? Well, binary posts prevent libcurl from being able to do strlen() on the data to figure out the size, so therefore we must tell libcurl the size of the post data. Setting headers in libcurl requests are done in a generic way, by building a list of our own headers and @@ -502,7 +502,7 @@ then passing that list to libcurl. While the simple examples above cover the majority of all cases where HTTP POST operations are required, they don't do multi-part formposts. Multi-part formposts were introduced as a better way to post (possibly large) binary data -and was first documented in the RFC1867. They're called multi-part because +and were first documented in the RFC1867. They're called multi-part because they're built by a chain of parts, each being a single unit. Each part has its own name and contents. You can in fact create and post a multi-part formpost with the regular libcurl POST support described above, but that would require @@ -511,7 +511,7 @@ easier, libcurl provides \fIcurl_formadd(3)\fP. Using this function, you add parts to the form. When you're done adding parts, you post the whole form. The following example sets two simple text parts with plain textual contents, -and then a file with binary contents and upload the whole thing. +and then a file with binary contents and uploads the whole thing. .nf struct curl_httppost *post=NULL; @@ -540,7 +540,7 @@ headers. It means that each one of these separate parts get a few headers set that describe the individual content-type, size etc. To enable your application to handicraft this formpost even more, libcurl allows you to supply your own set of custom headers to such an individual form part. You can -of course supply headers to as many parts you like, but this little example +of course supply headers to as many parts as you like, but this little example will show how you set headers to one specific part when you add that to the post handle: @@ -562,8 +562,8 @@ post handle: Since all options on an easyhandle are "sticky", they remain the same until changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell -curl to go back to a plain GET request if you intend to do such a one as your -next request. You force an easyhandle to back to GET by using the +curl to go back to a plain GET request if you intend to do one as your +next request. You force an easyhandle to go back to GET by using the CURLOPT_HTTPGET option: curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L); @@ -574,10 +574,10 @@ doing a POST. It will just make it POST without any data to send! .SH "Showing Progress" For historical and traditional reasons, libcurl has a built-in progress meter -that can be switched on and then makes it presents a progress meter in your +that can be switched on and then makes it present a progress meter in your terminal. -Switch on the progress meter by, oddly enough, set CURLOPT_NOPROGRESS to +Switch on the progress meter by, oddly enough, setting CURLOPT_NOPROGRESS to zero. This option is set to 1 by default. For most applications however, the built-in progress meter is useless and @@ -642,7 +642,7 @@ restrictions on what can actually happen. A requested URL that might not be a HTTP URL will be still be passed to the HTTP proxy to deliver back to libcurl. This happens transparently, and an application may not need to know. I say "may", because at times it is very important to understand that -all operations over a HTTP proxy is using the HTTP protocol. For example, you +all operations over a HTTP proxy use the HTTP protocol. For example, you can't invoke your own custom FTP commands or even proper FTP directory listings. @@ -773,7 +773,7 @@ Even if the connection is dropped, all connections involving SSL to the same host again, will benefit from libcurl's session ID cache that drastically reduces re-connection time. -FTP connections that are kept alive saves a lot of time, as the command- +FTP connections that are kept alive save a lot of time, as the command- response round-trips are skipped, and also you don't risk getting blocked without permission to login again like on many FTP servers only allowing N persons to be logged in at the same time. @@ -786,7 +786,7 @@ may also be added in the future. Each easy handle will attempt to keep the last few connections alive for a while in case they are to be used again. You can set the size of this "cache" -with the CURLOPT_MAXCONNECTS option. Default is 5. It is very seldom any +with the CURLOPT_MAXCONNECTS option. Default is 5. There is very seldom any point in changing this value, and if you think of changing this it is often just a matter of thinking again. @@ -799,7 +799,7 @@ CURLOPT_FORBID_REUSE to 1. .SH "HTTP Headers Used by libcurl" When you use libcurl to do HTTP requests, it'll pass along a series of headers -automatically. It might be good for you to know and understand these ones. You +automatically. It might be good for you to know and understand these. You can replace or remove them by using the CURLOPT_HTTPHEADER option. .IP "Host" @@ -823,7 +823,7 @@ this header. .SH "Customizing Operations" There is an ongoing development today where more and more protocols are built upon HTTP for transport. This has obvious benefits as HTTP is a tested and -reliable protocol that is widely deployed and have excellent proxy-support. +reliable protocol that is widely deployed and has excellent proxy-support. When you use one of these protocols, and even when doing other kinds of programming you may need to change the traditional HTTP (or FTP or...) @@ -839,14 +839,14 @@ for you. It is very simple to use: curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNRUQUEST"); When using the custom request, you change the request keyword of the actual -request you are performing. Thus, by default you make GET request but you can +request you are performing. Thus, by default you make a GET request but you can also make a POST operation (as described before) and then replace the POST keyword if you want to. You're the boss. .IP "Modify Headers" HTTP-like protocols pass a series of headers to the server when doing the request, and you're free to pass any amount of extra headers that you -think fit. Adding headers are this easy: +think fit. Adding headers is this easy: .nf struct curl_slist *headers=NULL; /* init to NULL is important */ @@ -873,8 +873,8 @@ replace them by simply setting them too: .IP "Delete Headers" If you replace an existing header with one with no contents, you will prevent -the header from being sent. Like if you want to completely prevent the -\&"Accept:" header to be sent, you can disable it with code similar to this: +the header from being sent. For instance, if you want to completely prevent the +\&"Accept:" header from being sent, you can disable it with code similar to this: headers = curl_slist_append(headers, "Accept:"); @@ -893,7 +893,7 @@ data size is unknown. .IP "HTTP Version" All HTTP requests includes the version number to tell the server which version -we support. libcurl speak HTTP 1.1 by default. Some very old servers don't +we support. libcurl speaks HTTP 1.1 by default. Some very old servers don't like getting 1.1-requests and when dealing with stubborn old things like that, you can tell libcurl to use 1.0 instead by doing something like this: @@ -902,12 +902,12 @@ you can tell libcurl to use 1.0 instead by doing something like this: .IP "FTP Custom Commands" Not all protocols are HTTP-like, and thus the above may not help you when -you want to make for example your FTP transfers to behave differently. +you want to make, for example, your FTP transfers to behave differently. Sending custom commands to a FTP server means that you need to send the commands exactly as the FTP server expects them (RFC959 is a good guide here), and you can only use commands that work on the control-connection -alone. All kinds of commands that requires data interchange and thus needs +alone. All kinds of commands that require data interchange and thus need a data-connection must be left to libcurl's own judgment. Also be aware that libcurl will do its very best to change directory to the target directory before doing any transfer, so if you change directory (with CWD @@ -947,7 +947,7 @@ combine with CURLOPT_NOBODY. If this option is set, no actual file content transfer will be performed. .IP "FTP Custom CUSTOMREQUEST" -If you do what list the contents of a FTP directory using your own defined FTP +If you do want to list the contents of a FTP directory using your own defined FTP command, CURLOPT_CUSTOMREQUEST will do just that. "NLST" is the default one for listing directories but you're free to pass in your idea of a good alternative. @@ -959,7 +959,7 @@ subsequent request to the server that matches the particular conditions set. The conditions include that the domain name and path match and that the cookie hasn't become too old. -In real-world cases, servers send new cookies to replace existing one to +In real-world cases, servers send new cookies to replace existing ones to update them. Server use cookies to "track" users and to keep "sessions". Cookies are sent from server to clients with the header Set-Cookie: and @@ -972,7 +972,7 @@ to set a cookie string like this: In many cases, that is not enough. You might want to dynamically save whatever cookies the remote server passes to you, and make sure those cookies -are then use accordingly on later requests. +are then used accordingly on later requests. One way to do this, is to save all headers you receive in a plain file and when you make a request, you tell libcurl to read the previous headers to @@ -989,16 +989,16 @@ disk at all. Note that the file you specify to CURLOPT_COOKIEFILE doesn't have to exist to enable the parser, so a common way to just enable the parser and not read any cookies is to use a the name of a file you know doesn't exist. -If you rather use existing cookies that you've previously received with your +If you would rather use existing cookies that you've previously received with your Netscape or Mozilla browsers, you can make libcurl use that cookie file as input. The CURLOPT_COOKIEFILE is used for that too, as libcurl will automatically find out what kind of file it is and act accordingly. -The perhaps most advanced cookie operation libcurl offers, is saving the +Perhaps the most advanced cookie operation libcurl offers, is saving the entire internal cookie state back into a Netscape/Mozilla formatted cookie file. We call that the cookie-jar. When you set a file name with CURLOPT_COOKIEJAR, that file name will be created and all received cookies -will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enabled +will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables cookies to get passed on properly between multiple handles without any information getting lost. @@ -1006,7 +1006,7 @@ information getting lost. FTP transfers use a second TCP/IP connection for the data transfer. This is usually a fact you can forget and ignore but at times this fact will come -back to haunt you. libcurl offers several different ways to custom how the +back to haunt you. libcurl offers several different ways to customize how the second connection is being made. libcurl can either connect to the server a second time or tell the server to @@ -1103,7 +1103,7 @@ authentication, HTTPS, FTPS, SCP, SFTP and FTP-kerberos are a few examples. On a related issue, be aware that even in situations like when you have problems with libcurl and ask someone for help, everything you reveal in order to get best possible help might also impose certain security related -risks. Host names, user names, paths, operating system specifics etc (not to +risks. Host names, user names, paths, operating system specifics, etc (not to mention passwords of course) may in fact be used by intruders to gain additional information of a potential target. @@ -1114,10 +1114,10 @@ information with faked data. .SH "Multiple Transfers Using the multi Interface" The easy interface as described in detail in this document is a synchronous -interface that transfers one file at a time and doesn't return until its +interface that transfers one file at a time and doesn't return until it is done. -The multi interface on the other hand, allows your program to transfer +The multi interface, on the other hand, allows your program to transfer multiple files in both directions at the same time, without forcing you to use multiple threads. The name might make it seem that the multi interface is for multi-threaded programs, but the truth is almost the @@ -1129,7 +1129,7 @@ synchronizing many threads. To use this interface, you are better off if you first understand the basics of how to use the easy interface. The multi interface is simply a way to make -multiple transfers at the same time by adding up multiple easy handles in to +multiple transfers at the same time by adding up multiple easy handles into a "multi stack". You create the easy handles you want and you set all the options just like you @@ -1138,7 +1138,7 @@ have been told above, and then you create a multi handle with with \fIcurl_multi_add_handle(3)\fP. When you've added the handles you have for the moment (you can still add new -ones at any time), you start the transfers by call +ones at any time), you start the transfers by calling \fIcurl_multi_perform(3)\fP. \fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as @@ -1157,7 +1157,7 @@ with the particular file descriptors libcurl uses for the moment. When you then call select(), it'll return when one of the file handles signal action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do what it wants to do. Take note that libcurl does also feature some time-out -code so we advice you to never use very long timeouts on select() before you +code so we advise you to never use very long timeouts on select() before you call \fIcurl_multi_perform(3)\fP, which thus should be called unconditionally every now and then even if none of its file descriptors have signaled ready. Another precaution you should use: always call @@ -1188,7 +1188,7 @@ to figure out success on each individual transfer. .IP "[1]" libcurl 7.10.3 and later have the ability to switch over to chunked -Transfer-Encoding in cases were HTTP uploads are done with data of an unknown +Transfer-Encoding in cases where HTTP uploads are done with data of an unknown size. .IP "[2]" This happens on Windows machines when libcurl is built and used as a |