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
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
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
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
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.
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
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
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
(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
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
\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
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
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
.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.
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).
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.
.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.
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.
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.
.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
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.
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
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.
.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.
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
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.
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
(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
.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
(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.
(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
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_*)
\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
.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
.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
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
.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.
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
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.
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
.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
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
.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)
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
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,
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.
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
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
.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"
.\"
.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
.\"
.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>
.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
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.
.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), "
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
.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.
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) "
.\"
.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>
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.
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
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):
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
.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
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
.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
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
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.
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.
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
\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
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
.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.
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
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
.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
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);
} 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.
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
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:
.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)"
.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
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
.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
.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
.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
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"
$ 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"
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.
.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
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
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
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.
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:
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
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
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;
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:
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);
.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
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.
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.
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.
.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"
.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...)
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 */
.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:");
.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:
.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
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.
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
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
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.
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
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.
.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
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
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
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
.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
projects / thirdparty / curl.git / commitdiff
