From 01f04b9a4127aa2bfb9cdaa8b2d4114268f45514 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2002 10:09:48 +0000 Subject: ripped out from ../ and put in its own directory now --- docs/libcurl/Makefile.am | 68 ++++ docs/libcurl/curl_easy_cleanup.3 | 29 ++ docs/libcurl/curl_easy_duphandle.3 | 37 ++ docs/libcurl/curl_easy_getinfo.3 | 114 ++++++ docs/libcurl/curl_easy_init.3 | 26 ++ docs/libcurl/curl_easy_perform.3 | 46 +++ docs/libcurl/curl_easy_setopt.3 | 627 ++++++++++++++++++++++++++++++++ docs/libcurl/curl_escape.3 | 28 ++ docs/libcurl/curl_formadd.3 | 165 +++++++++ docs/libcurl/curl_formfree.3 | 27 ++ docs/libcurl/curl_formparse.3 | 18 + docs/libcurl/curl_getdate.3 | 80 ++++ docs/libcurl/curl_getenv.3 | 32 ++ docs/libcurl/curl_global_cleanup.3 | 27 ++ docs/libcurl/curl_global_init.3 | 49 +++ docs/libcurl/curl_mprintf.3 | 88 +++++ docs/libcurl/curl_multi_add_handle.3 | 17 + docs/libcurl/curl_multi_cleanup.3 | 18 + docs/libcurl/curl_multi_fdset.3 | 23 ++ docs/libcurl/curl_multi_info_read.3 | 35 ++ docs/libcurl/curl_multi_init.3 | 21 ++ docs/libcurl/curl_multi_perform.3 | 30 ++ docs/libcurl/curl_multi_remove_handle.3 | 17 + docs/libcurl/curl_slist_append.3 | 29 ++ docs/libcurl/curl_slist_free_all.3 | 22 ++ docs/libcurl/curl_strequal.3 | 30 ++ docs/libcurl/curl_strnequal.3 | 1 + docs/libcurl/curl_unescape.3 | 27 ++ docs/libcurl/curl_version.3 | 27 ++ docs/libcurl/index.html | 38 ++ docs/libcurl/libcurl.3 | 132 +++++++ 31 files changed, 1928 insertions(+) create mode 100644 docs/libcurl/Makefile.am create mode 100644 docs/libcurl/curl_easy_cleanup.3 create mode 100644 docs/libcurl/curl_easy_duphandle.3 create mode 100644 docs/libcurl/curl_easy_getinfo.3 create mode 100644 docs/libcurl/curl_easy_init.3 create mode 100644 docs/libcurl/curl_easy_perform.3 create mode 100644 docs/libcurl/curl_easy_setopt.3 create mode 100644 docs/libcurl/curl_escape.3 create mode 100644 docs/libcurl/curl_formadd.3 create mode 100644 docs/libcurl/curl_formfree.3 create mode 100644 docs/libcurl/curl_formparse.3 create mode 100644 docs/libcurl/curl_getdate.3 create mode 100644 docs/libcurl/curl_getenv.3 create mode 100644 docs/libcurl/curl_global_cleanup.3 create mode 100644 docs/libcurl/curl_global_init.3 create mode 100644 docs/libcurl/curl_mprintf.3 create mode 100644 docs/libcurl/curl_multi_add_handle.3 create mode 100644 docs/libcurl/curl_multi_cleanup.3 create mode 100644 docs/libcurl/curl_multi_fdset.3 create mode 100644 docs/libcurl/curl_multi_info_read.3 create mode 100644 docs/libcurl/curl_multi_init.3 create mode 100644 docs/libcurl/curl_multi_perform.3 create mode 100644 docs/libcurl/curl_multi_remove_handle.3 create mode 100644 docs/libcurl/curl_slist_append.3 create mode 100644 docs/libcurl/curl_slist_free_all.3 create mode 100644 docs/libcurl/curl_strequal.3 create mode 100644 docs/libcurl/curl_strnequal.3 create mode 100644 docs/libcurl/curl_unescape.3 create mode 100644 docs/libcurl/curl_version.3 create mode 100644 docs/libcurl/index.html create mode 100644 docs/libcurl/libcurl.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am new file mode 100644 index 000000000..c6d6c9d46 --- /dev/null +++ b/docs/libcurl/Makefile.am @@ -0,0 +1,68 @@ +# +# $Id$ +# + +AUTOMAKE_OPTIONS = foreign no-dependencies + +man_MANS = \ + curl_easy_cleanup.3 \ + curl_easy_getinfo.3 \ + curl_easy_init.3 \ + curl_easy_perform.3 \ + curl_easy_setopt.3 \ + curl_easy_duphandle.3 \ + curl_formparse.3 \ + curl_formadd.3 \ + curl_formfree.3 \ + curl_getdate.3 \ + curl_getenv.3 \ + curl_slist_append.3 \ + curl_slist_free_all.3 \ + curl_version.3 \ + curl_escape.3 \ + curl_unescape.3 \ + curl_strequal.3 \ + curl_strnequal.3 \ + curl_mprintf.3 \ + curl_global_init.3 \ + curl_global_cleanup.3 \ + libcurl.3 + +HTMLPAGES = \ + curl_easy_cleanup.html \ + curl_easy_getinfo.html \ + curl_easy_init.html \ + curl_easy_perform.html \ + curl_easy_setopt.html \ + curl_easy_duphandle.html \ + curl_formadd.html \ + curl_formparse.html \ + curl_formfree.html \ + curl_getdate.html \ + curl_getenv.html \ + curl_slist_append.html \ + curl_slist_free_all.html \ + curl_version.html \ + curl_escape.html \ + curl_unescape.html \ + curl_strequal.html \ + curl_strnequal.html \ + curl_mprintf.html \ + curl_global_init.html \ + curl_global_cleanup.html \ + libcurl.html \ + index.html + +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) + +MAN2HTML= gnroff -man $< | man2html >$@ + +SUFFIXES = .1 .3 .html + +html: $(HTMLPAGES) + +.3.html: + $(MAN2HTML) + +.1.html: + $(MAN2HTML) diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 new file mode 100644 index 000000000..267c2f4f4 --- /dev/null +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -0,0 +1,29 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_easy_cleanup 3 "5 March 2001" "libcurl 7.7" "libcurl Manual" +.SH NAME +curl_easy_cleanup - End a libcurl session +.SH SYNOPSIS +.B #include +.sp +.BI "void curl_easy_cleanup(CURL *" handle ");" +.ad +.SH DESCRIPTION +This function must be the last function to call for a curl session. It is the +opposite of the +.I curl_easy_init +function and must be called with the same +.I handle +as input as the curl_easy_init call returned. + +This will effectively close all connections libcurl has been used and possibly +has kept open until now. Don't call this function if you intend to transfer +more files (libcurl 7.7 or later). +.SH RETURN VALUE +None +.SH "SEE ALSO" +.BR curl_easy_init "(3), " +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 new file mode 100644 index 000000000..b570dc432 --- /dev/null +++ b/docs/libcurl/curl_easy_duphandle.3 @@ -0,0 +1,37 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_easy_duphandle 3 "18 September 2001" "libcurl 7.9" "libcurl Manual" +.SH NAME +curl_easy_duphandle - Clone a libcurl session handle +.SH SYNOPSIS +.B #include +.sp +.BI "CURL *curl_easy_duphandle(CURL *"handle ");" +.ad +.SH DESCRIPTION +This function will return a new curl handle, a duplicate, using all the +options previously set in the input curl \fIhandle\fP. Both handles can +subsequently be used independently and they must both be freed with +\fIcurl_easy_cleanup()\fP. + +All strings that the input handle has been told to point to (as opposed to +copy) with previous calls to \fIcurl_easy_setopt\fP using char * inputs, will +be pointed to by the new handle as well. You must therefore make sure to keep +the data around until both handles have been cleaned up. + +The new handle will \fBnot\fP inherit any state information, no connections, +no SSL sessions and no cookies. + +\fBNote\fP that even in multi-threaded programs, this function must be called +in a synchronous way, the input handle may not be in use when cloned. + +This function was added in libcurl 7.9. +.SH RETURN VALUE +If this function returns NULL, something went wrong and no valid handle was +returned. +.SH "SEE ALSO" +.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_global_init "(3) +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 new file mode 100644 index 000000000..fba3947fe --- /dev/null +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -0,0 +1,114 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_easy_init 3 "31 Jan 2001" "libcurl 7.9.4" "libcurl Manual" +.SH NAME +curl_easy_getinfo - Extract information from a curl session (added in 7.4) +.SH SYNOPSIS +.B #include +.sp +.BI "CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );" +.ad +.SH DESCRIPTION +Request internal information from the curl session with this function. The +third argument +.B MUST +be a pointer to a long, a pointer to a char * or a pointer to a double (as +this documentation describes further down). The data pointed-to will be +filled in accordingly and can be relied upon only if the function returns +CURLE_OK. This function is intended to get used *AFTER* a performed transfer, +all results from this function are undefined until the transfer is completed. +.SH AVAILABLE INFORMATION +These are informations that can be extracted: +.TP 0.8i +.B CURLINFO_EFFECTIVE_URL +Pass a pointer to a 'char *' to receive the last used effective URL. +.TP +.B CURLINFO_HTTP_CODE +Pass a pointer to a long to receive the last received HTTP code. +.TP +.B CURLINFO_FILETIME +Pass a pointer to a long to receive the remote time of the retrieved +document. If you get -1, it can be because of many reasons (unknown, the +server hides it or the server doesn't support the command that tells document +time etc) and the time of the document is unknown. Note that you must tell the +server to collect this information before the transfer is made, by using the +CURLOPT_FILETIME option to \fIcurl_easy_setopt(3)\fP. (Added in 7.5) +.TP +.B CURLINFO_TOTAL_TIME +Pass a pointer to a double to receive the total transaction time in seconds +for the previous transfer. +.TP +.B CURLINFO_NAMELOOKUP_TIME +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the name resolving was completed. +.TP +.B CURLINFO_CONNECT_TIME +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the connect to the remote host (or proxy) was completed. +.TP +.B CURLINFO_PRETRANSFER_TIME +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the file transfer is just about to begin. This includes all +pre-transfer commands and negotiations that are specific to the particular +protocol(s) involved. +.TP +.B CURLINFO_STARTTRANSFER_TIME +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the first byte is just about to be transfered. This includes +CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate +the result. +.TP +.B CURLINFO_SIZE_UPLOAD +Pass a pointer to a double to receive the total amount of bytes that were +uploaded. +.TP +.B CURLINFO_SIZE_DOWNLOAD +Pass a pointer to a double to receive the total amount of bytes that were +downloaded. +.TP +.B CURLINFO_SPEED_DOWNLOAD +Pass a pointer to a double to receive the average download speed that curl +measured for the complete download. +.TP +.B CURLINFO_SPEED_UPLOAD +Pass a pointer to a double to receive the average upload speed that curl +measured for the complete upload. +.TP +.B CURLINFO_HEADER_SIZE +Pass a pointer to a long to receive the total size of all the headers +received. +.TP +.B CURLINFO_REQUEST_SIZE +Pass a pointer to a long to receive the total size of the issued +requests. This is so far only for HTTP requests. Note that this may be more +than one request if FOLLOWLOCATION is true. +.TP +.B CURLINFO_SSL_VERIFYRESULT +Pass a pointer to a long to receive the result of the certification +verification that was requested (using the CURLOPT_SSL_VERIFYPEER option to +curl_easy_setopt). (Added in 7.4.2) +.TP +.B CURLINFO_CONTENT_LENGTH_DOWNLOAD +Pass a pointer to a double to receive the content-length of the download. This +is the value read from the Content-Length: field. (Added in 7.6.1) +.TP +.B CURLINFO_CONTENT_LENGTH_UPLOAD +Pass a pointer to a double to receive the specified size of the upload. +(Added in 7.6.1) +.TP +.B CURLINFO_CONTENT_TYPE +Pass a pointer to a 'char *' to receive the content-type of the downloaded +object. This is the value read from the Content-Type: field. If you get NULL, +it means that the server didn't send a valid Content-Type header or that the +protocol used doesn't support this. (Added in 7.9.4) +.PP + +.SH RETURN VALUE +If the operation was successful, CURLE_OK is returned. Otherwise an +appropriate error code will be returned. +.SH "SEE ALSO" +.BR curl_easy_setopt "(3)" +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 new file mode 100644 index 000000000..cb695bb05 --- /dev/null +++ b/docs/libcurl/curl_easy_init.3 @@ -0,0 +1,26 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_easy_init 3 "1 March 2002" "libcurl 7.8.1" "libcurl Manual" +.SH NAME +curl_easy_init - Start a libcurl session +.SH SYNOPSIS +.B #include +.sp +.BI "CURL *curl_easy_init( );" +.ad +.SH DESCRIPTION +This function must be the first function to call, and it returns a CURL handle +that you shall use as input to the other easy-functions. The init calls +intializes curl and this call MUST have a corresponding call to +.I curl_easy_cleanup +when the operation is complete. + +.SH RETURN VALUE +If this function returns NULL, something went wrong and you cannot use the +other curl functions. +.SH "SEE ALSO" +.BR curl_easy_cleanup "(3), " curl_global_init "(3) +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3 new file mode 100644 index 000000000..a073d723d --- /dev/null +++ b/docs/libcurl/curl_easy_perform.3 @@ -0,0 +1,46 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_easy_perform 3 "5 Mar 2001" "libcurl 7.7" "libcurl Manual" +.SH NAME +curl_easy_perform - Perform a file transfer +.SH SYNOPSIS +.B #include +.sp +.BI "CURLcode curl_easy_perform(CURL *" handle "); +.ad +.SH DESCRIPTION +This function is called after the init and all the curl_easy_setopt() calls +are made, and will perform the transfer as described in the options. +It must be called with the same +.I handle +as input as the curl_easy_init call returned. + +libcurl version 7.7 or later (for older versions see below): You can do any +amount of calls to curl_easy_perform() while using the same handle. If you +intend to transfer more than one file, you are even encouraged to do +so. libcurl will then attempt to re-use the same connection for the following +transfers, thus making the operations faster, less CPU intense and using less +network resources. Just note that you will have to use +.I curl_easy_setopt +between the invokes to set options for the following curl_easy_perform. + +You must never call this function simultaneously from two places using the +same handle. Let the function return first before invoking it another time. If +you want parallel transfers, you must use several curl handles. + +Before libcurl version 7.7: You are only allowed to call this function once +using the same handle. If you want to do repeated calls, you must call +curl_easy_cleanup and curl_easy_init again first. +.SH RETURN VALUE +0 means everything was ok, non-zero means an error occurred as +.I +defines. If the CURLOPT_ERRORBUFFER was set with +.I curl_easy_setopt +there will be a readable error message in the error buffer when non-zero is +returned. +.SH "SEE ALSO" +.BR curl_easy_init "(3), " curl_easy_setopt "(3), " +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 new file mode 100644 index 000000000..4067cec5e --- /dev/null +++ b/docs/libcurl/curl_easy_setopt.3 @@ -0,0 +1,627 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_easy_setopt 3 "10 Dec 2001" "libcurl 7.9.2" "libcurl Manual" +.SH NAME +curl_easy_setopt - Set curl easy-session options +.SH SYNOPSIS +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); +.ad +.SH DESCRIPTION +curl_easy_setopt() is used to tell libcurl how to behave. Most operations in +libcurl have default actions, and by using the appropriate options to +\fIcurl_easy_setopt\fP, you can change them. All options are set with the +\fIoption\fP followed by a \fIparameter\fP. That parameter can be a long, a +function pointer or an object pointer, all depending on what the specific +option expects. Read this manual carefully as bad input values may cause +libcurl to behave badly! You can only set one option in each function call. A +typical application uses many curl_easy_setopt() calls in the setup phase. + +\fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be +copied by the library. Instead you should keep them available until libcurl no +longer needs them. Failing to do so will cause very odd behavior or even +crashes. + +\fBNOTE2:\fP options set with this function call are valid for the forthcoming +data transfers that are performed when you invoke \fIcurl_easy_perform\fP. +The options are not in any way reset between transfers, so if you want +subsequent transfers with different options, you must change them between the +transfers. + +The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or +\fIcurl_easy_duphandle(3)\fP call. +.SH OPTIONS +The options are listed in a sort of random order, but you'll figure it out! +.TP 0.8i +.B CURLOPT_FILE +Data pointer to pass to the file write function. Note that if you specify the +\fICURLOPT_WRITEFUNCTION\fP, this is the pointer you'll get as input. If you +don't use a callback, you must pass a 'FILE *' as libcurl will pass this to +fwrite() when writing data. + +\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use the +\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience +crashes. +.TP +.B CURLOPT_WRITEFUNCTION +Function pointer that should match the following prototype: \fBsize_t +function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This +function gets called by libcurl as soon as there is data available to pass +available that needs to be saved. The size of the data pointed to by \fIptr\fP +is \fIsize\fP multiplied with \fInmemb\fP. Return the number of bytes +actually taken care of. If that amount differs from the amount passed to your +function, it'll signal an error to the library and it will abort the transfer +and return \fICURLE_WRITE_ERROR\fP. + +Set the \fIstream\fP argument with the \fBCURLOPT_FILE\fP option. + +\fBNOTE:\fP you will be passed as much data as possible in all invokes, but +you cannot possibly make any assumptions. It may be one byte, it may be +thousands. +.TP +.B CURLOPT_INFILE +Data pointer to pass to the file read function. Note that if you specify the +\fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you +don't specify a read callback, this must be a valid FILE *. + +\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use a +\fICURLOPT_READFUNCTION\fP if you set this option. +.TP +.B CURLOPT_READFUNCTION +Function pointer that should match the following prototype: \fBsize_t +function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This +function gets called by libcurl as soon as it needs to read data in order to +send it to the peer. The data area pointed at by the pointer \fIptr\fP may be +filled with at most \fIsize\fP multiplied with \fInmemb\fP number of +bytes. Your function must return the actual number of bytes that you stored in +that memory area. Returning 0 will signal end-of-file to the library and cause +it to stop the current transfer. +.TP +.B CURLOPT_INFILESIZE +When uploading a file to a remote site, this option should be used to tell +libcurl what the expected size of the infile is. +.TP +.B CURLOPT_URL +The actual URL to deal with. The parameter should be a char * to a zero +terminated string. The string must remain present until curl no longer needs +it, as it doesn't copy the string. + +\fBNOTE:\fP this option is (the only one) required to be set before +\fIcurl_easy_perform(3)\fP is called. +.TP +.B CURLOPT_PROXY +Set HTTP proxy to use. The parameter should be a char * to a zero terminated +string holding the host name or dotted IP address. To specify port number in +this string, append :[port] to the end of the host name. The proxy string may +be prefixed with [protocol]:// since any such prefix will be ignored. The +proxy's port number may optionally be specified with the separate option +\fICURLOPT_PROXYPORT\fP. + +\fBNOTE:\fP when you tell the library to use a HTTP proxy, libcurl will +transparently convert operations to HTTP even if you specify a FTP URL +etc. This may have an impact on what other features of the library you can +use, such as CURLOPT_QUOTE and similar FTP specifics that don't work unless +you tunnel through the HTTP proxy. Such tunneling is activated with +\fICURLOPT_HTTPPROXYTUNNEL\fP. + +\fBNOTE2:\fP libcurl respects the environment variables \fBhttp_proxy\fP, +\fBftp_proxy\fP, \fBall_proxy\fP etc, if any of those is set. +.TP +.B CURLOPT_PROXYPORT +Pass a long with this option to set the proxy port to connect to unless it is +specified in the proxy string \fICURLOPT_PROXY\fP. +.TP +.B CURLOPT_HTTPPROXYTUNNEL +Set the parameter to non-zero to get the library to tunnel all operations +through a given HTTP proxy. Note that 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. (Added in libcurl 7.3) +.TP +.B CURLOPT_VERBOSE +Set the parameter to non-zero to get the library to display a lot of verbose +information about its operations. Very useful for libcurl and/or protocol +debugging and understanding. + +You hardly ever want this set in production use, you will almost always want +this when you debug/report problems. +.TP +.B CURLOPT_HEADER +A non-zero parameter tells the library to include the header in the body +output. This is only relevant for protocols that actually have headers +preceding the data (like HTTP). +.TP +.B CURLOPT_NOPROGRESS +A non-zero parameter tells the library to shut of the built-in progress meter +completely. + +\fBNOTE:\fP future versions of libcurl is likely to not have any built-in +progress meter at all. +.TP +.B CURLOPT_NOBODY +A non-zero parameter tells the library to not include the body-part in the +output. This is only relevant for protocols that have separate header and body +parts. +.TP +.B CURLOPT_FAILONERROR +A non-zero parameter tells the library to fail silently if the HTTP code +returned is equal to or larger than 300. The default action would be to return +the page normally, ignoring that code. +.TP +.B CURLOPT_UPLOAD +A non-zero parameter tells the library to prepare for an upload. The +CURLOPT_INFILE and CURLOPT_INFILESIZE are also interesting for uploads. +.TP +.B CURLOPT_POST +A non-zero parameter tells the library to do a regular HTTP post. This is a +normal application/x-www-form-urlencoded kind, which is the most commonly used +one by HTML forms. See the CURLOPT_POSTFIELDS option for how to specify the +data to post and CURLOPT_POSTFIELDSIZE in how to set the data size. Starting +with libcurl 7.8, this option is obsolete. Using the CURLOPT_POSTFIELDS option +will imply this option. +.TP +.B CURLOPT_FTPLISTONLY +A non-zero parameter tells the library to just list the names of an ftp +directory, instead of doing a full directory listing that would include file +sizes, dates etc. +.TP +.B CURLOPT_FTPAPPEND +A non-zero parameter tells the library to append to the remote file instead of +overwrite it. This is only useful when uploading to a ftp site. +.TP +.B CURLOPT_NETRC +A non-zero parameter tells the library to scan your \fI~/.netrc\fP file to +find user name and password for the remote site you are about to access. Only +machine name, user name and password is taken into account (init macros and +similar things aren't supported). + +\fBNote:\fP libcurl does not verify that the file has the correct properties +set (as the standard Unix ftp client does). It should only be readable by +user. +.TP +.B CURLOPT_FOLLOWLOCATION +A non-zero parameter tells the library to follow any Location: header that the +server sends as part of a HTTP header. + +\fBNOTE:\fP this means that the library will re-send the same request on the +new location and follow new Location: headers all the way until no more such +headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number +of redirects libcurl will follow. +.TP +.B CURLOPT_TRANSFERTEXT +A non-zero parameter tells the library to use ASCII mode for ftp transfers, +instead of the default binary transfer. For LDAP transfers it gets the data in +plain text instead of HTML and 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 or +similar. +.TP +.B CURLOPT_PUT +A non-zero parameter tells the library to use HTTP PUT to transfer data. The +data should be set with CURLOPT_INFILE and CURLOPT_INFILESIZE. +.TP +.B CURLOPT_USERPWD +Pass a char * as parameter, which should be [user name]:[password] to use for +the connection. If the password is left out, you will be prompted for it. +\fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +.TP +.B CURLOPT_PROXYUSERPWD +Pass a char * as parameter, which should be [user name]:[password] to use for +the connection to the HTTP proxy. If the password is left out, you will be +prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own +prompt function. +.TP +.B CURLOPT_RANGE +Pass a char * as parameter, which should contain the specified range you +want. It should be in the format "X-Y", where X or Y may be left out. HTTP +transfers also support several intervals, separated with commas as in +\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP +server to send the response document in pieces (using standard MIME separation +techniques). +.TP +.B CURLOPT_ERRORBUFFER +Pass a char * to a buffer that the libcurl may store human readable error +messages in. This may be more helpful than just the return code from the +library. The buffer must be at least CURL_ERROR_SIZE big. + +\fBNote:\fP if the library does not return an error, the buffer may not have +been touched. Do not rely on the contents in those cases. +.TP +.B CURLOPT_TIMEOUT +Pass a long as parameter containing the maximum time in seconds that you allow +the libcurl transfer operation to take. Normally, name lookups can take a +considerable time and limiting operations to less than a few minutes risk +aborting perfectly normal operations. This option will cause curl to use the +SIGALRM to enable time-outing system calls. + +\fBNOTE:\fP this does not work in Unix multi-threaded programs, as it uses +signals. +.TP +.B CURLOPT_POSTFIELDS +Pass a char * as parameter, which should be the full data to post in a HTTP +post operation. This is a normal application/x-www-form-urlencoded kind, which +is the most commonly used one by HTML forms. See also the CURLOPT_POST. Since +7.8, using CURLOPT_POSTFIELDS implies CURLOPT_POST. + +\fBNote:\fP to make multipart/formdata posts (aka rfc1867-posts), check out +the \fICURLOPT_HTTPPOST\fP option. +.TP +.B CURLOPT_POSTFIELDSIZE +If you want to post data to the server without letting libcurl do a strlen() +to measure the data size, this option must be used. When this option is used +you can post fully binary data, which otherwise is likely to fail. If this +size is set to zero, the library will use strlen() to get the size. (Added in +libcurl 7.2) +.TP +.B CURLOPT_REFERER +Pass a pointer to a zero terminated string as parameter. It will be used to +set the Referer: header in the http request sent to the remote server. This +can be used to fool servers or scripts. You can also set any custom header +with \fICURLOPT_HTTPHEADER\fP. +.TP +.B CURLOPT_USERAGENT +Pass a pointer to a zero terminated string as parameter. It will be used to +set the User-Agent: header in the http request sent to the remote server. This +can be used to fool servers or scripts. You can also set any custom header +with \fICURLOPT_HTTPHEADER\fP. +.TP +.B 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 +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 +address. Default FTP operations are passive, and thus won't use PORT. +.TP +.B CURLOPT_LOW_SPEED_LIMIT +Pass a long as parameter. It contains the transfer speed in bytes per second +that the transfer should be below during CURLOPT_LOW_SPEED_TIME seconds for +the library to consider it too slow and abort. +.TP +.B CURLOPT_LOW_SPEED_TIME +Pass a long as parameter. It contains the time in seconds that the transfer +should be below the CURLOPT_LOW_SPEED_LIMIT for the library to consider it too +slow and abort. +.TP +.B CURLOPT_RESUME_FROM +Pass a long as parameter. It contains the offset in number of bytes that you +want the transfer to start from. +.TP +.B CURLOPT_COOKIE +Pass a pointer to a zero terminated string as parameter. It will be used to +set a cookie in the http request. The format of the string should be +[NAME]=[CONTENTS]; Where NAME is the cookie name. +.TP +.B CURLOPT_HTTPHEADER +Pass a pointer to a linked list of HTTP headers to pass to the server in your +HTTP request. The linked list should be a fully valid list of \fBstruct +curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to +create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire +list. 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 +internally used header will get disabled. Thus, using this option you can add +new headers, replace internal headers and remove internal headers. + +\fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options +CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. +.TP +.B 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 HTTP post structs as parameter. The linked list should be a fully valid +list of 'struct HttpPost' structs properly filled in. The best and most +elegant way to do this, is to use \fIcurl_formadd(3)\fP as documented. The +data in this list must remained intact until you close this curl handle again +with \fIcurl_easy_cleanup(3)\fP. +.TP +.B CURLOPT_SSLCERT +Pass a pointer to a zero terminated string as parameter. The string should be +the file name of your certificate. The default format is "PEM" and can be +changed with \fICURLOPT_SSLCERTTYPE\fP. +.TP +.B CURLOPT_SSLCERTTYPE +Pass a pointer to a zero terminated string as parameter. The string should be +the format of your certificate. Supported formats are "PEM" and "DER". (Added +in 7.9.3) +.TP +.B CURLOPT_SSLCERTPASSWD +Pass a pointer to a zero terminated string as parameter. It will be used as +the password required to use the CURLOPT_SSLCERT certificate. If the password +is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can +be used to set your own prompt function. + +\fBNOTE:\fPThis option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and only +cept for backward compatibility. You never needed a pass phrase to load +a certificate but you need one to load your private key. +.TP +.B CURLOPT_SSLKEY +Pass a pointer to a zero terminated string as parameter. The string should be +the file name of your private key. The default format is "PEM" and can be +changed with \fICURLOPT_SSLKEYTYPE\fP. (Added in 7.9.3) +.TP +.B CURLOPT_SSLKEYTYPE +Pass a pointer to a zero terminated string as parameter. The string should be +the format of your private key. Supported formats are "PEM", "DER" and "ENG". +(Added in 7.9.3) + +\fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto +engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to +the engine. You have to set the crypto engine with \fICURLOPT_SSL_ENGINE\fP. +.TP +.B CURLOPT_SSLKEYASSWD +Pass a pointer to a zero terminated string as parameter. It will be used as +the password required to use the \fICURLOPT_SSLKEY\fP private key. If the +password is not supplied, you will be prompted for +it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +(Added in 7.9.3) +.TP +.B CURLOPT_SSL_ENGINE +Pass a pointer to a zero terminated string as parameter. It will be used as +the identifier for the crypto engine you want to use for your private +key. (Added in 7.9.3) + +\fBNOTE:\fPIf the crypto device cannot be loaded, +\fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. +.TP +.B CURLOPT_SSL_ENGINEDEFAULT +Sets the actual crypto engine as the default for (asymetric) crypto +operations. (Added in 7.9.3) + +\fBNOTE:\fPIf the crypto device cannot be set, +\fICURLE_SSL_ENGINE_SETFAILED\fP is returned. +.TP +.B CURLOPT_CRLF +Convert Unix newlines to CRLF newlines on FTP uploads. +.TP +.B CURLOPT_QUOTE +Pass a pointer to a linked list of FTP commands to pass to the server prior to +your ftp request. The linked list should be a fully valid list of 'struct +curl_slist' structs properly filled in. Use \fIcurl_slist_append(3)\fP to +append strings (commands) to the list, and clear the entire list afterwards +with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a +NULL to this option. +.TP +.B CURLOPT_POSTQUOTE +Pass a pointer to a linked list of FTP commands to pass to the 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. +.TP +.B CURLOPT_WRITEHEADER +Pass a pointer to be used to write the header part of the received data to. If +you don't use your own callback to take care of the writing, this must be a +valid FILE *. See also the \fICURLOPT_HEADERFUNCTION\fP option below on how to set a +custom get-all-headers callback. +.TP +.B CURLOPT_HEADERFUNCTION +Function pointer that should match the following prototype: \fIsize_t +function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This +function gets called by libcurl as soon as there is received header data that +needs to be written down. The headers are guaranteed to be written one-by-one +and only complete lines are written. Parsing headers should be easy enough +using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP +multiplied with \fInmemb\fP. The pointer named \fIstream\fP will be the one +you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the +number of bytes actually written or return -1 to signal error to the library +(it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return +code). (Added in libcurl 7.7.2) +.TP +.B CURLOPT_COOKIEFILE +Pass a pointer to a zero terminated string as parameter. It should contain the +name of your file holding cookie data. The cookie data may be in Netscape / +Mozilla cookie data format or just regular HTTP-style headers dumped to a +file. +.TP +.B CURLOPT_SSLVERSION +Pass a long as parameter. Set what version of SSL to attempt to use, 2 or +3. By default, the SSL library will try to solve this by itself although some +servers make this difficult why you at times may have to use this option. +.TP +.B CURLOPT_TIMECONDITION +Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE time value is +treated. You can set this parameter to TIMECOND_IFMODSINCE or +TIMECOND_IFUNMODSINCE. This is a HTTP-only feature. (TBD) +.TP +.B CURLOPT_TIMEVALUE +Pass a long as parameter. This should be the time in seconds since 1 jan 1970, +and the time will be used as specified in CURLOPT_TIMECONDITION or if that +isn't used, it will be TIMECOND_IFMODSINCE by default. +.TP +.B CURLOPT_CUSTOMREQUEST +Pass a pointer to a zero terminated string as parameter. It will be user +instead of GET or HEAD when doing the HTTP request. 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. +.TP +.B CURLOPT_STDERR +Pass a FILE * as parameter. This is the stream to use instead of stderr +internally when reporting errors. +.TP +.B 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 +name. (Added in libcurl 7.3) +.TP +.B CURLOPT_KRB4LEVEL +Pass a char * as parameter. Set the krb4 security level, this also enables +krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or +\&'private'. If the string is set but doesn't match one of these, 'private' +will be used. Set the string to NULL to disable kerberos4. The kerberos +support only works for FTP. (Added in libcurl 7.3) +.TP +.B CURLOPT_PROGRESSFUNCTION +Function pointer that should match the \fIcurl_progress_callback\fP prototype +found in \fI\fP. This function gets called by libcurl instead of +its internal equivalent with a frequent interval during data transfer. +Unknown/unused argument values will be set to zero (like if you only download +data, the upload size will remain 0). Returning a non-zero value from this +callback will cause libcurl to abort the transfer and return +\fICURLE_ABORTED_BY_CALLBACK\fP. +.TP +.B CURLOPT_PROGRESSDATA +Pass a pointer that will be untouched by libcurl and passed as the first +argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. +.TP +.B CURLOPT_SSL_VERIFYPEER +Pass a long that is set to a non-zero value to make curl verify the peer's +certificate. The certificate to verify against must be specified with the +CURLOPT_CAINFO option. (Added in 7.4.2) +.TP +.B CURLOPT_CAINFO +Pass a char * to a zero terminated file naming holding the certificate to +verify the peer with. This only makes sense when used in combination with the +CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2) +.TP +.B CURLOPT_PASSWDFUNCTION +Pass a pointer to a \fIcurl_passwd_callback\fP function that will be called +instead of the internal one if libcurl requests a password. The function must +match this prototype: \fBint my_getpass(void *client, char *prompt, char* +buffer, int buflen );\fP. If set to NULL, it equals to making the function +always fail. If the function returns a non-zero value, it will abort the +operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned. +\fIclient\fP is a generic pointer, see \fICURLOPT_PASSWDDATA\fP. \fIprompt\fP +is a zero-terminated string that is text that prefixes the input request. +\fIbuffer\fP is a pointer to data where the entered password should be stored +and \fIbuflen\fP is the maximum number of bytes that may be written in the +buffer. (Added in 7.4.2) +.TP +.B CURLOPT_PASSWDDATA +Pass a void * to whatever data you want. The passed pointer will be the first +argument sent to the specifed \fICURLOPT_PASSWDFUNCTION\fP function. (Added in +7.4.2) +.TP +.B CURLOPT_FILETIME +Pass a long. If it is a non-zero value, libcurl will attempt to get the +modification date of the remote document in this operation. This requires that +the remote server sends the time or replies to a time querying command. The +\fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument +can be used after a transfer to extract the received time (if any). (Added in +7.5) +.TP +.B CURLOPT_MAXREDIRS +Pass a long. The set number will be the redirection limit. If that many +redirections have been followed, the next redirect will cause an error +(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the +\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. (Added in 7.5) +.TP +.B CURLOPT_MAXCONNECTS +Pass a long. The set number will be the persistant connection cache size. The +set amount will be the maximum amount of simultaneous connections that libcurl +may cache between file transfers. 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. + +\fBNOTE:\fP if you already have performed transfers with this curl handle, +setting a smaller MAXCONNECTS than before may cause open connections to get +closed unnecessarily. (Added in 7.7) +.TP +.B CURLOPT_CLOSEPOLICY +Pass a long. This option sets what policy libcurl should use when the +connection cache is filled and one of the open connections has to be closed to +make room for a new connection. This must be one of the CURLCLOSEPOLICY_* +defines. Use \fICURLCLOSEPOLICY_LEAST_RECENTLY_USED\fP to make libcurl close +the connection that was least recently used, that connection is also least +likely to be capable of re-use. Use \fICURLCLOSEPOLICY_OLDEST\fP to make +libcurl close the oldest connection, the one that was created first among the +ones in the connection cache. The other close policies are not support +yet. (Added in 7.7) +.TP +.B CURLOPT_FRESH_CONNECT +Pass a long. Set to non-zero to make the next transfer use a new (fresh) +connection by force. If the connection cache is full before this connection, +one of the existing connections will be closed as according to the selected or +default policy. This option should be used with caution and only if you +understand what it does. Set this to 0 to have libcurl attempt re-using an +existing connection (default behavior). (Added in 7.7) +.TP +.B CURLOPT_FORBID_REUSE +Pass a long. Set to non-zero 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. +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 +re-use (default behavior). (Added in 7.7) +.TP +.B CURLOPT_RANDOM_FILE +Pass a char * to a zero terminated file name. The file will be used to read +from to seed the random engine for SSL. The more random the specified file is, +the more secure will the SSL connection become. +.TP +.B CURLOPT_EGDSOCKET +Pass a char * to the zero terminated path name to the Entropy Gathering Daemon +socket. It will be used to seed the random engine for SSL. +.TP +.B CURLOPT_CONNECTTIMEOUT +Pass a long. It should contain the maximum time in seconds that you allow the +connection to the server to take. This only limits the connection phase, once +it has connected, this option is of no more use. Set to zero to disable +connection timeout (it will then only timeout on the system's internal +timeouts). See also the \fICURLOPT_TIMEOUT\fP option. + +\fBNOTE:\fP this does not work in unix multi-threaded programs, as it uses +signals. +.TP +.B CURLOPT_HTTPGET +Pass a long. If the long is non-zero, this forces the HTTP request to get back +to GET. Only really usable if POST, PUT or a custom request have been used +previously using the same curl handle. (Added in 7.8.1) +.TP +.B CURLOPT_SSL_VERIFYHOST +Pass a long. Set if we should verify the Common name from the peer certificate +in the SSL handshake, set 1 to check existence, 2 to ensure that it matches +the provided hostname. (Added in 7.8.1) +.TP +.B CURLOPT_COOKIEJAR +Pass a file name as char *, zero terminated. This will make libcurl dump all +internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP +is called. If no cookies are known, no file will be created. Specify "-" to +instead have the cookies written to stdout. +.TP +.B 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 syntactly correct, it +consists of one or more cipher strings separated by colons. Commas or spaces +are also acceptable separators but colons are normally used, \!, \- and \+ can +be used as operators. Valid examples of cipher lists include 'RC4-SHA', +\'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you +compile OpenSSL. + +You'll find more details about cipher lists on this URL: +\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP +.TP +.B CURLOPT_HTTP_VERSION +Pass a long, set to one of the values described below. They force libcurl to +use the specific HTTP versions. This is not sensible to do unless you have a +good reason. +.RS +.TP 5 +.B CURL_HTTP_VERSION_NONE +We don't care about what version the library uses. libcurl will use whatever +it thinks fit. +.TP +.B CURL_HTTP_VERSION_1_0 +Enforce HTTP 1.0 requests. +.TP +.B CURL_HTTP_VERSION_1_1 +Enforce HTTP 1.1 requests. +.RE +.TP +.B CURLOPT_FTP_USE_EPSV +Pass a long. If the value is non-zero, it tells curl to use the EPSV command +when doing passive FTP downloads (which is always does by default). Using EPSV +means that it will first attempt to use EPSV before using PASV, but if you +pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. +.PP +.SH RETURN VALUE +CURLE_OK (zero) means that the option was set properly, non-zero means an +error occurred as \fI\fP defines. +.SH "SEE ALSO" +.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " +.SH BUGS +If you find any bugs, or just have questions, subscribe to one of the mailing +lists and post. We won't bite. + diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 new file mode 100644 index 000000000..0a1706d86 --- /dev/null +++ b/docs/libcurl/curl_escape.3 @@ -0,0 +1,28 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_escape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" +.SH NAME +curl_escape - URL encodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_escape( char *" url ", int "length " );" +.ad +.SH DESCRIPTION +This function will convert the given input string to an URL encoded string and +return that as a new allocated string. All input characters that are not a-z, +A-Z or 0-9 will be converted to their "URL escaped" version. If a sequence of +%NN (where NN is a two-digit hexadecimal number) is found in the string to +encode, that 3-letter combination will be copied to the output unmodifed, +assuming that it is an already encoded piece of data. + +If the 'length' argument is set to 0, curl_escape() will use strlen() on the +input 'url' string to find out the size. + +You must free() the returned string when you're done with it. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.I curl_unescape(), RFC 2396 diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 new file mode 100644 index 000000000..e0e157279 --- /dev/null +++ b/docs/libcurl/curl_formadd.3 @@ -0,0 +1,165 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_formadd 3 "1 Match 2002" "libcurl 7.9.1" "libcurl Manual" +.SH NAME +curl_formadd - add a section to a multipart/formdata HTTP POST +.SH SYNOPSIS +.B #include +.sp +.BI "int curl_formadd(struct HttpPost ** " firstitem, +.BI "struct HttpPost ** " lastitem, " ...);" +.ad +.SH DESCRIPTION +curl_formadd() is used to append sections when building a multipart/formdata +HTTP POST (sometimes refered to as rfc1867-style posts). Append one section at +a time until you've added all the sections you want included and then you pass +the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. +\fIlastitem\fP is set after each call and on repeated invokes it should be +left as set to allow repeated invokes to find the end of the list faster. + +After the \fIlastitem\fP pointer follow the real arguments. (If the following +description confuses you, jump directly to the examples): + +\fBCURLFORM_COPYNAME\fP or \fBCURLFORM_PTRNAME\fP followed by a string is used +for the name of the section. Optionally one may use \fBCURLFORM_NAMELENGTH\fP +to specify the length of the name (allowing null characters within the +name). All options that use the word COPY in their names copy the given +contents, while the ones with PTR in their names simply points to the (static) +data you must make sure remain until curl no longer needs it. + +The four options for providing values are: \fBCURLFORM_COPYCONTENTS\fP, +\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, or \fBCURLFORM_FILECONTENT\fP +followed by a char or void pointer (allowed for PTRCONTENTS). + +\fBCURLFORM_FILECONTENT\fP does a normal post like \fBCURLFORM_COPYCONTENTS\fP +but the actual value is read from the filename given as a string. + +Other arguments may be \fBCURLFORM_CONTENTTYPE\fP if the user wishes to +specify one (for FILE if no type is given the library tries to provide the +correct one; for CONTENTS no Content-Type is sent in this case). + +For \fBCURLFORM_PTRCONTENTS\fP or \fBCURLFORM_COPYNAME\fP the user may also +add \fBCURLFORM_CONTENTSLENGTH\fP followed by the length as a long (if not +given the library will use strlen to determine the length). + +For \fBCURLFORM_FILE\fP the user may send multiple files in one section by +providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename +(and each FILE is allowed to have a CONTENTTYPE). + +Another possibility to send single or multiple files in one section is to use +\fBCURLFORM_ARRAY\fP that gets a struct curl_forms array pointer as its +value. Each structure element has a CURLformoption and a char pointer. For the +options only \fBCURLFORM_FILE\fP, \fBCURLFORM_CONTENTTYPE\fP, and +\fBCURLFORM_END\fP (that is used to determine the end of the array and thus +must be the option of the last and no other element of the curl_forms array) +are allowed. The effect of this parameter is the same as giving multiple +\fBCURLFORM_FILE\fP options possibly with \fBCURLFORM_CONTENTTYPE\fP after or +before each \fBCURLFORM_FILE\fP option. + +Should you need to specify extra headers for the form POST section, use +\fBCURLFORM_CONTENTHEADER\fP. This takes a curl_slist prepared in the usual way +using \fBcurl_slist_append\fP and appends the list of headers to those Curl +automatically generates for \fBCURLFORM_CONTENTTYPE\fP and the content +disposition. The list must exist while the POST occurs, if you free it before +the post completes you may experience problems. + +The last argument in such an array must always be \fBCURLFORM_END\fP. + +The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to +NULL in the first call to this function. All list-data will be allocated by +the function itself. You must call \fIcurl_formfree\fP after the form post has +been done to free the resources again. + +This function will copy all input data except the data pointed to by the +arguments after \fBCURLFORM_PTRNAME\fP and \fBCURLFORM_PTRCONTENTS\fP and keep +its own version of it allocated until you call \fIcurl_formfree\fP. When +you've passed the pointer to \fIcurl_easy_setopt\fP, you must not free the +list until after you've called \fIcurl_easy_cleanup\fP for the curl handle. If +you provide a pointer as an arguments after \fBCURLFORM_PTRNAME\fP or +\fBCURLFORM_PTRCONTENTS\fP you must ensure that the pointer stays valid until +you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP. + +See example below. +.SH RETURN VALUE +Returns non-zero if an error occurs. +.SH EXAMPLE +.nf + + struct HttpPost* post = NULL; + struct HttpPost* last = NULL; + char namebuffer[] = "name buffer"; + long namelength = strlen(namebuffer); + char buffer[] = "test buffer"; + char htmlbuffer[] = "test buffer"; + long htmlbufferlength = strlen(htmlbuffer); + struct curl_forms forms[3]; + char file1[] = "my-face.jpg"; + char file2[] = "your-face.jpg"; + /* add null character into htmlbuffer, to demonstrate that + transfers of buffers containing null characters actually work + */ + htmlbuffer[8] = '\\0'; + + /* Add simple name/content section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", + CURLFORM_COPYCONTENTS, "content", CURLFORM_END); + + /* Add simple name/content/contenttype section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode", + CURLFORM_COPYCONTENTS, "", + CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); + + /* Add name/ptrcontent section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent", + CURLFORM_PTRCONTENTS, buffer, CURLFORM_END); + + /* Add ptrname/ptrcontent section */ + curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer, + CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, + namelength, CURLFORM_END); + + /* Add name/ptrcontent/contenttype section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole", + CURLFORM_PTRCONTENTS, htmlbuffer, + CURLFORM_CONTENTSLENGTH, htmlbufferlength, + CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); + + /* Add simple file section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", + CURLFORM_FILE, "my-face.jpg", CURLFORM_END); + + /* Add file/contenttype section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", + CURLFORM_FILE, "my-face.jpg", + CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END); + + /* Add two file section */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", + CURLFORM_FILE, "my-face.jpg", + CURLFORM_FILE, "your-face.jpg", CURLFORM_END); + + /* Add two file section using CURLFORM_ARRAY */ + forms[0].option = CURLFORM_FILE; + forms[0].value = file1; + forms[1].option = CURLFORM_FILE; + forms[1].value = file2; + forms[2].option = CURLFORM_END; + + /* no option needed for the end marker */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", + CURLFORM_ARRAY, forms, CURLFORM_END); + /* Add the content of a file as a normal post text value */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent", + CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END); + /* Set the form info */ + curl_easy_setopt(curl, CURLOPT_HTTPPOST, post); + +.SH "SEE ALSO" +.BR curl_easy_setopt "(3), " +.BR curl_formparse "(3) [deprecated], " +.BR curl_formfree "(3)" +.SH BUGS +Surely there are some, you tell me! + diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 new file mode 100644 index 000000000..3bf3f999b --- /dev/null +++ b/docs/libcurl/curl_formfree.3 @@ -0,0 +1,27 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_formfree 3 "6 April 2001" "libcurl 7.7.1" "libcurl Manual" +.SH NAME +curl_formfree - free a previously build multipart/formdata HTTP POST chain +.SH SYNOPSIS +.B #include +.sp +.BI "void curl_formfree(struct HttpPost *" form); +.ad +.SH DESCRIPTION +curl_formfree() is used to clean up data previously built/appended with +curl_formadd()/curl_formparse(). This must be called when the data has +been used, which typically means after the curl_easy_perform() has +been called. +.SH RETURN VALUE +None +.SH "SEE ALSO" +.BR curl_formparse "(3) [deprecated], " +.BR curl_formadd "(3) " +.SH BUGS +libcurl 7.7.1 and earlier versions does not allow a NULL pointer to be used as +argument. + + diff --git a/docs/libcurl/curl_formparse.3 b/docs/libcurl/curl_formparse.3 new file mode 100644 index 000000000..bc7accba3 --- /dev/null +++ b/docs/libcurl/curl_formparse.3 @@ -0,0 +1,18 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_formparse 3 "17 Dec 2001" "libcurl 7.9.2" "libcurl Manual" +.SH NAME +curl_formparse - add a section to a multipart/formdata HTTP POST: +deprecated (use curl_formadd instead) +.SH SYNOPSIS +.B #include +.sp +.BI "CURLcode curl_formparse(char * " string, " struct HttpPost ** " firstitem, +.BI "struct HttpPost ** " lastitem ");" +.ad +.SH DESCRIPTION +This has been removed deliberately. The \fBcurl_formadd\fP has been introduced +to replace this function. Do not use this. Convert to the new function +now. curl_formparse() will be removed from a future version of libcurl. diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 new file mode 100644 index 000000000..0141e8c49 --- /dev/null +++ b/docs/libcurl/curl_getdate.3 @@ -0,0 +1,80 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_getdate 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" +.SH NAME +curl_getdate - Convert an date in a ASCII string to number of seconds since +January 1, 1970 +.SH SYNOPSIS +.B #include +.sp +.BI "time_t curl_getdate(char *" datestring ", time_t *"now" ); +.ad +.SH DESCRIPTION +This function returns the number of seconds since January 1st 1970, for the +date and time that the +.I datestring +parameter specifies. The +.I now +parameter is there and should hold the current time to allow the datestring to +specify relative dates/times. Read further in the date string parser section +below. +.SH PARSING DATES AND TIMES +A "date" is a string, possibly empty, containing many items separated by +whitespace. The whitespace may be omitted when no ambiguity arises. The +empty string means the beginning of today (i.e., midnight). Order of the +items is immaterial. A date string may contain many flavors of items: +.TP 0.8i +.B calendar date items +This can be specified in a number of different ways. Including 1970-09-17, 70-9-17, 70-09-17, 9/17/72, 24 September 1972, 24 Sept 72, 24 Sep 72, Sep 24, 1972, 24-sep-72, 24sep72. +The year can also be omitted, for example: 9/17 or "sep 17". +.TP +.B time of the day items +This string specifies the time on a given day. Syntax supported includes: +18:19:0, 18:19, 6:19pm, 18:19-0500 (for specifying the time zone as well). +.TP +.B time zone items +Specifies international time zone. There are a few acronyms supported, but in +general you should instead use the specific realtive time compared to +UTC. Supported formats include: -1200, MST, +0100. +.TP +.B day of the week items +Specifies a day of the week. If this is mentioned alone it means that day of +the week in the future. + +Days of the week may be spelled out in full: `Sunday', `Monday', etc or they +may be abbreviated to their first three letters, optionally followed by a +period. The special abbreviations `Tues' for `Tuesday', `Wednes' for +`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed. + +A number may precede a day of the week item to move forward supplementary +weeks. It is best used in expression like `third monday'. In this context, +`last DAY' or `next DAY' is also acceptable; they move one week before or +after the day that DAY by itself would represent. +.TP +.B relative items +A relative item adjusts a date (or the current date if none) forward or +backward. Example syntax includes: "1 year", "1 year ago", "2 days", "4 +weeks". + +The string `tomorrow' is worth one day in the future (equivalent to `day'), +the string `yesterday' is worth one day in the past (equivalent to `day ago'). +.TP +.B pure numbers +If the decimal number is of the form YYYYMMDD and no other calendar date item +appears before it in the date string, then YYYY is read as the year, MM as the +month number and DD as the day of the month, for the specified calendar date. +.PP +.SH RETURN VALUE +This function returns zero when it fails to parse the date string. Otherwise +it returns the number of seconds as described. +.SH AUTHORS +Originally written by Steven M. Bellovin while at the +University of North Carolina at Chapel Hill. Later tweaked by a couple of +people on Usenet. Completely overhauled by Rich $alz and Jim +Berets in August, 1990. +.SH "SEE ALSO" +.BR +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 new file mode 100644 index 000000000..d10932197 --- /dev/null +++ b/docs/libcurl/curl_getenv.3 @@ -0,0 +1,32 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_getenv 3 "15 August 2001" "libcurl 7.8.1" "libcurl Manual" +.SH NAME +curl_getenv - return value for environment name +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_getenv(const char *" name "); +.ad +.SH DESCRIPTION +curl_getenv() is a portable wrapper for the getenv() function, meant to +emulate its behaviour and provide an identical interface for all operating +systems libcurl builds on (including win32). +.SH RETURN VALUE +If successful, curl_getenv() returns a pointer to the value of the specified +environment. The memory it refers to is malloc()ed why the application must +free() this when the data has completed to serve its purpose. When +.I curl_getenv() +fails 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 +systems. +.SH "SEE ALSO" +.BR getenv "(3C), " +.SH BUGS +Surely there are some, you tell me! + diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3 new file mode 100644 index 000000000..4bc12d8fd --- /dev/null +++ b/docs/libcurl/curl_global_cleanup.3 @@ -0,0 +1,27 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_global_cleanup 3 "28 May 2001" "libcurl 7.8" "libcurl Manual" +.SH NAME +curl_global_cleanup - Global libcurl cleanup +.SH SYNOPSIS +.B #include +.sp +.BI "void curl_global_cleanup(void);" +.ad +.SH DESCRIPTION +curl_global_cleanup must be called once (no matter how many threads or libcurl +sessions that'll be used) by every application that uses libcurl, after all +uses of libcurl is complete. + +This is the opposite of \fIcurl_global_init\fP. + +Not calling this function may result in memory leaks. + +This function was added in libcurl 7.8. +.SH "SEE ALSO" +.BR curl_global_init "(3), " +.SH BUGS +None? + diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 new file mode 100644 index 000000000..ea8419f49 --- /dev/null +++ b/docs/libcurl/curl_global_init.3 @@ -0,0 +1,49 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_global_init 3 "13 Nov 2001" "libcurl 7.9.1" "libcurl Manual" +.SH NAME +curl_global_init - Global libcurl initialisation +.SH SYNOPSIS +.B #include +.sp +.BI "CURLcode curl_global_init(long " flags ");" +.ad +.SH DESCRIPTION +This function should only be called once (no matter how many threads or +libcurl sessions that'll be used) by every application that uses libcurl. + +If this function hasn't been invoked when \fIcurl_easy_init\fP is called, it +will be done automatically by libcurl. + +The flags option is a bit pattern that tells libcurl exact what features to +init, as described below. Set the desired bits by ORing the values together. + +You must however \fBalways\fP use the \fIcurl_global_cleanup\fP function, as +that cannot be called automatically for you by libcurl. + +Calling this function more than once will cause unpredictable results. + +This function was added in libcurl 7.8. +.SH FLAGS +.TP 5 +.B CURL_GLOBAL_ALL +Initialize everything possible. This sets all known bits. +.TP +.B CURL_GLOBAL_SSL +Initialize SSL +.TP +.B CURL_GLOBAL_WIN32 +Initialize the Win32 socket libraries. (added in libcurl 7.8.1) +.TP +.B CURL_GLOBAL_NOTHING +Initialise nothing extra. This sets no bit. +.SH RETURN VALUE +If this function returns non-zero, something went wrong and you cannot use the +other curl functions. +.SH "SEE ALSO" +.BR curl_global_cleanup "(3), " +.SH BUGS +None. + diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 new file mode 100644 index 000000000..839b22536 --- /dev/null +++ b/docs/libcurl/curl_mprintf.3 @@ -0,0 +1,88 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_printf 3 "20 April 2001" "libcurl 7.7.2" "libcurl Manual" +.SH NAME +curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf +curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf, +curl_mvsprintf - formatted output conversion +.SH SYNOPSIS +.B #include +.sp +.BI "int curl_mprintf(const char *" format ", ...);" +.br +.BI "int curl_mfprintf(FILE *" fd ", const char *" format ", ...);" +.br +.BI "int curl_msprintf(char *" buffer ", const char *" format ", ...);" +.br +.BI "int curl_msnprintf(char *" buffer ", size_t " maxlength ", const char *" format ", ...);" +.br +.BI "int curl_mvprintf(const char *" format ", va_list " args ");" +.br +.BI "int curl_mvfprintf(FILE *" fd ", const char *" format ", va_list " args ");" +.br +.BI "int curl_mvsprintf(char *" buffer ", const char *" format ", va_list " args ");" +.br +.BI "int curl_mvsnprintf(char *" buffer ", size_t " maxlength ", const char *" format ", va_list " args ");" +.br +.BI "char *curl_maprintf(const char *" format ", ...);" +.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 +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. + +See this table for notable exceptions. +.RS +.TP +.B curl_mprintf() +Normal printf() clone. +.TP +.B curl_mfprintf() +Normal fprinf() clone. +.TP +.B curl_msprintf() +Normal sprintf() clone. +.TP +.B curl_msnprintf() +snprintf() clone. Many systems don't have this. It is just like \fBsprintf\fP +but with an extra argument after the buffer that specifies the length of the +target buffer. +.TP +.B curl_mvprintf() +Normal vprintf() clone. +.TP +.B curl_mvfprintf() +Normal vfprintf() clone. +.TP +.B curl_mvsprintf() +Normal vsprintf() clone. +.TP +.B curl_mvsnprintf() +vsnprintf() clone. Many systems don't have this. It is just like +\fBvsprintf\fP but with an extra argument after the buffer that specifies the +length of the target buffer. +.TP +.B curl_maprintf() +Like printf() but returns the output string as a malloc()ed string. The +returned string must be free()ed by the receiver. +.TP +.B curl_mvaprintf() +Like curl_maprintf() but takes a va_list pointer argument instead of a +variable amount of arguments. +.RE + +To easily use all these cloned functions instead of the normal ones, #define +_MPRINTF_REPLACE before you include the file. Then all the +normal names like printf, fprintf, sprintf etc will use the curl-functions +instead. +.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. + +All other functions return the number of character they actually outputed. +.SH "SEE ALSO" +.BR printf "(3), " sprintf "(3), " fprintf "(3), " vprintf "(3) " diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 new file mode 100644 index 000000000..b8b274da9 --- /dev/null +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -0,0 +1,17 @@ +.\" $Id$ +.\" +.TH curl_multi_add_handle 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_add_handle - add an easy handle to a multi session +.SH SYNOPSIS +#include + +CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); +.ad +.SH DESCRIPTION +Adds a standard easy handle to the multi stack. This will make this multi +handle control the specified easy handle. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 new file mode 100644 index 000000000..d7830e7ac --- /dev/null +++ b/docs/libcurl/curl_multi_cleanup.3 @@ -0,0 +1,18 @@ +.\" $Id$ +.\" +.TH curl_multi_cleanup 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_cleanup - close down a multi session +.SH SYNOPSIS +.B #include +.sp +.BI "CURLMcode curl_multi_cleanup( CURLM *multi_handle );" +.ad +.SH DESCRIPTION +Cleans up and removes a whole multi stack. It does not free or touch any +individual easy handles in any way - they still need to be closed +individually, using the usual curl_easy_cleanup() way. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_init "(3)," curl_easy_cleanup "(3)," curl_easy_init "(3)" diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 new file mode 100644 index 000000000..48aadad8b --- /dev/null +++ b/docs/libcurl/curl_multi_fdset.3 @@ -0,0 +1,23 @@ +.\" $Id$ +.\" +.TH curl_multi_fdset 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_fdset - add an easy handle to a multi session +.SH SYNOPSIS +#include + +CURLMcode curl_multi_fdset(CURLM *multi_handle, + fd_set *read_fd_set, + fd_set *write_fd_set, + fd_set *exc_fd_set, + int *max_fd); +.ad +.SH DESCRIPTION +This function extracts file descriptor information from a given multi_handle. +libcurl returns its fd_set sets. The application can use these to select() or +poll() on. The curl_multi_perform() function should be called as soon as one +of them are ready to be read from or written to. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 new file mode 100644 index 000000000..8fcaeb576 --- /dev/null +++ b/docs/libcurl/curl_multi_info_read.3 @@ -0,0 +1,35 @@ +.\" $Id$ +.\" +.TH curl_multi_info_read 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_info_read - read multi stack informationals +.SH SYNOPSIS +#include + +CURLMsg *curl_multi_info_read( CURLM *multi_handle, + int *msgs_in_queue); +.ad +.SH DESCRIPTION +Ask the multi handle if there's any messages/informationals from the +individual transfers. Messages include informationals such as an error code +from the transfer or just the fact that a transfer is completed. More details +on these should be written down as well. + +Repeated calls to this function will return a new struct each time, until a +special "end of msgs" struct is returned as a signal that there is no more to +get at this point. The integer pointed to with \fImsgs_in_queue\fP will +contain the number of remaining messages after this function was called. + +The data the returned pointer points to will not survive calling +curl_multi_cleanup(). + +The 'CURLMsg' struct is very simple and only contain very basic informations. +If more involved information is wanted, the particular "easy handle" in +present in that struct and can thus be used in subsequent regular +curl_easy_getinfo() calls (or similar). +.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 +read) in the integer the second argument points to. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)," curl_multi_perform "(3)" diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 new file mode 100644 index 000000000..36336b1ff --- /dev/null +++ b/docs/libcurl/curl_multi_init.3 @@ -0,0 +1,21 @@ +.\" $Id$ +.\" +.TH curl_multi_init 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_init - Start a multi session +.SH SYNOPSIS +.B #include +.sp +.BI "CURLM *curl_multi_init( );" +.ad +.SH DESCRIPTION +This function returns a CURLM handle to be used as input to all the other +multi-functions. This init call MUST have a corresponding call to +\fIcurl_multi_cleanup\fP when the operation is complete. +.SH RETURN VALUE +If this function returns NULL, something went wrong and you cannot use the +other curl functions. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_global_init "(3)," curl_easy_init "(3)" +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 new file mode 100644 index 000000000..dae41ace8 --- /dev/null +++ b/docs/libcurl/curl_multi_perform.3 @@ -0,0 +1,30 @@ +.\" $Id$ +.\" +.TH curl_multi_perform 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_perform - add an easy handle to a multi session +.SH SYNOPSIS +#include + +CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles); +.ad +.SH DESCRIPTION +When the app thinks there's data available for the multi_handle, it should +call this function to read/write whatever there is to read or write right +now. curl_multi_perform() returns as soon as the reads/writes are done. This +function does not require that there actually is any data available for +reading or that data can be written, it can be called just in case. It will +write the number of handles that still transfer data in the second argument's +integer-pointer. +.SH "RETURN VALUE" +CURLMcode type, general libcurl multi interface error code. + +NOTE that this only returns errors etc regarding the whole multi stack. There +might still have occurred problems on invidual transfers even when this +function returns OK. +.SH "TYPICAL USAGE" +Most application will use \fIcurl_multi_fdset\fP to get the multi_handle's +file descriptors, then it'll wait for action on them using select() and as +soon as one or more of them are ready, \fIcurl_multi_perform\fP gets called. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 new file mode 100644 index 000000000..11cc6c587 --- /dev/null +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -0,0 +1,17 @@ +.\" $Id$ +.\" +.TH curl_multi_remove_handle 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_remove_handle - add an easy handle to a multi session +.SH SYNOPSIS +#include + +CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle); +.ad +.SH DESCRIPTION +Removes a given easy_handle from the multi_handle. This will make the +specified easy handle be removed from this multi handle's control. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 new file mode 100644 index 000000000..4737b989b --- /dev/null +++ b/docs/libcurl/curl_slist_append.3 @@ -0,0 +1,29 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_slist_append 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" +.SH NAME +curl_slist_append - add a string to an slist +.SH SYNOPSIS +.B #include +.sp +.BI "struct curl_slist *curl_slist_append(struct curl_slist *" list, +.BI "const char * "string ");" +.ad +.SH DESCRIPTION +curl_slist_append() appends a specified string to a linked list of +strings. The existing +.I list +should be passed as the first argument while the new list is returned from +this function. The specified +.I string +has been appended when this function returns. +.SH RETURN VALUE +A null pointer is returned if anything went wrong, otherwise the new list +pointer is returned. +.SH "SEE ALSO" +.BR curl_slist_free_all "(3), " +.SH BUGS +Surely there are some, you tell me! + diff --git a/docs/libcurl/curl_slist_free_all.3 b/docs/libcurl/curl_slist_free_all.3 new file mode 100644 index 000000000..f471a8922 --- /dev/null +++ b/docs/libcurl/curl_slist_free_all.3 @@ -0,0 +1,22 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_slist_free_all 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" +.SH NAME +curl_slist_free_all - free an entire curl_slist list +.SH SYNOPSIS +.B #include +.sp +.BI "void curl_slist_free_all(struct curl_slist *" list); +.ad +.SH DESCRIPTION +curl_slist_free_all() removes all traces of a previously built curl_slist +linked list. +.SH RETURN VALUE +Nothing. +.SH "SEE ALSO" +.BR curl_slist_append "(3), " +.SH BUGS +Surely there are some, you tell me! + diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 new file mode 100644 index 000000000..a35a52dfd --- /dev/null +++ b/docs/libcurl/curl_strequal.3 @@ -0,0 +1,30 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_strequal 3 "20 April 2001" "libcurl 7.7.2" "libcurl Manual" +.SH NAME +curl_strequal, curl_strnequal - case insensitive string comparisons +.SH SYNOPSIS +.B #include +.sp +.BI "int curl_strequal(char *" str1 ", char *" str2 ");" +.sp +.BI "int curl_strenqual(char *" str1 ", char *" str2 ", size_t " len ");" +.SH DESCRIPTION +The +.B curl_strequal() +function compares the two strings \fIstr1\fP and \fIstr2\fP, ignoring the case +of the characters. It returns a non-zero (TRUE) integer if the strings are +identical. +.sp +The \fBcurl_strnequal()\fP function is similar, except it only compares the +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. +.SH RETURN VALUE +Non-zero if the strings are identical. Zero if they're not. +.SH "SEE ALSO" +.BR strcmp "(3), " strcasecmp "(3)" diff --git a/docs/libcurl/curl_strnequal.3 b/docs/libcurl/curl_strnequal.3 new file mode 100644 index 000000000..c7d91cca8 --- /dev/null +++ b/docs/libcurl/curl_strnequal.3 @@ -0,0 +1 @@ +.so curl_strequal.3 diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 new file mode 100644 index 000000000..0e84a192a --- /dev/null +++ b/docs/libcurl/curl_unescape.3 @@ -0,0 +1,27 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_unescape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" +.SH NAME +curl_unescape - URL decodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_unescape( char *" url ", int "length " );" +.ad +.SH DESCRIPTION +This function will convert the given URL encoded input string to a "plain +string" and return that as a new allocated string. All input characters that +are URL encoded (%XX where XX is a two-digit hexadecimal number, or +) will be +converted to their plain text versions (up to a ? letter, no letters to the +right of a ? letter will be converted). + +If the 'length' argument is set to 0, curl_unescape() will use strlen() on the +input 'url' string to find out the size. + +You must free() the returned string when you're done with it. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.I curl_escape(), RFC 2396 diff --git a/docs/libcurl/curl_version.3 b/docs/libcurl/curl_version.3 new file mode 100644 index 000000000..5ddaa03f5 --- /dev/null +++ b/docs/libcurl/curl_version.3 @@ -0,0 +1,27 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_version 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" +.SH NAME +curl_version - returns the libcurl version string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_version( );" +.ad +.SH DESCRIPTION +Returns a human readable string with the version number of libcurl and some of +its important components (like OpenSSL version). + +Note: this returns the actual running lib's version, you might have installed +a newer lib's include files in your system which may turn your LIBCURL_VERSION +#define value to differ from this result. +.SH RETURN VALUE +A pointer to a zero terminated string. +.SH "SEE ALSO" +The +.I LIBCURL_VERSION +#define in +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html new file mode 100644 index 000000000..b3300013b --- /dev/null +++ b/docs/libcurl/index.html @@ -0,0 +1,38 @@ +HTML> + + +Index to Curl documentation + + + +

Index to Curl documentation

+ +

Programs

+

curl-config.html +

curl.html + +

Library routines

+

libcurl.html +

curl_easy_cleanup.html +

curl_easy_duphandle.html +

curl_easy_getinfo.html +

curl_easy_init.html +

curl_easy_perform.html +

curl_easy_setopt.html +

curl_escape.html +

curl_formadd.html +

curl_formfree.html +

curl_formparse.html +

curl_getdate.html +

curl_getenv.html +

curl_global_cleanup.html +

curl_global_init.html +

curl_mprintf.html +

curl_slist_append.html +

curl_slist_free_all.html +

curl_strequal.html +

curl_strnequal.html +

curl_unescape.html +

curl_version.html + + diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 new file mode 100644 index 000000000..16af69845 --- /dev/null +++ b/docs/libcurl/libcurl.3 @@ -0,0 +1,132 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH libcurl 5 "14 August 2001" "libcurl 7.8.1" "libcurl overview" +.SH NAME +libcurl \- client-side URL transfers +.SH DESCRIPTION +This is an overview on how to use libcurl in your C programs. There are +specific man pages for each function mentioned in here. There's also the +libcurl-the-guide document for a complete tutorial to programming with +libcurl. + +libcurl can also be used directly from within your Java, PHP, Perl, Ruby or +Tcl programs as well, look elsewhere for documentation on this! + +All applications that use libcurl should call \fIcurl_global_init()\fP exactly +once before any libcurl function can be used. After all usage of libcurl is +complete, it \fBmust\fP call \fIcurl_global_cleanup()\fP. In between those two +calls, you can use libcurl as described below. + +When using libcurl you init your session and get a handle, which you use as +input to the following interface functions you use. Use \fIcurl_easy_init()\fP +to get the handle. + +You continue by setting all the options you want in the upcoming transfer, +most important among them is the URL itself (you can't transfer anything +without a specified URL as you may have figured out yourself). You might want +to set some callbacks as well that will be called from the library when data +is available etc. \fIcurl_easy_setopt()\fP is there for this. + +When all is setup, you tell libcurl to perform the transfer using +\fIcurl_easy_perform()\fP. It will then do the entire operation and won't +return until it is done (successfully or not). + +After the transfer has been made, you can set new options and make another +transfer, or if you're done, cleanup the session by calling +\fIcurl_easy_cleanup()\fP. If you want persistant connections, you don't +cleanup immediately, but instead run ahead and perform other transfers using +the same handle. See the chapter below for Persistant Connections. + +There is also a series of other helpful functions to use. They are: + +.RS +.TP 10 +.B curl_version() +displays the libcurl version +.TP +.B curl_getdate() +converts a date string to time_t +.TP +.B curl_getenv() +portable environment variable reader +.TP +.B curl_easy_getinfo() +get information about a performed transfer +.TP +.B curl_formadd() +helps building a HTTP form POST +.TP +.B curl_formfree() +free a list built with curl_formparse()/curl_formadd() +.TP +.B curl_slist_append() +builds a linked list +.TP +.B curl_slist_free_all() +frees a whole curl_slist +.TP +.B curl_mprintf() +portable printf() functions +.TP +.B curl_strequal() +portable case insensitive string comparisons +.RE + +.SH "LINKING WITH LIBCURL" +Starting with 7.7.2 (on unix-like machines), there's a tool named curl-config +that gets installed with the rest of the curl stuff when 'make install' is +performed. + +curl-config is added to make it easier for applications to link with libcurl +and developers to learn about libcurl and how to use it. + +Run 'curl-config --libs' to get the (additional) linker options you need to +link with the particular version of libcurl you've installed. + +For details, see the curl-config.1 man page. +.SH "LIBCURL SYMBOL NAMES" +All public functions in the libcurl interface are prefixed with 'curl_' (with +a lowercase c). You can find other functions in the library source code, but +other prefixes indicate the functions are private and may change without +further notice in the next release. + +Only use documented functions and functionality! +.SH "PORTABILITY" +libcurl works +.B exactly +the same, on any of the platforms it compiles and builds on. + +There's only one caution, and that is the win32 platform that may(*) require +you to init the winsock stuff before you use the libcurl functions. Details on +this are noted on the curl_easy_init() man page. + +(*) = it appears as if users of the cygwin environment get this done +automatically, also libcurl 7.8.1 and later can handle this for you. +.SH "THREADS" +Never ever call curl-functions simultaneously using the same handle from +several threads. libcurl is thread-safe and can be used in any number of +threads, but you must use separate curl handles if you want to use libcurl in +more than one thread simultaneously. +.SH "PERSISTANT CONNECTIONS" +With libcurl 7.7, persistant connections were added. Persistant connections +means that libcurl can re-use the same connection for several transfers, if +the conditions are right. + +libcurl will *always* attempt to use persistant connections. Whenever you use +curl_easy_perform(), libcurl will attempt to use an existing connection to do +the transfer, and if none exists it'll open a new one that will be subject +for re-use on a possible following call to curl_easy_perform(). + +To allow libcurl to take full advantage of persistant connections, you should +do as many of your file transfers as possible using the same curl +handle. When you call curl_easy_cleanup(), all the possibly open connections +held by libcurl will be closed and forgotten. + +Note that the options set with curl_easy_setopt() will be used in on every +repeat curl_easy_perform() call +.SH "COMPATIBILITY WITH OLDER LIBCURLS" +Repeated curl_easy_perform() calls on the same handle were not supported in +pre-7.7 versions, and caused confusion and undefined behaviour. + -- cgit v1.2.1 From 4d7b1512c1642f7ca598c3a401894aeac812ffbe Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2002 13:06:46 +0000 Subject: mention 'easy handle' and not just handle, there will soon be other handles to keep track of too --- docs/libcurl/curl_easy_init.3 | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index cb695bb05..83f361f4b 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -2,20 +2,19 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_init 3 "1 March 2002" "libcurl 7.8.1" "libcurl Manual" +.TH curl_easy_init 3 "4 March 2002" "libcurl 7.8.1" "libcurl Manual" .SH NAME -curl_easy_init - Start a libcurl session +curl_easy_init - Start a libcurl easy session .SH SYNOPSIS .B #include .sp .BI "CURL *curl_easy_init( );" .ad .SH DESCRIPTION -This function must be the first function to call, and it returns a CURL handle -that you shall use as input to the other easy-functions. The init calls +This function must be the first function to call, and it returns a CURL easy +handle that you must use as input to other easy-functions. curl_easy_init intializes curl and this call MUST have a corresponding call to -.I curl_easy_cleanup -when the operation is complete. +\fIcurl_easy_cleanup\fP when the operation is complete. .SH RETURN VALUE If this function returns NULL, something went wrong and you cannot use the -- cgit v1.2.1 From d6c9a72e1584d6d3a967caf587a9f1a8fa1a4bd2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2002 13:10:15 +0000 Subject: explicitly mention easy handle --- docs/libcurl/curl_easy_cleanup.3 | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index 267c2f4f4..eea1df27c 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -2,28 +2,24 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_cleanup 3 "5 March 2001" "libcurl 7.7" "libcurl Manual" +.TH curl_easy_cleanup 3 "4 March 2002" "libcurl 7.7" "libcurl Manual" .SH NAME -curl_easy_cleanup - End a libcurl session +curl_easy_cleanup - End a libcurl easy session .SH SYNOPSIS .B #include .sp .BI "void curl_easy_cleanup(CURL *" handle ");" .ad .SH DESCRIPTION -This function must be the last function to call for a curl session. It is the -opposite of the -.I curl_easy_init -function and must be called with the same -.I handle -as input as the curl_easy_init call returned. +This function must be the last function to call for an easy session. It is the +opposite of the \fIcurl_easy_init\fP function and must be called with the same +\fIhandle\fP as input that the curl_easy_init call returned. -This will effectively close all connections libcurl has been used and possibly +This will effectively close all connections this handle has used and possibly has kept open until now. Don't call this function if you intend to transfer -more files (libcurl 7.7 or later). +more files. .SH RETURN VALUE None .SH "SEE ALSO" .BR curl_easy_init "(3), " -.SH BUGS -Surely there are some, you tell me! + -- cgit v1.2.1 From d89dbe5bd625ead10d2ec544e0c2374449b33a55 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Mar 2002 07:44:49 +0000 Subject: we don't skip what looks like already escaped strings, that was fixed ages ago --- docs/libcurl/curl_escape.3 | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 0a1706d86..ba81303c5 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_escape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" +.TH curl_escape 3 "6 March 2002" "libcurl 7.9" "libcurl Manual" .SH NAME curl_escape - URL encodes the given string .SH SYNOPSIS @@ -13,10 +13,8 @@ curl_escape - URL encodes the given string .SH DESCRIPTION This function will convert the given input string to an URL encoded string and return that as a new allocated string. All input characters that are not a-z, -A-Z or 0-9 will be converted to their "URL escaped" version. If a sequence of -%NN (where NN is a two-digit hexadecimal number) is found in the string to -encode, that 3-letter combination will be copied to the output unmodifed, -assuming that it is an already encoded piece of data. +A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a +two-digit hexadecimal number). If the 'length' argument is set to 0, curl_escape() will use strlen() on the input 'url' string to find out the size. -- cgit v1.2.1 From f752098ba56fb2d9934307156046837261a2d0f9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Mar 2002 15:01:45 +0000 Subject: when removed, an easy handle can be curl_easy_perform()ed again --- docs/libcurl/curl_multi_remove_handle.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 index 11cc6c587..a8d93eef4 100644 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_remove_handle 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.TH curl_multi_remove_handle 3 "6 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_remove_handle - add an easy handle to a multi session .SH SYNOPSIS @@ -11,6 +11,9 @@ CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle); .SH DESCRIPTION Removes a given easy_handle from the multi_handle. This will make the specified easy handle be removed from this multi handle's control. + +When the easy handle has been removed from a multi stack, it is again +perfectly legal to invoke \fIcurl_easy_perform()\fP on this easy handle. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" -- cgit v1.2.1 From c2d4fd876c77132caf593e397db615eb12266c7d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Mar 2002 08:50:18 +0000 Subject: 7.9.5 commit --- docs/libcurl/curl_multi_add_handle.3 | 5 ++++- docs/libcurl/curl_multi_init.3 | 3 ++- 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index b8b274da9..c2077a048 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_add_handle 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.TH curl_multi_add_handle 3 "4 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_add_handle - add an easy handle to a multi session .SH SYNOPSIS @@ -11,6 +11,9 @@ CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); .SH DESCRIPTION Adds a standard easy handle to the multi stack. This will make this multi handle control the specified easy handle. + +When an easy handle has been added to a multi stack, you can not and you must +not use curl_easy_perform() on that handle! .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index 36336b1ff..e3619d5c5 100644 --- a/docs/libcurl/curl_multi_init.3 +++ b/docs/libcurl/curl_multi_init.3 @@ -10,7 +10,8 @@ curl_multi_init - Start a multi session .ad .SH DESCRIPTION This function returns a CURLM handle to be used as input to all the other -multi-functions. This init call MUST have a corresponding call to +multi-functions, sometimes refered to as a multi handle on some places in the +documentation. This init call MUST have a corresponding call to \fIcurl_multi_cleanup\fP when the operation is complete. .SH RETURN VALUE If this function returns NULL, something went wrong and you cannot use the -- cgit v1.2.1 From 2c0d9ad64cb492761fc76e90be767cbc18a85abd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 17 Mar 2002 08:28:51 +0000 Subject: clarified that it is only the + letter that isn't converted on the right side of a ? letter --- docs/libcurl/curl_unescape.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index 0e84a192a..756ab45ac 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -14,7 +14,7 @@ curl_unescape - URL decodes the given string This function will convert the given URL encoded input string to a "plain string" and return that as a new allocated string. All input characters that are URL encoded (%XX where XX is a two-digit hexadecimal number, or +) will be -converted to their plain text versions (up to a ? letter, no letters to the +converted to their plain text versions (up to a ? letter, no + letters to the right of a ? letter will be converted). If the 'length' argument is set to 0, curl_unescape() will use strlen() on the -- cgit v1.2.1 From 61a84abe2abe35d01eeb399596df23f266e43f8a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 18 Mar 2002 08:53:21 +0000 Subject: WRITEFUNCTION correction --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4067cec5e..f1bd48ad1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -49,12 +49,12 @@ crashes. .B CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This -function gets called by libcurl as soon as there is data available to pass -available that needs to be saved. The size of the data pointed to by \fIptr\fP -is \fIsize\fP multiplied with \fInmemb\fP. Return the number of bytes -actually taken care of. If that amount differs from the amount passed to your -function, it'll signal an error to the library and it will abort the transfer -and return \fICURLE_WRITE_ERROR\fP. +function gets called by libcurl as soon as there is data available that needs +to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP +multiplied with \fInmemb\fP. Return the number of bytes actually taken care +of. If that amount differs from the amount passed to your function, it'll +signal an error to the library and it will abort the transfer and return +\fICURLE_WRITE_ERROR\fP. Set the \fIstream\fP argument with the \fBCURLOPT_FILE\fP option. -- cgit v1.2.1 From b8a0fb1dfe314b207351f8b4501a57c6bf982020 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Mar 2002 09:31:05 +0000 Subject: point out that this describes the easy interface and also make a more general statement about language bindings --- docs/libcurl/libcurl.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 16af69845..8ecf1b2c3 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl 5 "14 August 2001" "libcurl 7.8.1" "libcurl overview" +.TH libcurl 5 "19 March 2001" "libcurl 7.8.1" "libcurl overview" .SH NAME libcurl \- client-side URL transfers .SH DESCRIPTION @@ -11,17 +11,17 @@ specific man pages for each function mentioned in here. There's also the libcurl-the-guide document for a complete tutorial to programming with libcurl. -libcurl can also be used directly from within your Java, PHP, Perl, Ruby or -Tcl programs as well, look elsewhere for documentation on this! +There are a dozen custom bindings that bring libcurl access to your favourite +language. Look elsewhere for documentation on those. All applications that use libcurl should call \fIcurl_global_init()\fP exactly once before any libcurl function can be used. After all usage of libcurl is complete, it \fBmust\fP call \fIcurl_global_cleanup()\fP. In between those two calls, you can use libcurl as described below. -When using libcurl you init your session and get a handle, which you use as -input to the following interface functions you use. Use \fIcurl_easy_init()\fP -to get the handle. +When using libcurl's "easy" interface you init your session and get a handle, +which you use as input to the easy interface functions you use. Use +\fIcurl_easy_init()\fP to get the handle. You continue by setting all the options you want in the upcoming transfer, most important among them is the URL itself (you can't transfer anything -- cgit v1.2.1 From 171c4fd49fe1f90cf55024ff8d81e27f1709f17b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Mar 2002 09:41:06 +0000 Subject: removed text that really belongs to very old libcurls that are no longer being used widely --- docs/libcurl/libcurl.3 | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 8ecf1b2c3..e84e693b4 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl 5 "19 March 2001" "libcurl 7.8.1" "libcurl overview" +.TH libcurl 5 "19 March 2002" "libcurl 7.8.1" "libcurl overview" .SH NAME libcurl \- client-side URL transfers .SH DESCRIPTION @@ -97,13 +97,6 @@ Only use documented functions and functionality! libcurl works .B exactly the same, on any of the platforms it compiles and builds on. - -There's only one caution, and that is the win32 platform that may(*) require -you to init the winsock stuff before you use the libcurl functions. Details on -this are noted on the curl_easy_init() man page. - -(*) = it appears as if users of the cygwin environment get this done -automatically, also libcurl 7.8.1 and later can handle this for you. .SH "THREADS" Never ever call curl-functions simultaneously using the same handle from several threads. libcurl is thread-safe and can be used in any number of @@ -126,7 +119,3 @@ held by libcurl will be closed and forgotten. Note that the options set with curl_easy_setopt() will be used in on every repeat curl_easy_perform() call -.SH "COMPATIBILITY WITH OLDER LIBCURLS" -Repeated curl_easy_perform() calls on the same handle were not supported in -pre-7.7 versions, and caused confusion and undefined behaviour. - -- cgit v1.2.1 From 340caf5da3344d8c603cd8ff33f569c6279a34dc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Mar 2002 10:16:12 +0000 Subject: multi interface overview and description --- docs/libcurl/libcurl-multi.3 | 80 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 docs/libcurl/libcurl-multi.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 new file mode 100644 index 000000000..a07736de2 --- /dev/null +++ b/docs/libcurl/libcurl-multi.3 @@ -0,0 +1,80 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH libcurl-multi 5 "19 March 2001" "libcurl 7.9.5" "libcurl multi interface" +.SH NAME +libcurl-multi \- how to use the multi interface +.SH DESCRIPTION +This is an overview on how to use the libcurl multi interface in your C +programs. There are specific man pages for each function mentioned in +here. There's also the libcurl-the-guide document for a complete tutorial to +programming with libcurl and the \fIlibcurl(3)\fP man page for an overview of +the libcurl easy interface. + +All functions in the multi interface are prefixed with curl_multi. +.SH "OBJECTIVES" +The multi interface introduces several new abilities that the easy interface +refuses to offer. They are mainly: + +1. Enable a "pull" interface. The application that uses libcurl decides where +and when to ask libcurl to get/send data. + +2. Enable multiple simultaneous transfers in the same thread without making it +complicated for the application. + +3. Enable the application to select() on its own file descriptors and curl's +file descriptors simultaneous easily. +.SH "ONE MULTI HANDLE MANY EASY HANDLES" +To use the multi interface, you must first create a 'multi handle' with +\fIcurl_multi_init\fP. This handle is then used as input to all further +curl_multi_* functions. + +Each single transfer is built up with an easy handle. You must create them, +and setup the appropriate options for each easy handle, as outlined in the +\fIlibcurl(3)\fP man page. + +When the easy handle is setup for a transfer, then instead of using +\fIcurl_easy_perform\fP (as when using the easy interface for transfers), you +should instead add the easy handle to the multi handle using +\fIcurl_easy_add_handl\fP. The multi handle is sometimes referred to as a +\'multi stack\' because of the fact that it may hold a large amount of easy +handles. + +Should you change your mind, the easy handle is again removed from the multi +stack using \fIcurl_multi_remove_handle\fP. Once removed from the multi +handle, you can again use other easy interface functions like +curl_easy_perform or whatever you think is necessary. + +Adding the easy handles to the multi handle does not start any +transfer. Remember that one of the main ideas with this interface is to let +your application drive. You drive the transfers by invoking +\fIcurl_multi_perform\fP. libcurl will then transfer data if there is anything +available to transfer. It'll use the callbacks and everything else you have +setup in the individual easy handles. It'll transfer data on all current +transfers in the multi stack that are ready to transfer anything. It may be +all, it may be none. + +Your application can acquire knowledge from libcurl when it would like to get +invoked to transfer data, so that you don't have to busy-loop and call that +\fIcurl_multi_perform\fP like a mad man! \fIcurl_multi_fdset\fP offers an +interface using which you can extract fd_sets from libcurl to use in select() +or poll() calls in order to get to know when the transfers in the multi stack +might need attention. This also makes it very easy for your program to wait +for input on your own private file descriptors at the same time or perhaps +timeout every now and then, should you want that. + +\fIcurl_multi_perform\fP stores the number of still running transfers in one +of its input arguments, and by reading that you can figure out when all the +transfers in the multi handles are done. 'done' does not mean successful. One +or more of the transfers may have failed. + +To get information about completed transfers, to figure out success or not and +similar, \fIcurl_multi_info_read\fP should be called. It can return a message +about a current or previous transfer. Repeated invokes of the function get +more messages until the message queue is empty. + +When all transfers in the multi stack are done, cleanup the multi handle with +\fIcurl_multi_cleanup\fP. Be careful and please note that you \fBMUST\fP +invoke separate \fIcurl_easy_cleanup\fP calls on every single easy handle to +clean them up properly. -- cgit v1.2.1 From 286fb6f64538333037fe91e40075a027ee38e0ef Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Mar 2002 10:19:56 +0000 Subject: added the multi functions man pages --- docs/libcurl/Makefile.am | 18 +++++++++++++++++- docs/libcurl/index.html | 10 ++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index c6d6c9d46..cfd1a1fe2 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -26,7 +26,15 @@ man_MANS = \ curl_mprintf.3 \ curl_global_init.3 \ curl_global_cleanup.3 \ - libcurl.3 + libcurl.3 \ + curl_multi_add_handle.3 \ + curl_multi_cleanup.3 \ + curl_multi_fdset.3 \ + curl_multi_info_read.3 \ + curl_multi_init.3 \ + curl_multi_perform.3 \ + curl_multi_remove_handle.3 \ + libcurl-multi.3 HTMLPAGES = \ curl_easy_cleanup.html \ @@ -51,6 +59,14 @@ HTMLPAGES = \ curl_global_init.html \ curl_global_cleanup.html \ libcurl.html \ + curl_multi_add_handle.html \ + curl_multi_cleanup.html \ + curl_multi_fdset.html \ + curl_multi_info_read.html \ + curl_multi_init.html \ + curl_multi_perform.html \ + curl_multi_remove_handle.html \ + libcurl-multi.html \ index.html EXTRA_DIST = $(man_MANS) $(HTMLPAGES) diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index b3300013b..1d2d8df19 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -34,5 +34,15 @@ HTML>

curl_strnequal.html

curl_unescape.html

curl_version.html +

+

curl_multi_add_handle.html +

curl_multi_cleanup.html +

curl_multi_fdset.html +

curl_multi_info_read.html +

curl_multi_init.html +

curl_multi_perform.html +

curl_multi_remove_handle.html +

libcurl-multi.html + -- cgit v1.2.1 From eb0f72781833542689076253da0a74e1991e6242 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 20 Mar 2002 10:11:50 +0000 Subject: newcomer notice added --- docs/libcurl/libcurl-multi.3 | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index a07736de2..0dc3f6216 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl-multi 5 "19 March 2001" "libcurl 7.9.5" "libcurl multi interface" +.TH libcurl-multi 5 "20 March 2001" "libcurl 7.9.5" "libcurl multi interface" .SH NAME libcurl-multi \- how to use the multi interface .SH DESCRIPTION @@ -13,6 +13,11 @@ programming with libcurl and the \fIlibcurl(3)\fP man page for an overview of the libcurl easy interface. All functions in the multi interface are prefixed with curl_multi. +.SH "PLEASE NOTICE" +The multi interface is a rather new member of the libcurl family. It has not +yet been very widely used. It may still be a few more bugs lurking in there +than we are used to. That said, it might also just work in every aspect you +try it. Please report all bugs and oddities you see. .SH "OBJECTIVES" The multi interface introduces several new abilities that the easy interface refuses to offer. They are mainly: -- cgit v1.2.1 From 38ed8938d865033affed20ed0dbcf47251403e12 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Apr 2002 13:29:05 +0000 Subject: Added DNS cache control options --- docs/libcurl/curl_easy_setopt.3 | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f1bd48ad1..2027977e1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "10 Dec 2001" "libcurl 7.9.2" "libcurl Manual" +.TH curl_easy_setopt 3 "2 Apr 2002" "libcurl 7.9.2" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS @@ -615,6 +615,17 @@ Pass a long. If the value is non-zero, it tells curl to use the EPSV command when doing passive FTP downloads (which is always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. +.TP +.B CURLOPT_DNS_CACHE_TIMEOUT +Pass a long, this sets the timeout in seconds. Name resolves will be kept in +memory for this number of seconds. Set to zero (0) to completely disable +caching, or set to -1 to make the cached entries remain forever. By default, +libcurl caches info for 60 seconds. (Added in libcurl 7.9.3) +.TP +.B CURLOPT_DNS_USE_GLOBAL_CACHE +Pass a long. If the value is non-zero, it tells curl to use a global DNS cache +that will survive between easy handles creations and deletions. This is not +thread-safe and this will use a global varible. (Added in libcurl 7.9.3) .PP .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an -- cgit v1.2.1 From 14d1da3ae0419210ffd736489330aa689389a933 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Apr 2002 06:20:06 +0000 Subject: spell checked and removed talk about very old version numbers --- docs/libcurl/libcurl.3 | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index e84e693b4..10ff177d1 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl 5 "19 March 2002" "libcurl 7.8.1" "libcurl overview" +.TH libcurl 3 "19 March 2002" "libcurl 7.9.6" "libcurl overview" .SH NAME libcurl \- client-side URL transfers .SH DESCRIPTION @@ -21,7 +21,8 @@ calls, you can use libcurl as described below. When using libcurl's "easy" interface you init your session and get a handle, which you use as input to the easy interface functions you use. Use -\fIcurl_easy_init()\fP to get the handle. +\fIcurl_easy_init()\fP to get the handle. There is also the so called "multi" +interface, try the \fIlibcurl-multi(3)\fP man page for an overview of that. You continue by setting all the options you want in the upcoming transfer, most important among them is the URL itself (you can't transfer anything @@ -75,9 +76,8 @@ portable case insensitive string comparisons .RE .SH "LINKING WITH LIBCURL" -Starting with 7.7.2 (on unix-like machines), there's a tool named curl-config -that gets installed with the rest of the curl stuff when 'make install' is -performed. +On unix-like machines, there's a tool named curl-config that gets installed +with the rest of the curl stuff when 'make install' is performed. curl-config is added to make it easier for applications to link with libcurl and developers to learn about libcurl and how to use it. @@ -103,19 +103,18 @@ several threads. libcurl is thread-safe and can be used in any number of threads, but you must use separate curl handles if you want to use libcurl in more than one thread simultaneously. .SH "PERSISTANT CONNECTIONS" -With libcurl 7.7, persistant connections were added. Persistant connections -means that libcurl can re-use the same connection for several transfers, if -the conditions are right. +Persistent connections means that libcurl can re-use the same connection for +several transfers, if the conditions are right. -libcurl will *always* attempt to use persistant connections. Whenever you use +libcurl will *always* attempt to use persistent connections. Whenever you use curl_easy_perform(), libcurl will attempt to use an existing connection to do -the transfer, and if none exists it'll open a new one that will be subject -for re-use on a possible following call to curl_easy_perform(). +the transfer, and if none exists it'll open a new one that will be subject for +re-use on a possible following call to curl_easy_perform(). -To allow libcurl to take full advantage of persistant connections, you should -do as many of your file transfers as possible using the same curl -handle. When you call curl_easy_cleanup(), all the possibly open connections -held by libcurl will be closed and forgotten. +To allow libcurl to take full advantage of persistent connections, you should +do as many of your file transfers as possible using the same curl handle. When +you call curl_easy_cleanup(), all the possibly open connections held by +libcurl will be closed and forgotten. Note that the options set with curl_easy_setopt() will be used in on every repeat curl_easy_perform() call -- cgit v1.2.1 From 536ea60d73cd407b076c36bb0dbf72c37a586b0e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Apr 2002 13:24:45 +0000 Subject: error codes documented --- docs/libcurl/libcurl-errors.3 | 233 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 docs/libcurl/libcurl-errors.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 new file mode 100644 index 000000000..ceeb56d61 --- /dev/null +++ b/docs/libcurl/libcurl-errors.3 @@ -0,0 +1,233 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH libcurl-errors 3 "10 April 2002" "libcurl 7.9.6" "libcurl errors" +.SH NAME +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. +.SH "CURLcode" +Almost all "easy" interface functions return a CURLcode error code. No matter +what, using \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. CURLcode is one of the following: +.RS 1 +.TP 5 +.B CURLE_OK (0) +All fine. Proceed as usual. +.TP +.B CURLE_UNSUPPORTED_PROTOCOL (1) +The URL you passed to libcurl used a protocol that this libcurl does not +support. The support might be a compile-time option that you didn't use, it +can be a misspelled protocol string or just a protocol libcurl has no code +for. +.TP +.B CURLE_FAILED_INIT (2) +Very early initialization code failed. This is likely to be an internal error +or problem. +.TP +.B CURLE_URL_MALFORMAT (3) +The URL was not properly formatted. +.TP +.B CURLE_URL_MALFORMAT_USER (4) +URL user malformatted. The user-part of the URL syntax was not correct. +.TP +.B CURLE_COULDNT_RESOLVE_PROXY (5) +Couldn't resolve proxy. The given proxy host could not be resolved. +.TP +.B CURLE_COULDNT_RESOLVE_HOST (6) +Couldn't resolve host. The given remote host was not resolved. +.TP +.B CURLE_COULDNT_CONNECT (7) +Failed to connect() to host or proxy. +.TP +.B CURLE_FTP_WEIRD_SERVER_REPLY (8) +After connecting to a FTP server, libcurl expects to get a certain reply back. +This error code implies that it god a strange or bad reply. The given remote +server is probably not an OK FTP server. +.TP +.B CURLE_FTP_ACCESS_DENIED (9) +We were denied access when trying to login to an FTP server or when trying to +change working directory to the one given in the URL. +.TP +.B CURLE_FTP_USER_PASSWORD_INCORRECT (10) +The username and/or the password were incorrect when trying to login to an FTP +server. +.TP +.B CURLE_FTP_WEIRD_PASS_REPLY (11) +After having sent the FTP password to the server, libcurl expects a proper +reply. This error code indicates that an unexpected code was returned. +.TP +.B CURLE_FTP_WEIRD_USER_REPLY (12) +After having sent user name to the FTP server, libcurl expects a proper +reply. This error code indicates that an unexpected code was returned. +.TP +.B CURLE_FTP_WEIRD_PASV_REPLY (13) +libcurl failed to get a sensible result back from the server as a response to +either a PASV or a EPSV command. The server is flawed. +.TP +.B CURLE_FTP_WEIRD_227_FORMAT (14) +FTP servers return a 227-line as a response to a PASV command. If libcurl +fails to parse that line, this return code is passed back. +.TP +.B CURLE_FTP_CANT_GET_HOST (15) +An internal failure to lookup the host used for the new connection. +.TP +.B CURLE_FTP_CANT_RECONNECT (16) +A bad return code on either PASV or EPSV was sent by the FTP server, +preventing libcurl from being able to continue. +.TP +.B CURLE_FTP_COULDNT_SET_BINARY (17) +Received an error when trying to set the transfer mode to binary. +.TP +.B 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 +doesn't match the previously given size. +.TP +.B CURLE_FTP_COULDNT_RETR_FILE (19) +This was either a weird reply to a 'RETR' command or a zero byte transfer +complete. +.TP +.B CURLE_FTP_WRITE_ERROR (20) +After a completed file transfer, the FTP server did not respond a proper +\"transfer successful\" code. +.TP +.B CURLE_FTP_QUOTE_ERROR (21) +When sending custom "QUOTE" commands to the remote server, one of the commands +returned an error code that was 400 or higher. +.TP +.B CURLE_HTTP_NOT_FOUND (22) +This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server +returns an error code that is >= 400. +.TP +.B CURLE_WRITE_ERROR (23) +This error message is in fact used for two different kinds of write +errors. (This fact should be corrected in future versions of libcurl.) The +first kind of write this error code might refer to, is for errors that occurs +when writing received data to a local file, the other kind is when we get +problems writing data to a remote server. +.TP +.B CURLE_MALFORMAT_USER (24) +Malformat user. User name badly specified. *Not currently used* +.TP +.B CURLE_FTP_COULDNT_STOR_FILE (25) +FTP couldn't STOR file. The server denied the STOR operation. The error buffer +usually contains the server's explanation to this. +.TP +.B CURLE_READ_ERROR (26) +This error is returned both for errors when reading a local file, as well as +when getting problems when reading network data. +.TP +.B CURLE_OUT_OF_MEMORY (27) +Out of memory. A memory allocation request failed. This is serious badness and +things are severly screwed up if this ever occur. +.TP +.B CURLE_OPERATION_TIMEOUTED (28) +Operation timeout. The specified time-out period was reached according to the +conditions. +.TP +.B CURLE_FTP_COULDNT_SET_ASCII (29) +libcurl failed to set ASCII transfer type (TYPE A). +.TP +.B CURLE_FTP_PORT_FAILED (30) +The FTP PORT command returned error. This mostly happen when you haven't +specified a good enough address for libcurl to use. See \fICURLOPT_FTPPORT\fP. +.TP +.B CURLE_FTP_COULDNT_USE_REST (31) +The FTP REST command returned error. This should never happen if the server is +sane. +.TP +.B CURLE_FTP_COULDNT_GET_SIZE (32) +The FTP SIZE command returned errror. SIZE is not a kosher FTP command, it is +an extension and not all servers support it. This is not a surprising error. +.TP +.B CURLE_HTTP_RANGE_ERROR (33) +The HTTP server does not support or accept range requests. +.TP +.B CURLE_HTTP_POST_ERROR (34) +This is an odd error that mainly occurs due to internal confusion. +.TP +.B CURLE_SSL_CONNECT_ERROR (35) +A problem occured somewhere in the SSL/TLS handshake. You really want the +error buffer and read the message there as it pinpoints the problem slightly +more. Could be certificates (file formats, paths, permissions), passwords, and +others. +.TP +.B CURLE_FTP_BAD_DOWNLOAD_RESUME (36) +Attempting FTP resume beyond file size. +.TP +.B CURLE_FILE_COULDNT_READ_FILE (37) +A file given with FILE:// couldn't be opened. Most likely because the file +path doesn't identify an existing file. Did you check file permissions? +.TP +.B CURLE_LDAP_CANNOT_BIND (38) +LDAP cannot bind. LDAP bind operation failed. +.TP +.B CURLE_LDAP_SEARCH_FAILED (39) +LDAP search failed. +.TP +.B CURLE_LIBRARY_NOT_FOUND (40) +Library not found. The LDAP library was not found. +.TP +.B CURLE_FUNCTION_NOT_FOUND (41) +Function not found. A required LDAP function was not found. +.TP +.B CURLE_ABORTED_BY_CALLBACK (42) +Aborted by callback. A callback returned "abort" to libcurl. +.TP +.B CURLE_BAD_FUNCTION_ARGUMENT (43) +Internal error. A function was called with a bad parameter. +.TP +.B CURLE_BAD_CALLING_ORDER (44) +Internal error. A function was called in a bad order. +.TP +.B CURLE_HTTP_PORT_FAILED (45) +Interface error. A specified outgoing interface could not be used. Set which +interface to use for outgoing connections' source IP address with +CURLOPT_INTERFACE. +.TP +.B CURLE_BAD_PASSWORD_ENTERED (46) +Bad password entered. An error was signaled when the password was +entered. This can also be the result of a "bad password" returned from a +specified password callback. +.TP +.B CURLE_TOO_MANY_REDIRECTS (47) +Too many redirects. When following redirects, libcurl hit the maximum amount. +Set your limit with CURLOPT_MAXREDIRS. +.TP +.B CURLE_UNKNOWN_TELNET_OPTION (48) +An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to +the appropriate documentation. +.TP +.B CURLE_TELNET_OPTION_SYNTAX (49) +A telnet option string was Illegally formatted. +.TP +.B CURLE_OBSOLETE (50) +This is not an error. This used to be another error code in an old libcurl +version and is currently unused. +.TP +.B CURLE_SSL_PEER_CERTIFICATE (51) +The remote server's SSL certificate was deemed not OK. +.TP +.B CURLE_GOT_NOTHING (52) +Nothing was returned from the server, and under the circumstances, getting +nothing is considered an error. +.TP +.B CURLE_SSL_ENGINE_NOTFOUND (53) +The specified crypto engine wasn't found. +.TP +.B CURLE_SSL_ENGINE_SETFAILED (54) +Failed setting the selected SSL crypto engine as default! + +.TP +.B CURL_LAST +This is not an error, but in the curl/curl.h file this can be used to know how +many existing error codes there are. +.RE + +.SH "CURLMcode" +This is the generic return code used by functions in the libcurl multi +interface. -- cgit v1.2.1 From 09df9b90c323a42397caf02150b87b4daa077e5c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Apr 2002 18:08:50 +0000 Subject: corrected to new return codes --- docs/libcurl/libcurl-errors.3 | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index ceeb56d61..7181e0b08 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -12,7 +12,12 @@ Why they occur and possibly what you can do to fix the problem. Almost all "easy" interface functions return a CURLcode error code. No matter what, using \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. CURLcode is one of the following: +than just the error code does. + +This man page is meant to describe libcurl 7.9.6 and later. Earlier versions +might have had quirks not mentioned here. + +CURLcode is one of the following: .RS 1 .TP 5 .B CURLE_OK (0) @@ -104,11 +109,8 @@ This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server returns an error code that is >= 400. .TP .B CURLE_WRITE_ERROR (23) -This error message is in fact used for two different kinds of write -errors. (This fact should be corrected in future versions of libcurl.) The -first kind of write this error code might refer to, is for errors that occurs -when writing received data to a local file, the other kind is when we get -problems writing data to a remote server. +An error occurred when writing received data to a local file, or an error was +returned to libcurl from a write callback. .TP .B CURLE_MALFORMAT_USER (24) Malformat user. User name badly specified. *Not currently used* @@ -118,8 +120,8 @@ FTP couldn't STOR file. The server denied the STOR operation. The error buffer usually contains the server's explanation to this. .TP .B CURLE_READ_ERROR (26) -This error is returned both for errors when reading a local file, as well as -when getting problems when reading network data. +There was a problem reading a local file or an error returned by the read +callback. .TP .B CURLE_OUT_OF_MEMORY (27) Out of memory. A memory allocation request failed. This is serious badness and @@ -221,7 +223,12 @@ The specified crypto engine wasn't found. .TP .B CURLE_SSL_ENGINE_SETFAILED (54) Failed setting the selected SSL crypto engine as default! - +.TP +.B CURLE_SEND_ERROR (55) +Failed sending network data. +.TP +.B CURLE_RECV_ERROR (56) +Failure with receiving network data. .TP .B CURL_LAST This is not an error, but in the curl/curl.h file this can be used to know how -- cgit v1.2.1 From eb8770506f95e6abd87246a167f1225d10fd1beb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Apr 2002 10:10:36 +0000 Subject: added libcurl-errors --- docs/libcurl/Makefile.am | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index cfd1a1fe2..76c17cff1 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -34,7 +34,8 @@ man_MANS = \ curl_multi_init.3 \ curl_multi_perform.3 \ curl_multi_remove_handle.3 \ - libcurl-multi.3 + libcurl-multi.3 \ + libcurl-errors.3 HTMLPAGES = \ curl_easy_cleanup.html \ @@ -67,6 +68,7 @@ HTMLPAGES = \ curl_multi_perform.html \ curl_multi_remove_handle.html \ libcurl-multi.html \ + libcurl-errors.html \ index.html EXTRA_DIST = $(man_MANS) $(HTMLPAGES) -- cgit v1.2.1 From a00918116de72a88f8b29cae1f9ed075057dea9f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Apr 2002 11:39:27 +0000 Subject: 7.9.6-pre5 --- docs/libcurl/curl_easy_setopt.3 | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2027977e1..9e8b26904 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "2 Apr 2002" "libcurl 7.9.2" "libcurl Manual" +.TH curl_easy_setopt 3 "12 Apr 2002" "libcurl 7.9.6" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS @@ -35,7 +35,7 @@ The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. .SH OPTIONS The options are listed in a sort of random order, but you'll figure it out! -.TP 0.8i +.TP 0.4i .B CURLOPT_FILE Data pointer to pass to the file write function. Note that if you specify the \fICURLOPT_WRITEFUNCTION\fP, this is the pointer you'll get as input. If you @@ -626,10 +626,23 @@ libcurl caches info for 60 seconds. (Added in libcurl 7.9.3) Pass a long. If the value is non-zero, it tells curl to use a global DNS cache that will survive between easy handles creations and deletions. This is not thread-safe and this will use a global varible. (Added in libcurl 7.9.3) +.TP +.B CURLOPT_DEBUGFUNCTION +Function pointer that should match the following prototype: \fIint +curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP +This function will receive debug information if CURLOPT_VERBOSE is +enabled. The curl_infotype argument specifies what kind of information it +is. This funtion must return 0. +.TP +.B CURLOPT_DEBUGDATA +Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in +the last void * argument. This pointer is not used by libcurl, it is only +passed to the callback. .PP .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an -error occurred as \fI\fP defines. +error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP +man page for the full list with descriptions. .SH "SEE ALSO" .BR curl_easy_init "(3), " curl_easy_cleanup "(3), " .SH BUGS -- cgit v1.2.1 From 2bc84fb1639aef24e5c883976dc36c50647a22ff Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 17 Apr 2002 07:21:17 +0000 Subject: Dirk Manske's two new infos --- docs/libcurl/curl_easy_getinfo.3 | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index fba3947fe..e60f97f94 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_init 3 "31 Jan 2001" "libcurl 7.9.4" "libcurl Manual" +.TH curl_easy_init 3 "17 Apr 2002" "libcurl 7.9.7" "libcurl Manual" .SH NAME curl_easy_getinfo - Extract information from a curl session (added in 7.4) .SH SYNOPSIS @@ -60,6 +60,16 @@ start until the first byte is just about to be transfered. This includes CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate the result. .TP +.B CURLINFO_REDIRECT_TIME +Pass a pointer to a double to receive the total time, in seconds, it took for +all redirection steps include name lookup, connect, pretransfer and transfer +before final transaction was started. CURLINFO_REDIRECT_TIME contains the +complete execution time for multiple redirections. (Added in 7.9.7) +.TP +.B CURLINFO_REDIRECT_COUNT +Pass a pointer to a long to receive the total number of redirections that were +actually followed. (Added in 7.9.7) +.TP .B CURLINFO_SIZE_UPLOAD Pass a pointer to a double to receive the total amount of bytes that were uploaded. -- cgit v1.2.1 From 47819ea86e45cb4302cbfb45722e91a04939422c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 24 Apr 2002 10:16:46 +0000 Subject: clarified a bit with the timecondition stuff --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9e8b26904..c3a93273c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "12 Apr 2002" "libcurl 7.9.6" "libcurl Manual" +.TH curl_easy_setopt 3 "22 Apr 2002" "libcurl 7.9.6" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS @@ -428,8 +428,8 @@ TIMECOND_IFUNMODSINCE. This is a HTTP-only feature. (TBD) .TP .B CURLOPT_TIMEVALUE Pass a long as parameter. This should be the time in seconds since 1 jan 1970, -and the time will be used as specified in CURLOPT_TIMECONDITION or if that -isn't used, it will be TIMECOND_IFMODSINCE by default. +and the time will be used in a condition as specified with +CURLOPT_TIMECONDITION. .TP .B CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user -- cgit v1.2.1 From f6525ae20087290e1ce91839461e671b9ec81cc0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 25 Apr 2002 16:45:15 +0000 Subject: the TOTAL_TIME is not really total, as it excludes the connect time... --- docs/libcurl/curl_easy_getinfo.3 | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index e60f97f94..9f1e6a07e 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_init 3 "17 Apr 2002" "libcurl 7.9.7" "libcurl Manual" +.TH curl_easy_init 3 "25 Apr 2002" "libcurl 7.9.7" "libcurl Manual" .SH NAME curl_easy_getinfo - Extract information from a curl session (added in 7.4) .SH SYNOPSIS @@ -38,7 +38,9 @@ CURLOPT_FILETIME option to \fIcurl_easy_setopt(3)\fP. (Added in 7.5) .TP .B CURLINFO_TOTAL_TIME Pass a pointer to a double to receive the total transaction time in seconds -for the previous transfer. +for the previous transfer. This time does not include the connect time, so if +you want the complete operation time, you should add the +CURLINFO_CONNECT_TIME. .TP .B CURLINFO_NAMELOOKUP_TIME Pass a pointer to a double to receive the time, in seconds, it took from the -- cgit v1.2.1 From bd9650bc8135b2d0aecf73f261d4deddbdb5dfb6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 30 Apr 2002 07:37:02 +0000 Subject: how to set more than one cookie --- docs/libcurl/curl_easy_setopt.3 | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c3a93273c..5d7d2b91d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "22 Apr 2002" "libcurl 7.9.6" "libcurl Manual" +.TH curl_easy_setopt 3 "30 Apr 2002" "libcurl 7.9.6" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS @@ -293,6 +293,13 @@ want the transfer to start from. Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be [NAME]=[CONTENTS]; Where NAME is the cookie name. + +If you need to set mulitple cookies, you need to set them all using a single +option and thus you need to concat them all in one single string. Set multiple +cookies in one string like this: "name1=content1; name2=content2;" etc. + +Using this option multiple times will only make the latest string override the +previously ones. .TP .B CURLOPT_HTTPHEADER Pass a pointer to a linked list of HTTP headers to pass to the server in your -- cgit v1.2.1 From 9ef97979985badcfd5bdc97055508e53ba54d6a0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 2 May 2002 22:34:31 +0000 Subject: clarified that you must keep the variables that you point to! --- docs/libcurl/curl_multi_fdset.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 48aadad8b..0fab39e0b 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_fdset 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.TH curl_multi_fdset 3 "3 May 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_fdset - add an easy handle to a multi session .SH SYNOPSIS @@ -17,6 +17,10 @@ This function extracts file descriptor information from a given multi_handle. libcurl returns its fd_set sets. The application can use these to select() or poll() on. The curl_multi_perform() function should be called as soon as one of them are ready to be read from or written to. + +NOTE that once this call is made, you must not remove the sets you point to, +as libcurl will need to be able to read them. It needs them after select() +calls, to know if certain sockets are readable or writable. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" -- cgit v1.2.1 From d9a1a59f2242711e287df3b93160e0a2494f23e1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 3 May 2002 14:50:29 +0000 Subject: CURL_MAX_WRITE_SIZE is a new exported define that informs about the biggest sized buffer that may be passed to a write callback --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5d7d2b91d..34a6b5f06 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "30 Apr 2002" "libcurl 7.9.6" "libcurl Manual" +.TH curl_easy_setopt 3 "3 May 2002" "libcurl 7.9.6" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS @@ -60,7 +60,8 @@ Set the \fIstream\fP argument with the \fBCURLOPT_FILE\fP option. \fBNOTE:\fP you will be passed as much data as possible in all invokes, but you cannot possibly make any assumptions. It may be one byte, it may be -thousands. +thousands. The maximum amount of data that can be passed to the write callback +is defined in the curl.h header file: CURL_MAX_WRITE_SIZE. .TP .B CURLOPT_INFILE Data pointer to pass to the file read function. Note that if you specify the -- cgit v1.2.1 From 8539e76cb9a7308f59e584f0cf62c11427f88e0e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 6 May 2002 13:43:35 +0000 Subject: CURLOPT_FILE and CURLOPT_INFILE have better aliases now: CURLOPT_WRITEDATA and CURLOPT_READDATA --- docs/libcurl/curl_easy_setopt.3 | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 34a6b5f06..c1c7c636e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -36,7 +36,7 @@ The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or .SH OPTIONS The options are listed in a sort of random order, but you'll figure it out! .TP 0.4i -.B CURLOPT_FILE +.B CURLOPT_WRITEDATA Data pointer to pass to the file write function. Note that if you specify the \fICURLOPT_WRITEFUNCTION\fP, this is the pointer you'll get as input. If you don't use a callback, you must pass a 'FILE *' as libcurl will pass this to @@ -45,6 +45,8 @@ fwrite() when writing data. \fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use the \fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience crashes. + +This option is also known with the older name \fBCURLOPT_FILE\fP. .TP .B CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t @@ -63,13 +65,15 @@ you cannot possibly make any assumptions. It may be one byte, it may be thousands. The maximum amount of data that can be passed to the write callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE. .TP -.B CURLOPT_INFILE +.B CURLOPT_READDATA Data pointer to pass to the file read function. Note that if you specify the \fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you don't specify a read callback, this must be a valid FILE *. \fBNOTE:\fP 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 \fBCURLOPT_INFILE\fP. .TP .B CURLOPT_READFUNCTION Function pointer that should match the following prototype: \fBsize_t -- cgit v1.2.1 From 20d9c1b30d305adf459a6bb496e410a8ad7c8169 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 7 May 2002 23:36:53 +0000 Subject: Patrick Smith's contributed docs improvements for when NLST is used by curl... --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c1c7c636e..343b4592e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -171,6 +171,10 @@ will imply this option. A non-zero parameter tells the library to just list the names of an ftp directory, instead of doing a full directory listing that would include file sizes, dates etc. + +This causes an FTP NLST command to be sent. Beware that some FTP servers +list only files in their response to NLST; they do not include +subdirectories and symbolic links. .TP .B CURLOPT_FTPAPPEND A non-zero parameter tells the library to append to the remote file instead of -- cgit v1.2.1 From c3c392fc9801e7eb1834613ad41c57bb386355c0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 21 May 2002 07:47:09 +0000 Subject: return type CURLFORMcode instead of plain int --- docs/libcurl/curl_formadd.3 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index e0e157279..93bed079d 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -2,13 +2,13 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_formadd 3 "1 Match 2002" "libcurl 7.9.1" "libcurl Manual" +.TH curl_formadd 3 "21 May 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS .B #include .sp -.BI "int curl_formadd(struct HttpPost ** " firstitem, +.BI "CURLFORMcode curl_formadd(struct HttpPost ** " firstitem, .BI "struct HttpPost ** " lastitem, " ...);" .ad .SH DESCRIPTION @@ -83,7 +83,9 @@ you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP. See example below. .SH RETURN VALUE -Returns non-zero if an error occurs. +0 means everything was ok, non-zero means an error occurred as +.I +defines. .SH EXAMPLE .nf -- cgit v1.2.1 From 51fcee6f811c46c55cefebb726e6c4dee7dedd13 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 21 May 2002 22:20:16 +0000 Subject: James Cone added CURLOPT_NETRC / --netrc / --netrc-optional descriptions --- docs/libcurl/curl_easy_setopt.3 | 37 +++++++++++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 343b4592e..5635ebdb4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -181,10 +181,39 @@ A non-zero parameter tells the library to append to the remote file instead of overwrite it. This is only useful when uploading to a ftp site. .TP .B CURLOPT_NETRC -A non-zero parameter tells the library to scan your \fI~/.netrc\fP file to -find user name and password for the remote site you are about to access. Only -machine name, user name and password is taken into account (init macros and -similar things aren't supported). +This parameter controls the preference of libcurl between using user names and +passwords from your \fI~/.netrc\fP file, relative to user names and passwords +in the URL supplied with \fICURLOPT_URL\fP. + +\fBNote:\fP libcurl uses a user name (and supplied or prompted password) +supplied with \fICURLOPT_USERPWD\fP in preference to any of the options +controlled by this parameter. + +Pass a long, set to one of the values described below. +.RS +.TP 5 +.B 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 password after that \fImachine\fP, +which ever information is not specified in the URL. + +Undefined values of the option will have this effect. +.TP +.B CURL_NETRC_IGNORED +The library will ignore the file and use only the information in the URL. + +This is the default. +.TP +.B 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. +.RE +.TP +Only machine name, user name and password are taken into account +(init macros and similar things aren't supported). \fBNote:\fP libcurl does not verify that the file has the correct properties set (as the standard Unix ftp client does). It should only be readable by -- cgit v1.2.1 From 59c11b82d55b6e8110f2232f0fd47068e4072495 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 28 May 2002 09:21:29 +0000 Subject: Cris Bailiff's CAPATH support added --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5635ebdb4..a118a15d6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -514,12 +514,20 @@ argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. .B CURLOPT_SSL_VERIFYPEER Pass a long that is set to a non-zero value to make curl verify the peer's certificate. The certificate to verify against must be specified with the -CURLOPT_CAINFO option. (Added in 7.4.2) +CURLOPT_CAINFO option (Added in 7.4.2) or a certificate directory must be specified +with the CURLOPT_CAPATH option (Added in 7.9.8). .TP .B CURLOPT_CAINFO -Pass a char * to a zero terminated file naming holding the certificate to -verify the peer with. This only makes sense when used in combination with the -CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2) +Pass a char * to a zero terminated string naming a file holding one or more +certificates to verify the peer with. This only makes sense when used in +combination with the CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2) +.TP +.B CURLOPT_CAPATH +Pass a char * to a zero terminated string naming a directory holding multiple CA +certificates to verify the peer with. The certificate directory must be prepared using +the openssl c_rehash utility. This only makes sense when used in combination with the +CURLOPT_SSL_VERIFYPEER option. The CAPATH function apparently does not work in Windows +due to some limitation in openssl. (Added in 7.9.8) .TP .B CURLOPT_PASSWDFUNCTION Pass a pointer to a \fIcurl_passwd_callback\fP function that will be called -- cgit v1.2.1 From 15bc7e19f9335958adbc8787904184068469bada Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 3 Jun 2002 13:04:35 +0000 Subject: updated header --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a118a15d6..c953bf7bc 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "3 May 2002" "libcurl 7.9.6" "libcurl Manual" +.TH curl_easy_setopt 3 "28 May 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS -- cgit v1.2.1 From 5cb06d8fd6e917e118fa039cf02017d6c903a145 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 15 Jun 2002 11:17:42 +0000 Subject: Chris Combes added description of his newly added options --- docs/libcurl/curl_formadd.3 | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 93bed079d..2c522c90a 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_formadd 3 "21 May 2002" "libcurl 7.9.8" "libcurl Manual" +.TH curl_formadd 3 "15 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS @@ -29,9 +29,10 @@ name). All options that use the word COPY in their names copy the given contents, while the ones with PTR in their names simply points to the (static) data you must make sure remain until curl no longer needs it. -The four options for providing values are: \fBCURLFORM_COPYCONTENTS\fP, -\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, or \fBCURLFORM_FILECONTENT\fP -followed by a char or void pointer (allowed for PTRCONTENTS). +The options for providing values are: \fBCURLFORM_COPYCONTENTS\fP, +\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, \fBCURLFORM_BUFFER\fP, +or \fBCURLFORM_FILECONTENT\fP followed by a char or void pointer +(allowed for PTRCONTENTS). \fBCURLFORM_FILECONTENT\fP does a normal post like \fBCURLFORM_COPYCONTENTS\fP but the actual value is read from the filename given as a string. @@ -48,6 +49,20 @@ For \fBCURLFORM_FILE\fP the user may send multiple files in one section by providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename (and each FILE is allowed to have a CONTENTTYPE). +\fBCURLFORM_BUFFER\fP +tells libcurl that a buffer is to be used to upload data instead of using a +file. The value of the next parameter is used as the value of the "filename" +parameter in the content header. + +\fBCURLFORM_BUFFERPTR\fP +tells libcurl that the address of the next parameter is a pointer to the buffer +containing data to upload. The buffer containing this data must not be freed +until after curl_easy_cleanup is called. + +\fBCURLFORM_BUFFERLENGTH\fP +tells libcurl that the length of the buffer to upload is the value of the +next parameter. + Another possibility to send single or multiple files in one section is to use \fBCURLFORM_ARRAY\fP that gets a struct curl_forms array pointer as its value. Each structure element has a CURLformoption and a char pointer. For the @@ -149,6 +164,13 @@ defines. forms[1].value = file2; forms[2].option = CURLFORM_END; + /* Add a buffer to upload */ + curl_formadd(&post, &last, + CURLFORM_BUFFER, "data", + CURLFORM_BUFFERPTR, record, + CURLFORM_BUFFERLENGTH, record_length, + CURLFORM_END); + /* no option needed for the end marker */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", CURLFORM_ARRAY, forms, CURLFORM_END); -- cgit v1.2.1 From 62527fa98a822243aaf0b07dde0a85c851ed771b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 24 Jun 2002 06:14:56 +0000 Subject: corrected to match reality better --- docs/libcurl/curl_formadd.3 | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 2c522c90a..66d4ffefd 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_formadd 3 "15 June 2002" "libcurl 7.9.8" "libcurl Manual" +.TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS @@ -63,15 +63,11 @@ until after curl_easy_cleanup is called. tells libcurl that the length of the buffer to upload is the value of the next parameter. -Another possibility to send single or multiple files in one section is to use -\fBCURLFORM_ARRAY\fP that gets a struct curl_forms array pointer as its -value. Each structure element has a CURLformoption and a char pointer. For the -options only \fBCURLFORM_FILE\fP, \fBCURLFORM_CONTENTTYPE\fP, and -\fBCURLFORM_END\fP (that is used to determine the end of the array and thus -must be the option of the last and no other element of the curl_forms array) -are allowed. The effect of this parameter is the same as giving multiple -\fBCURLFORM_FILE\fP options possibly with \fBCURLFORM_CONTENTTYPE\fP after or -before each \fBCURLFORM_FILE\fP option. +Another possibility to send options to curl_formadd() is the +\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as +its value. Each curl_forms structure element has a CURLformoption and a char +pointer. The final element in the array must be a CURLFORM_END. All available +options can be used in an array, except the CURLFORM_ARRAY option itself! Should you need to specify extra headers for the form POST section, use \fBCURLFORM_CONTENTHEADER\fP. This takes a curl_slist prepared in the usual way @@ -166,6 +162,7 @@ defines. /* Add a buffer to upload */ curl_formadd(&post, &last, + CURLFORM_COPYNAME, "name", CURLFORM_BUFFER, "data", CURLFORM_BUFFERPTR, record, CURLFORM_BUFFERLENGTH, record_length, -- cgit v1.2.1 From f79f5cbf82bc6c7e2961fcff97377adadff35b02 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 29 Jul 2002 22:42:11 +0000 Subject: Setting PASSWDFUNCTION to NULL will set back the internal function as password function. --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c953bf7bc..4a5d65a7a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -533,9 +533,9 @@ due to some limitation in openssl. (Added in 7.9.8) Pass a pointer to a \fIcurl_passwd_callback\fP function that will be called instead of the internal one if libcurl requests a password. The function must match this prototype: \fBint my_getpass(void *client, char *prompt, char* -buffer, int buflen );\fP. If set to NULL, it equals to making the function -always fail. If the function returns a non-zero value, it will abort the -operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned. +buffer, int buflen );\fP. If set to NULL, it sets back the function to the +internal default one. If the function returns a non-zero value, it will abort +the operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned. \fIclient\fP is a generic pointer, see \fICURLOPT_PASSWDDATA\fP. \fIprompt\fP is a zero-terminated string that is text that prefixes the input request. \fIbuffer\fP is a pointer to data where the entered password should be stored -- cgit v1.2.1 From 33306b2749281626fe69bba57cb4871dd89cbaf7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Aug 2002 09:38:31 +0000 Subject: jonatan's fixes --- docs/libcurl/curl_easy_setopt.3 | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4a5d65a7a..e3908c686 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "28 May 2002" "libcurl 7.9.8" "libcurl Manual" +.TH curl_easy_setopt 3 "5 Aug 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS @@ -46,7 +46,8 @@ fwrite() when writing data. \fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience crashes. -This option is also known with the older name \fBCURLOPT_FILE\fP. +This option is also known with the older name \fBCURLOPT_FILE\fP, the name +CURLOPT_WRITEDATA was introduced in 7.9.7. .TP .B CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t @@ -73,7 +74,8 @@ don't specify a read callback, this must be a valid FILE *. \fBNOTE:\fP 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 \fBCURLOPT_INFILE\fP. +This option is also known with the older name \fBCURLOPT_INFILE\fP, the name +CURLOPT_READDATA was introduced in 7.9.7. .TP .B CURLOPT_READFUNCTION Function pointer that should match the following prototype: \fBsize_t @@ -123,7 +125,7 @@ specified in the proxy string \fICURLOPT_PROXY\fP. Set the parameter to non-zero to get the library to tunnel all operations through a given HTTP proxy. Note that 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. (Added in libcurl 7.3) +probably don't want this tunneling option. (Added in 7.3) .TP .B CURLOPT_VERBOSE Set the parameter to non-zero to get the library to display a lot of verbose @@ -453,7 +455,7 @@ multiplied with \fInmemb\fP. The pointer named \fIstream\fP will be the one you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the number of bytes actually written or return -1 to signal error to the library (it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return -code). (Added in libcurl 7.7.2) +code). (Added in 7.7.2) .TP .B CURLOPT_COOKIEFILE Pass a pointer to a zero terminated string as parameter. It should contain the @@ -489,14 +491,14 @@ internally when reporting errors. .B 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 -name. (Added in libcurl 7.3) +name. (Added in 7.3) .TP .B CURLOPT_KRB4LEVEL Pass a char * as parameter. Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or \&'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos4. The kerberos -support only works for FTP. (Added in libcurl 7.3) +support only works for FTP. (Added in 7.3) .TP .B CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype @@ -602,7 +604,7 @@ re-use (default behavior). (Added in 7.7) .B CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, -the more secure will the SSL connection become. +the more secure the SSL connection will become. .TP .B CURLOPT_EGDSOCKET Pass a char * to the zero terminated path name to the Entropy Gathering Daemon @@ -632,7 +634,7 @@ the provided hostname. (Added in 7.8.1) Pass a file name as char *, zero terminated. This will make libcurl dump all internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP is called. If no cookies are known, no file will be created. Specify "-" to -instead have the cookies written to stdout. +instead have the cookies written to stdout. (Added in 7.9) .TP .B CURLOPT_SSL_CIPHER_LIST Pass a char *, pointing to a zero terminated string holding the list of @@ -665,7 +667,7 @@ Enforce HTTP 1.1 requests. .TP .B CURLOPT_FTP_USE_EPSV Pass a long. If the value is non-zero, it tells curl to use the EPSV command -when doing passive FTP downloads (which is always does by default). Using EPSV +when doing passive FTP downloads (which it always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. .TP @@ -673,12 +675,12 @@ pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero (0) to completely disable caching, or set to -1 to make the cached entries remain forever. By default, -libcurl caches info for 60 seconds. (Added in libcurl 7.9.3) +libcurl caches info for 60 seconds. (Added in 7.9.3) .TP .B CURLOPT_DNS_USE_GLOBAL_CACHE Pass a long. If the value is non-zero, it tells curl to use a global DNS cache -that will survive between easy handles creations and deletions. This is not -thread-safe and this will use a global varible. (Added in libcurl 7.9.3) +that will survive between easy handle creations and deletions. This is not +thread-safe and this will use a global varible. (Added in 7.9.3) .TP .B CURLOPT_DEBUGFUNCTION Function pointer that should match the following prototype: \fIint -- cgit v1.2.1 From be24652d4d304929dfe7bd3f3fbc2d208ecec56e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 7 Aug 2002 08:23:40 +0000 Subject: Adding more blurb about activating the cookies on COOKIEFILE and COOKIEJAR --- docs/libcurl/curl_easy_setopt.3 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e3908c686..12087ea8f 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -462,6 +462,10 @@ Pass a pointer to a zero terminated string as parameter. It should contain the name of your file holding cookie data. The cookie data may be in Netscape / Mozilla cookie data format or just regular HTTP-style headers dumped to a file. + +Given an empty or non-existing file, this option will only enable cookies for +this curl handle, making it understand and parse received cookies and then use +matching cookies in future request. .TP .B CURLOPT_SSLVERSION Pass a long as parameter. Set what version of SSL to attempt to use, 2 or @@ -634,7 +638,11 @@ the provided hostname. (Added in 7.8.1) Pass a file name as char *, zero terminated. This will make libcurl dump all internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP is called. If no cookies are known, no file will be created. Specify "-" to -instead have the cookies written to stdout. (Added in 7.9) +instead have the cookies written to stdout. Using this option also enables +cookies for this session, so if you for example follow a location it will make +matching cookies get sent accordingly. + +(Added in 7.9) .TP .B CURLOPT_SSL_CIPHER_LIST Pass a char *, pointing to a zero terminated string holding the list of -- cgit v1.2.1 From b5dd257427e9bcf84985a1be8a3273e1c3767ea0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 8 Aug 2002 23:05:50 +0000 Subject: makes things better --- docs/libcurl/.cvsignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/libcurl/.cvsignore (limited to 'docs/libcurl') diff --git a/docs/libcurl/.cvsignore b/docs/libcurl/.cvsignore new file mode 100644 index 000000000..282522db0 --- /dev/null +++ b/docs/libcurl/.cvsignore @@ -0,0 +1,2 @@ +Makefile +Makefile.in -- cgit v1.2.1 From 7aeb63c817c5b895a178d52723afa421a29a7f1a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 Aug 2002 08:54:49 +0000 Subject: ignore html too --- docs/libcurl/.cvsignore | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/.cvsignore b/docs/libcurl/.cvsignore index 282522db0..09e145216 100644 --- a/docs/libcurl/.cvsignore +++ b/docs/libcurl/.cvsignore @@ -1,2 +1,3 @@ Makefile Makefile.in +*html -- cgit v1.2.1 From 5c1a6ed71934778774ce69726aa4199f4812b82e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 15 Aug 2002 06:13:54 +0000 Subject: Leonce Limousin pointed out flaws --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 12087ea8f..247f5852e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -332,7 +332,7 @@ want the transfer to start from. .B CURLOPT_COOKIE Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be -[NAME]=[CONTENTS]; Where NAME is the cookie name. +\[NAME]=[CONTENTS]; Where NAME is the cookie name. If you need to set mulitple cookies, you need to set them all using a single option and thus you need to concat them all in one single string. Set multiple @@ -398,7 +398,7 @@ the format of your private key. Supported formats are "PEM", "DER" and "ENG". engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to the engine. You have to set the crypto engine with \fICURLOPT_SSL_ENGINE\fP. .TP -.B CURLOPT_SSLKEYASSWD +.B CURLOPT_SSLKEYPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as the password required to use the \fICURLOPT_SSLKEY\fP private key. If the password is not supplied, you will be prompted for -- cgit v1.2.1 From c8ee1fa62e64752ad329aa5fbec1ca4cea91fcf4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 15 Aug 2002 08:06:36 +0000 Subject: modified again to look better HTML converted --- docs/libcurl/curl_easy_setopt.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 247f5852e..b582fa7ec 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -332,7 +332,8 @@ want the transfer to start from. .B CURLOPT_COOKIE Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be -\[NAME]=[CONTENTS]; Where NAME is the cookie name. +NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie +should contain. If you need to set mulitple cookies, you need to set them all using a single option and thus you need to concat them all in one single string. Set multiple -- cgit v1.2.1 From 6d7785a35b35cfe4a061873a9f913a5d8dca832b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 21 Aug 2002 19:04:08 +0000 Subject: NOSIGNAL, BUFFERSIZE and clarification for the PROGRESSFUNCTION --- docs/libcurl/curl_easy_setopt.3 | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b582fa7ec..e467768aa 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "5 Aug 2002" "libcurl 7.9.8" "libcurl Manual" +.TH curl_easy_setopt 3 "20 Aug 2002" "libcurl 7.9.9" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS @@ -513,6 +513,9 @@ Unknown/unused argument values will be set to zero (like if you only download data, the upload size will remain 0). Returning a non-zero value from this callback will cause libcurl to abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. + +Also note that \fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this +function actually get called. .TP .B CURLOPT_PROGRESSDATA Pass a pointer that will be untouched by libcurl and passed as the first @@ -702,6 +705,19 @@ is. This funtion must return 0. Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in the last void * argument. This pointer is not used by libcurl, it is only passed to the callback. +.TP +.B CURLOPT_BUFFERSIZE +Pass a long specifying your prefered size for the receive buffer in libcurl. +The main point of this would be that the write callback gets called more often +and with smaller chunks. This is just treated as a request, not an order. You +cannot be guaranteed to actually get the given size. (Added in 7.9.9) +.TP +.B CURLOPT_NOSIGNAL +Pass a long. If it is non-zero, libcurl will not use any functions that +install signal handlers or any functions that cause signals to be sent to the +process. This option is mainly here to allow multi-threaded unix applications +to still set/use all timeout options etc, without risking getting signals. +(Added in 7.9.9) .PP .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an -- cgit v1.2.1 From 2a0bc64226c06b1e83b44f9fa53b3ff8458d67e7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Aug 2002 19:45:22 +0000 Subject: Markus F.X.J. Oberhumer's added notes about NOSIGNAL in the TIMEOUT descriptions, slightly edited by me. --- docs/libcurl/curl_easy_setopt.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e467768aa..b0b32e9a3 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -276,8 +276,8 @@ considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations. This option will cause curl to use the SIGALRM to enable time-outing system calls. -\fBNOTE:\fP this does not work in Unix multi-threaded programs, as it uses -signals. +\fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as +it uses signals unless CURLOPT_NOSIGNAL (see below) is set. .TP .B CURLOPT_POSTFIELDS Pass a char * as parameter, which should be the full data to post in a HTTP @@ -625,8 +625,8 @@ it has connected, this option is of no more use. Set to zero to disable connection timeout (it will then only timeout on the system's internal timeouts). See also the \fICURLOPT_TIMEOUT\fP option. -\fBNOTE:\fP this does not work in unix multi-threaded programs, as it uses -signals. +\fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as +it uses signals unless CURLOPT_NOSIGNAL (see below) is set. .TP .B CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back -- cgit v1.2.1 From 22cf05519aa09dce9f17bd5c78d34c0c19d03c65 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 13 Sep 2002 12:37:14 +0000 Subject: clarified what CURLOPT_MAXCONNECTS actually do --- docs/libcurl/curl_easy_setopt.3 | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b0b32e9a3..93f9f4ef1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "20 Aug 2002" "libcurl 7.9.9" "libcurl Manual" +.TH curl_easy_setopt 3 "13 Sep 2002" "libcurl 7.10" "libcurl Manual" .SH NAME curl_easy_setopt - Set curl easy-session options .SH SYNOPSIS @@ -572,11 +572,16 @@ redirections have been followed, the next redirect will cause an error \fICURLOPT_FOLLOWLOCATION\fP is used at the same time. (Added in 7.5) .TP .B CURLOPT_MAXCONNECTS -Pass a long. The set number will be the persistant connection cache size. The -set amount will be the maximum amount of simultaneous connections that libcurl -may cache between file transfers. 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. +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. 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 protocols that support +persistent connections. + +When reaching the maximum limit, curl uses the \fICURLOPT_CLOSEPOLICY\fP to +figure out which of the existing connections to close to prevent the number of +open connections to increase. \fBNOTE:\fP if you already have performed transfers with this curl handle, setting a smaller MAXCONNECTS than before may cause open connections to get @@ -710,14 +715,14 @@ passed to the callback. Pass a long specifying your prefered size for the receive buffer in libcurl. The main point of this would be that the write callback gets called more often and with smaller chunks. This is just treated as a request, not an order. You -cannot be guaranteed to actually get the given size. (Added in 7.9.9) +cannot be guaranteed to actually get the given size. (Added in 7.10) .TP .B CURLOPT_NOSIGNAL Pass a long. If it is non-zero, libcurl will not use any functions that install signal handlers or any functions that cause signals to be sent to the process. This option is mainly here to allow multi-threaded unix applications to still set/use all timeout options etc, without risking getting signals. -(Added in 7.9.9) +(Added in 7.10) .PP .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an -- cgit v1.2.1 From 342fce97af208c84ab6297e334a97af08a23b059 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 18 Sep 2002 15:26:42 +0000 Subject: Re-ordered all the options to be more logically structured. Hopefully this will make this page more readable and easy to find things in! --- docs/libcurl/curl_easy_setopt.3 | 871 +++++++++++++++++++++------------------- 1 file changed, 452 insertions(+), 419 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 93f9f4ef1..38e00222a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2,23 +2,23 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "13 Sep 2002" "libcurl 7.10" "libcurl Manual" +.TH curl_easy_setopt 3 "18 Sep 2002" "libcurl 7.10" "libcurl Manual" .SH NAME -curl_easy_setopt - Set curl easy-session options +curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS #include CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); .ad .SH DESCRIPTION -curl_easy_setopt() is used to tell libcurl how to behave. Most operations in -libcurl have default actions, and by using the appropriate options to -\fIcurl_easy_setopt\fP, you can change them. All options are set with the -\fIoption\fP followed by a \fIparameter\fP. That parameter can be a long, a -function pointer or an object pointer, all depending on what the specific -option expects. Read this manual carefully as bad input values may cause -libcurl to behave badly! You can only set one option in each function call. A -typical application uses many curl_easy_setopt() calls in the setup phase. +curl_easy_setopt() is used to tell libcurl how to behave. By using the +appropriate options to \fIcurl_easy_setopt\fP, you can change libcurl's +behavior. All options are set with the \fIoption\fP followed by a +\fIparameter\fP. That parameter can be a long, a function pointer or an object +pointer, all depending on what the specific option expects. Read this manual +carefully as bad input values may cause libcurl to behave badly! You can only +set one option in each function call. A typical application uses many +curl_easy_setopt() calls in the setup phase. \fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be copied by the library. Instead you should keep them available until libcurl no @@ -33,26 +33,42 @@ transfers. The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. -.SH OPTIONS -The options are listed in a sort of random order, but you'll figure it out! +.SH BEHAVIOR OPTIONS .TP 0.4i -.B CURLOPT_WRITEDATA -Data pointer to pass to the file write function. Note that if you specify the -\fICURLOPT_WRITEFUNCTION\fP, this is the pointer you'll get as input. If you -don't use a callback, you must pass a 'FILE *' as libcurl will pass this to -fwrite() when writing data. +.B CURLOPT_VERBOSE +Set the parameter to non-zero to get the library to display a lot of verbose +information about its operations. Very useful for libcurl and/or protocol +debugging and understanding. -\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use the -\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience -crashes. +You hardly ever want this set in production use, you will almost always want +this when you debug/report problems. Another neat option for debugging is the +\fICURLOPT_DEBUGFUNCTION\fP. +.TP +.B CURLOPT_HEADER +A non-zero parameter tells the library to include the header in the body +output. This is only relevant for protocols that actually have headers +preceding the data (like HTTP). +.TP +.B CURLOPT_NOPROGRESS +A non-zero parameter tells the library to shut of the built-in progress meter +completely. -This option is also known with the older name \fBCURLOPT_FILE\fP, the name -CURLOPT_WRITEDATA was introduced in 7.9.7. +\fBNOTE:\fP future versions of libcurl is likely to not have any built-in +progress meter at all. .TP +.B CURLOPT_NOSIGNAL +Pass a long. If it is non-zero, libcurl will not use any functions that +install signal handlers or any functions that cause signals to be sent to the +process. This option is mainly here to allow multi-threaded unix applications +to still set/use all timeout options etc, without risking getting signals. +(Added in 7.10) +.PP +.SH CALLBACK OPTIONS +.TP 0.4i .B CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This -function gets called by libcurl as soon as there is data available that needs +function gets called by libcurl as soon as there is data reveiced that needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP. Return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll @@ -66,16 +82,18 @@ you cannot possibly make any assumptions. It may be one byte, it may be thousands. The maximum amount of data that can be passed to the write callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE. .TP -.B CURLOPT_READDATA -Data pointer to pass to the file read function. Note that if you specify the -\fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you -don't specify a read callback, this must be a valid FILE *. +.B CURLOPT_WRITEDATA +Data pointer to pass to the file write function. Note that if you specify the +\fICURLOPT_WRITEFUNCTION\fP, this is the pointer you'll get as input. If you +don't use a callback, you must pass a 'FILE *' as libcurl will pass this to +fwrite() when writing data. -\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use a -\fICURLOPT_READFUNCTION\fP if you set this option. +\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use the +\fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience +crashes. -This option is also known with the older name \fBCURLOPT_INFILE\fP, the name -CURLOPT_READDATA was introduced in 7.9.7. +This option is also known with the older name \fBCURLOPT_FILE\fP, the name +CURLOPT_WRITEDATA was introduced in 7.9.7. .TP .B CURLOPT_READFUNCTION Function pointer that should match the following prototype: \fBsize_t @@ -87,10 +105,106 @@ bytes. Your function must return the actual number of bytes that you stored in that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer. .TP -.B CURLOPT_INFILESIZE -When uploading a file to a remote site, this option should be used to tell -libcurl what the expected size of the infile is. +.B CURLOPT_READDATA +Data pointer to pass to the file read function. Note that if you specify the +\fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you +don't specify a read callback, this must be a valid FILE *. + +\fBNOTE:\fP 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 \fBCURLOPT_INFILE\fP, the name +CURLOPT_READDATA was introduced in 7.9.7. +.TP +.B CURLOPT_PROGRESSFUNCTION +Function pointer that should match the \fIcurl_progress_callback\fP prototype +found in \fI\fP. This function gets called by libcurl instead of +its internal equivalent with a frequent interval during data transfer. +Unknown/unused argument values will be set to zero (like if you only download +data, the upload size will remain 0). Returning a non-zero value from this +callback will cause libcurl to abort the transfer and return +\fICURLE_ABORTED_BY_CALLBACK\fP. + +Also note that \fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this +function actually get called. +.TP +.B CURLOPT_PROGRESSDATA +Pass a pointer that will be untouched by libcurl and passed as the first +argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. +.TP +.B CURLOPT_PASSWDFUNCTION +Pass a pointer to a \fIcurl_passwd_callback\fP function that will be called +instead of the internal one if libcurl requests a password. The function must +match this prototype: \fBint getpass(void *client, char *prompt, char* buffer, +int buflen );\fP. If set to NULL, it sets back the function to the internal +default one. If the function returns a non-zero value, it will abort the +operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned. +\fIclient\fP is a generic pointer, see \fICURLOPT_PASSWDDATA\fP. \fIprompt\fP +is a zero-terminated string that is text that prefixes the input request. +\fIbuffer\fP is a pointer to data where the entered password should be stored +and \fIbuflen\fP is the maximum number of bytes that may be written in the +buffer. (Added in 7.4.2) +.TP +.B CURLOPT_PASSWDDATA +Pass a void * to whatever data you want. The passed pointer will be the first +argument sent to the specifed \fICURLOPT_PASSWDFUNCTION\fP function. (Added in +7.4.2) +.TP +.B CURLOPT_HEADERFUNCTION +Function pointer that should match the following prototype: \fIsize_t +function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This +function gets called by libcurl as soon as there is received header data that +needs to be written down. The headers are guaranteed to be written one-by-one +and only complete lines are written. Parsing headers should be easy enough +using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP +multiplied with \fInmemb\fP. The pointer named \fIstream\fP will be the one +you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the +number of bytes actually written or return -1 to signal error to the library +(it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return +code). (Added in 7.7.2) +.TP +.B CURLOPT_WRITEHEADER +Pass a pointer to be used to write the header part of the received data to. If +you don't use your own callback to take care of the writing, this must be a +valid FILE *. See also the \fICURLOPT_HEADERFUNCTION\fP option below on how to +set a custom get-all-headers callback. +.TP +.B CURLOPT_DEBUGFUNCTION +Function pointer that should match the following prototype: \fIint +curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP +This function will receive debug information if CURLOPT_VERBOSE is +enabled. The curl_infotype argument specifies what kind of information it +is. This funtion must return 0. +.TP +.B CURLOPT_DEBUGDATA +Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in +the last void * argument. This pointer is not used by libcurl, it is only +passed to the callback. +.PP +.SH ERROR OPTIONS +.TP 0.4i +.B CURLOPT_ERRORBUFFER +Pass a char * to a buffer that the libcurl may store human readable error +messages in. This may be more helpful than just the return code from the +library. The buffer must be at least CURL_ERROR_SIZE big. + +Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better +debug/trace why errors happen. + +\fBNote:\fP if the library does not return an error, the buffer may not have +been touched. Do not rely on the contents in those cases. +.TP +.B CURLOPT_STDERR +Pass a FILE * as parameter. This is the stream to use instead of stderr +internally when reporting errors. .TP +.B CURLOPT_FAILONERROR +A non-zero parameter tells the library to fail silently if the HTTP code +returned is equal to or larger than 300. The default action would be to return +the page normally, ignoring that code. +.PP +.SH NETWORK OPTIONS +.TP 0.4i .B CURLOPT_URL The actual URL to deal with. The parameter should be a char * to a zero terminated string. The string must remain present until curl no longer needs @@ -121,67 +235,41 @@ you tunnel through the HTTP proxy. Such tunneling is activated with Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. .TP +.B CURLOPT_PROXTYPE +Pass a long with this option to set type of the proxy. Available options for +this are CURLPROXY_HTTP and CURLPROXY_SOCKS5, with the HTTP one being +default. (Added in 7.10) +.TP .B CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations through a given HTTP proxy. Note that 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. (Added in 7.3) .TP -.B CURLOPT_VERBOSE -Set the parameter to non-zero to get the library to display a lot of verbose -information about its operations. Very useful for libcurl and/or protocol -debugging and understanding. - -You hardly ever want this set in production use, you will almost always want -this when you debug/report problems. -.TP -.B CURLOPT_HEADER -A non-zero parameter tells the library to include the header in the body -output. This is only relevant for protocols that actually have headers -preceding the data (like HTTP). -.TP -.B CURLOPT_NOPROGRESS -A non-zero parameter tells the library to shut of the built-in progress meter -completely. - -\fBNOTE:\fP future versions of libcurl is likely to not have any built-in -progress meter at all. -.TP -.B CURLOPT_NOBODY -A non-zero parameter tells the library to not include the body-part in the -output. This is only relevant for protocols that have separate header and body -parts. -.TP -.B CURLOPT_FAILONERROR -A non-zero parameter tells the library to fail silently if the HTTP code -returned is equal to or larger than 300. The default action would be to return -the page normally, ignoring that code. -.TP -.B CURLOPT_UPLOAD -A non-zero parameter tells the library to prepare for an upload. The -CURLOPT_INFILE and CURLOPT_INFILESIZE are also interesting for uploads. -.TP -.B CURLOPT_POST -A non-zero parameter tells the library to do a regular HTTP post. This is a -normal application/x-www-form-urlencoded kind, which is the most commonly used -one by HTML forms. See the CURLOPT_POSTFIELDS option for how to specify the -data to post and CURLOPT_POSTFIELDSIZE in how to set the data size. Starting -with libcurl 7.8, this option is obsolete. Using the CURLOPT_POSTFIELDS option -will imply this option. +.B 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 +name. (Added in 7.3) .TP -.B CURLOPT_FTPLISTONLY -A non-zero parameter tells the library to just list the names of an ftp -directory, instead of doing a full directory listing that would include file -sizes, dates etc. - -This causes an FTP NLST command to be sent. Beware that some FTP servers -list only files in their response to NLST; they do not include -subdirectories and symbolic links. +.B CURLOPT_DNS_CACHE_TIMEOUT +Pass a long, this sets the timeout in seconds. Name resolves will be kept in +memory for this number of seconds. Set to zero (0) to completely disable +caching, or set to -1 to make the cached entries remain forever. By default, +libcurl caches info for 60 seconds. (Added in 7.9.3) .TP -.B CURLOPT_FTPAPPEND -A non-zero parameter tells the library to append to the remote file instead of -overwrite it. This is only useful when uploading to a ftp site. +.B CURLOPT_DNS_USE_GLOBAL_CACHE +Pass a long. If the value is non-zero, it tells curl to use a global DNS cache +that will survive between easy handle creations and deletions. This is not +thread-safe and this will use a global varible. (Added in 7.9.3) .TP +.B CURLOPT_BUFFERSIZE +Pass a long specifying your prefered size for the receive buffer in libcurl. +The main point of this would be that the write callback gets called more often +and with smaller chunks. This is just treated as a request, not an order. You +cannot be guaranteed to actually get the given size. (Added in 7.10) +.PP +.SH NAMES and PASSWORDS OPTIONS +.TP 0.4i .B CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and passwords from your \fI~/.netrc\fP file, relative to user names and passwords @@ -221,6 +309,19 @@ Only machine name, user name and password are taken into account set (as the standard Unix ftp client does). It should only be readable by user. .TP +.B CURLOPT_USERPWD +Pass a char * as parameter, which should be [user name]:[password] to use for +the connection. If the password is left out, you will be prompted for it. +\fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +.TP +.B CURLOPT_PROXYUSERPWD +Pass a char * as parameter, which should be [user name]:[password] to use for +the connection to the HTTP proxy. If the password is left out, you will be +prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own +prompt function. +.PP +.SH HTTP OPTIONS +.TP 0.4i .B CURLOPT_FOLLOWLOCATION A non-zero parameter tells the library to follow any Location: header that the server sends as part of a HTTP header. @@ -230,54 +331,23 @@ new location and follow new Location: headers all the way until no more such headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects libcurl will follow. .TP -.B CURLOPT_TRANSFERTEXT -A non-zero parameter tells the library to use ASCII mode for ftp transfers, -instead of the default binary transfer. For LDAP transfers it gets the data in -plain text instead of HTML and 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 or -similar. +.B CURLOPT_MAXREDIRS +Pass a long. The set number will be the redirection limit. If that many +redirections have been followed, the next redirect will cause an error +(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the +\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. (Added in 7.5) .TP .B CURLOPT_PUT A non-zero parameter tells the library to use HTTP PUT to transfer data. The -data should be set with CURLOPT_INFILE and CURLOPT_INFILESIZE. -.TP -.B CURLOPT_USERPWD -Pass a char * as parameter, which should be [user name]:[password] to use for -the connection. If the password is left out, you will be prompted for it. -\fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +data should be set with CURLOPT_READDATA and CURLOPT_INFILESIZE. .TP -.B CURLOPT_PROXYUSERPWD -Pass a char * as parameter, which should be [user name]:[password] to use for -the connection to the HTTP proxy. If the password is left out, you will be -prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own -prompt function. -.TP -.B CURLOPT_RANGE -Pass a char * as parameter, which should contain the specified range you -want. It should be in the format "X-Y", where X or Y may be left out. HTTP -transfers also support several intervals, separated with commas as in -\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP -server to send the response document in pieces (using standard MIME separation -techniques). -.TP -.B CURLOPT_ERRORBUFFER -Pass a char * to a buffer that the libcurl may store human readable error -messages in. This may be more helpful than just the return code from the -library. The buffer must be at least CURL_ERROR_SIZE big. - -\fBNote:\fP if the library does not return an error, the buffer may not have -been touched. Do not rely on the contents in those cases. -.TP -.B CURLOPT_TIMEOUT -Pass a long as parameter containing the maximum time in seconds that you allow -the libcurl transfer operation to take. Normally, name lookups can take a -considerable time and limiting operations to less than a few minutes risk -aborting perfectly normal operations. This option will cause curl to use the -SIGALRM to enable time-outing system calls. - -\fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as -it uses signals unless CURLOPT_NOSIGNAL (see below) is set. +.B CURLOPT_POST +A non-zero parameter tells the library to do a regular HTTP post. This is a +normal application/x-www-form-urlencoded kind, which is the most commonly used +one by HTML forms. See the CURLOPT_POSTFIELDS option for how to specify the +data to post and CURLOPT_POSTFIELDSIZE in how to set the data size. Starting +with libcurl 7.8, this option is obsolete. Using the CURLOPT_POSTFIELDS option +will imply this option. .TP .B CURLOPT_POSTFIELDS Pass a char * as parameter, which should be the full data to post in a HTTP @@ -295,6 +365,15 @@ you can post fully binary data, which otherwise is likely to fail. If this size is set to zero, the library will use strlen() to get the size. (Added in libcurl 7.2) .TP +.B 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 HTTP post structs as parameter. The linked list should be a fully valid +list of 'struct HttpPost' structs properly filled in. The best and most +elegant way to do this, 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. +.TP .B CURLOPT_REFERER Pass a pointer to a zero terminated string as parameter. It will be used to set the Referer: header in the http request sent to the remote server. This @@ -307,41 +386,6 @@ set the User-Agent: header in the http request sent to the remote server. This can be used to fool servers or scripts. You can also set any custom header with \fICURLOPT_HTTPHEADER\fP. .TP -.B 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 -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 -address. Default FTP operations are passive, and thus won't use PORT. -.TP -.B CURLOPT_LOW_SPEED_LIMIT -Pass a long as parameter. It contains the transfer speed in bytes per second -that the transfer should be below during CURLOPT_LOW_SPEED_TIME seconds for -the library to consider it too slow and abort. -.TP -.B CURLOPT_LOW_SPEED_TIME -Pass a long as parameter. It contains the time in seconds that the transfer -should be below the CURLOPT_LOW_SPEED_LIMIT for the library to consider it too -slow and abort. -.TP -.B CURLOPT_RESUME_FROM -Pass a long as parameter. It contains the offset in number of bytes that you -want the transfer to start from. -.TP -.B CURLOPT_COOKIE -Pass a pointer to a zero terminated string as parameter. It will be used to -set a cookie in the http request. The format of the string should be -NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie -should contain. - -If you need to set mulitple cookies, you need to set them all using a single -option and thus you need to concat them all in one single string. Set multiple -cookies in one string like this: "name1=content1; name2=content2;" etc. - -Using this option multiple times will only make the latest string override the -previously ones. -.TP .B CURLOPT_HTTPHEADER Pass a pointer to a linked list of HTTP headers to pass to the server in your HTTP request. The linked list should be a fully valid list of \fBstruct @@ -356,79 +400,85 @@ new headers, replace internal headers and remove internal headers. \fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. .TP -.B 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 HTTP post structs as parameter. The linked list should be a fully valid -list of 'struct HttpPost' structs properly filled in. The best and most -elegant way to do this, is to use \fIcurl_formadd(3)\fP as documented. The -data in this list must remained intact until you close this curl handle again -with \fIcurl_easy_cleanup(3)\fP. -.TP -.B CURLOPT_SSLCERT -Pass a pointer to a zero terminated string as parameter. The string should be -the file name of your certificate. The default format is "PEM" and can be -changed with \fICURLOPT_SSLCERTTYPE\fP. -.TP -.B CURLOPT_SSLCERTTYPE -Pass a pointer to a zero terminated string as parameter. The string should be -the format of your certificate. Supported formats are "PEM" and "DER". (Added -in 7.9.3) +.B CURLOPT_COOKIE +Pass a pointer to a zero terminated string as parameter. It will be used to +set a cookie in the http request. The format of the string should be +NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie +should contain. + +If you need to set mulitple cookies, you need to set them all using a single +option and thus you need to concat them all in one single string. Set multiple +cookies in one string like this: "name1=content1; name2=content2;" etc. + +Using this option multiple times will only make the latest string override the +previously ones. .TP -.B CURLOPT_SSLCERTPASSWD -Pass a pointer to a zero terminated string as parameter. It will be used as -the password required to use the CURLOPT_SSLCERT certificate. If the password -is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can -be used to set your own prompt function. +.B CURLOPT_COOKIEFILE +Pass a pointer to a zero terminated string as parameter. It should contain the +name of your file holding cookie data to read. The cookie data may be in +Netscape / Mozilla cookie data format or just regular HTTP-style headers +dumped to a file. -\fBNOTE:\fPThis option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and only -cept for backward compatibility. You never needed a pass phrase to load -a certificate but you need one to load your private key. +Given an empty or non-existing file, this option will enable cookies for this +curl handle, making it understand and parse received cookies and then use +matching cookies in future request. .TP -.B CURLOPT_SSLKEY -Pass a pointer to a zero terminated string as parameter. The string should be -the file name of your private key. The default format is "PEM" and can be -changed with \fICURLOPT_SSLKEYTYPE\fP. (Added in 7.9.3) +.B CURLOPT_COOKIEJAR +Pass a file name as char *, zero terminated. This will make libcurl write all +internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP +is called. If no cookies are known, no file will be created. Specify "-" to +instead have the cookies written to stdout. Using this option also enables +cookies for this session, so if you for example follow a location it will make +matching cookies get sent accordingly. (Added in 7.9) .TP -.B CURLOPT_SSLKEYTYPE -Pass a pointer to a zero terminated string as parameter. The string should be -the format of your private key. Supported formats are "PEM", "DER" and "ENG". -(Added in 7.9.3) - -\fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto -engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to -the engine. You have to set the crypto engine with \fICURLOPT_SSL_ENGINE\fP. +.B CURLOPT_TIMECONDITION +Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE time value is +treated. You can set this parameter to TIMECOND_IFMODSINCE or +TIMECOND_IFUNMODSINCE. This is a HTTP-only feature. (TBD) .TP -.B CURLOPT_SSLKEYPASSWD -Pass a pointer to a zero terminated string as parameter. It will be used as -the password required to use the \fICURLOPT_SSLKEY\fP private key. If the -password is not supplied, you will be prompted for -it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. -(Added in 7.9.3) +.B CURLOPT_TIMEVALUE +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 +CURLOPT_TIMECONDITION. .TP -.B CURLOPT_SSL_ENGINE -Pass a pointer to a zero terminated string as parameter. It will be used as -the identifier for the crypto engine you want to use for your private -key. (Added in 7.9.3) - -\fBNOTE:\fPIf the crypto device cannot be loaded, -\fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. +.B CURLOPT_HTTPGET +Pass a long. If the long is non-zero, this forces the HTTP request to get back +to GET. Only really usable if POST, PUT or a custom request have been used +previously using the same curl handle. (Added in 7.8.1) .TP -.B CURLOPT_SSL_ENGINEDEFAULT -Sets the actual crypto engine as the default for (asymetric) crypto -operations. (Added in 7.9.3) - -\fBNOTE:\fPIf the crypto device cannot be set, -\fICURLE_SSL_ENGINE_SETFAILED\fP is returned. +.B CURLOPT_HTTP_VERSION +Pass a long, set to one of the values described below. They force libcurl to +use the specific HTTP versions. This is not sensible to do unless you have a +good reason. +.RS +.TP 5 +.B CURL_HTTP_VERSION_NONE +We don't care about what version the library uses. libcurl will use whatever +it thinks fit. .TP -.B CURLOPT_CRLF -Convert Unix newlines to CRLF newlines on FTP uploads. +.B CURL_HTTP_VERSION_1_0 +Enforce HTTP 1.0 requests. +.TP +.B CURL_HTTP_VERSION_1_1 +Enforce HTTP 1.1 requests. +.RE +.PP +.SH FTP OPTIONS +.TP 0.4i +.B 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 +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 +address. Default FTP operations are passive, and thus won't use PORT. .TP .B CURLOPT_QUOTE Pass a pointer to a linked list of FTP commands to pass to the server prior to -your ftp request. The linked list should be a fully valid list of 'struct -curl_slist' structs properly filled in. Use \fIcurl_slist_append(3)\fP to -append strings (commands) to the list, and clear the entire list afterwards +your ftp request. This will be done before any other FTP commands are issued +(even before the CWD command). The linked list should be a fully valid list of +'struct curl_slist' structs properly filled in. Use \fIcurl_slist_append(3)\fP +to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL to this option. .TP @@ -439,49 +489,56 @@ struct curl_slist structs properly filled in as described for \fICURLOPT_QUOTE\fP. Disable this operation again by setting a NULL to this option. .TP -.B CURLOPT_WRITEHEADER -Pass a pointer to be used to write the header part of the received data to. If -you don't use your own callback to take care of the writing, this must be a -valid FILE *. See also the \fICURLOPT_HEADERFUNCTION\fP option below on how to set a -custom get-all-headers callback. -.TP -.B CURLOPT_HEADERFUNCTION -Function pointer that should match the following prototype: \fIsize_t -function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This -function gets called by libcurl as soon as there is received header data that -needs to be written down. The headers are guaranteed to be written one-by-one -and only complete lines are written. Parsing headers should be easy enough -using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP -multiplied with \fInmemb\fP. The pointer named \fIstream\fP will be the one -you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the -number of bytes actually written or return -1 to signal error to the library -(it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return -code). (Added in 7.7.2) +.B CURLOPT_PREQUOTE +Pass a pointer to a linked list of FTP commands to pass to the server after +the transfer type is set. 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. .TP -.B CURLOPT_COOKIEFILE -Pass a pointer to a zero terminated string as parameter. It should contain the -name of your file holding cookie data. The cookie data may be in Netscape / -Mozilla cookie data format or just regular HTTP-style headers dumped to a -file. +.B CURLOPT_FTPLISTONLY +A non-zero parameter tells the library to just list the names of an ftp +directory, instead of doing a full directory listing that would include file +sizes, dates etc. -Given an empty or non-existing file, this option will only enable cookies for -this curl handle, making it understand and parse received cookies and then use -matching cookies in future request. +This causes an FTP NLST command to be sent. Beware that some FTP servers list +only files in their response to NLST; they might not include subdirectories +and symbolic links. .TP -.B CURLOPT_SSLVERSION -Pass a long as parameter. Set what version of SSL to attempt to use, 2 or -3. By default, the SSL library will try to solve this by itself although some -servers make this difficult why you at times may have to use this option. +.B CURLOPT_FTPAPPEND +A non-zero parameter tells the library to append to the remote file instead of +overwrite it. This is only useful when uploading to a ftp site. .TP -.B CURLOPT_TIMECONDITION -Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE time value is -treated. You can set this parameter to TIMECOND_IFMODSINCE or -TIMECOND_IFUNMODSINCE. This is a HTTP-only feature. (TBD) +.B CURLOPT_FTP_USE_EPSV +Pass a long. If the value is non-zero, it tells curl to use the EPSV command +when doing passive FTP downloads (which it always does by default). Using EPSV +means that it will first attempt to use EPSV before using PASV, but if you +pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. +.PP +.SH PROTOCOL OPTIONS +.TP 0.4i +.B CURLOPT_TRANSFERTEXT +A non-zero parameter tells the library to use ASCII mode for ftp transfers, +instead of the default binary transfer. For LDAP transfers it gets the data in +plain text instead of HTML and 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 or +similar. .TP -.B CURLOPT_TIMEVALUE -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 -CURLOPT_TIMECONDITION. +.B CURLOPT_CRLF +Convert Unix newlines to CRLF newlines on transfers. +.TP +.B CURLOPT_RANGE +Pass a char * as parameter, which should contain the specified range you +want. It should be in the format "X-Y", where X or Y may be left out. HTTP +transfers also support several intervals, separated with commas as in +\fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP +server to send the response document in pieces (using standard MIME separation +techniques). +.TP +.B CURLOPT_RESUME_FROM +Pass a long as parameter. It contains the offset in number of bytes that you +want the transfer to start from. .TP .B CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user @@ -489,74 +546,6 @@ instead of GET or HEAD when doing the HTTP request. 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. .TP -.B CURLOPT_STDERR -Pass a FILE * as parameter. This is the stream to use instead of stderr -internally when reporting errors. -.TP -.B 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 -name. (Added in 7.3) -.TP -.B CURLOPT_KRB4LEVEL -Pass a char * as parameter. Set the krb4 security level, this also enables -krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or -\&'private'. If the string is set but doesn't match one of these, 'private' -will be used. Set the string to NULL to disable kerberos4. The kerberos -support only works for FTP. (Added in 7.3) -.TP -.B CURLOPT_PROGRESSFUNCTION -Function pointer that should match the \fIcurl_progress_callback\fP prototype -found in \fI\fP. This function gets called by libcurl instead of -its internal equivalent with a frequent interval during data transfer. -Unknown/unused argument values will be set to zero (like if you only download -data, the upload size will remain 0). Returning a non-zero value from this -callback will cause libcurl to abort the transfer and return -\fICURLE_ABORTED_BY_CALLBACK\fP. - -Also note that \fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this -function actually get called. -.TP -.B CURLOPT_PROGRESSDATA -Pass a pointer that will be untouched by libcurl and passed as the first -argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. -.TP -.B CURLOPT_SSL_VERIFYPEER -Pass a long that is set to a non-zero value to make curl verify the peer's -certificate. The certificate to verify against must be specified with the -CURLOPT_CAINFO option (Added in 7.4.2) or a certificate directory must be specified -with the CURLOPT_CAPATH option (Added in 7.9.8). -.TP -.B CURLOPT_CAINFO -Pass a char * to a zero terminated string naming a file holding one or more -certificates to verify the peer with. This only makes sense when used in -combination with the CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2) -.TP -.B CURLOPT_CAPATH -Pass a char * to a zero terminated string naming a directory holding multiple CA -certificates to verify the peer with. The certificate directory must be prepared using -the openssl c_rehash utility. This only makes sense when used in combination with the -CURLOPT_SSL_VERIFYPEER option. The CAPATH function apparently does not work in Windows -due to some limitation in openssl. (Added in 7.9.8) -.TP -.B CURLOPT_PASSWDFUNCTION -Pass a pointer to a \fIcurl_passwd_callback\fP function that will be called -instead of the internal one if libcurl requests a password. The function must -match this prototype: \fBint my_getpass(void *client, char *prompt, char* -buffer, int buflen );\fP. If set to NULL, it sets back the function to the -internal default one. If the function returns a non-zero value, it will abort -the operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned. -\fIclient\fP is a generic pointer, see \fICURLOPT_PASSWDDATA\fP. \fIprompt\fP -is a zero-terminated string that is text that prefixes the input request. -\fIbuffer\fP is a pointer to data where the entered password should be stored -and \fIbuflen\fP is the maximum number of bytes that may be written in the -buffer. (Added in 7.4.2) -.TP -.B CURLOPT_PASSWDDATA -Pass a void * to whatever data you want. The passed pointer will be the first -argument sent to the specifed \fICURLOPT_PASSWDFUNCTION\fP function. (Added in -7.4.2) -.TP .B CURLOPT_FILETIME Pass a long. If it is a non-zero value, libcurl will attempt to get the modification date of the remote document in this operation. This requires that @@ -565,11 +554,40 @@ the remote server sends the time or replies to a time querying command. The can be used after a transfer to extract the received time (if any). (Added in 7.5) .TP -.B CURLOPT_MAXREDIRS -Pass a long. The set number will be the redirection limit. If that many -redirections have been followed, the next redirect will cause an error -(\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the -\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. (Added in 7.5) +.B CURLOPT_NOBODY +A non-zero parameter tells the library to not include the body-part in the +output. This is only relevant for protocols that have separate header and body +parts. +.TP +.B CURLOPT_INFILESIZE +When uploading a file to a remote site, this option should be used to tell +libcurl what the expected size of the infile is. +.TP +.B CURLOPT_UPLOAD +A non-zero parameter tells the library to prepare for an upload. The +CURLOPT_READDATA and CURLOPT_INFILESIZE are also interesting for uploads. +.PP +.SH CONNECTION OPTIONS +.TP 0.4i +.B CURLOPT_TIMEOUT +Pass a long as parameter containing the maximum time in seconds that you allow +the libcurl transfer operation to take. Normally, name lookups can take a +considerable time and limiting operations to less than a few minutes risk +aborting perfectly normal operations. This option will cause curl to use the +SIGALRM to enable time-outing system calls. + +\fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as +it uses signals unless CURLOPT_NOSIGNAL (see below) is set. +.TP +.B CURLOPT_LOW_SPEED_LIMIT +Pass a long as parameter. It contains the transfer speed in bytes per second +that the transfer should be below during CURLOPT_LOW_SPEED_TIME seconds for +the library to consider it too slow and abort. +.TP +.B CURLOPT_LOW_SPEED_TIME +Pass a long as parameter. It contains the time in seconds that the transfer +should be below the CURLOPT_LOW_SPEED_LIMIT for the library to consider it too +slow and abort. .TP .B CURLOPT_MAXCONNECTS Pass a long. The set number will be the persistent connection cache size. The @@ -614,15 +632,6 @@ 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 re-use (default behavior). (Added in 7.7) .TP -.B CURLOPT_RANDOM_FILE -Pass a char * to a zero terminated file name. The file will be used to read -from to seed the random engine for SSL. The more random the specified file is, -the more secure the SSL connection will become. -.TP -.B CURLOPT_EGDSOCKET -Pass a char * to the zero terminated path name to the Entropy Gathering Daemon -socket. It will be used to seed the random engine for SSL. -.TP .B CURLOPT_CONNECTTIMEOUT Pass a long. It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once @@ -632,27 +641,103 @@ timeouts). See also the \fICURLOPT_TIMEOUT\fP option. \fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as it uses signals unless CURLOPT_NOSIGNAL (see below) is set. +.PP +.SH SSL and SECURITY OPTIONS +.TP 0.4i +.B CURLOPT_SSLCERT +Pass a pointer to a zero terminated string as parameter. The string should be +the file name of your certificate. The default format is "PEM" and can be +changed with \fICURLOPT_SSLCERTTYPE\fP. .TP -.B CURLOPT_HTTPGET -Pass a long. If the long is non-zero, this forces the HTTP request to get back -to GET. Only really usable if POST, PUT or a custom request have been used -previously using the same curl handle. (Added in 7.8.1) +.B CURLOPT_SSLCERTTYPE +Pass a pointer to a zero terminated string as parameter. The string should be +the format of your certificate. Supported formats are "PEM" and "DER". (Added +in 7.9.3) +.TP +.B CURLOPT_SSLCERTPASSWD +Pass a pointer to a zero terminated string as parameter. It will be used as +the password required to use the CURLOPT_SSLCERT certificate. If the password +is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can +be used to set your own prompt function. + +\fBNOTE:\fPThis option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and only +cept for backward compatibility. You never needed a pass phrase to load +a certificate but you need one to load your private key. +.TP +.B CURLOPT_SSLKEY +Pass a pointer to a zero terminated string as parameter. The string should be +the file name of your private key. The default format is "PEM" and can be +changed with \fICURLOPT_SSLKEYTYPE\fP. (Added in 7.9.3) +.TP +.B CURLOPT_SSLKEYTYPE +Pass a pointer to a zero terminated string as parameter. The string should be +the format of your private key. Supported formats are "PEM", "DER" and "ENG". +(Added in 7.9.3) + +\fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto +engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to +the engine. You have to set the crypto engine with \fICURLOPT_SSL_ENGINE\fP. +.TP +.B CURLOPT_SSLKEYPASSWD +Pass a pointer to a zero terminated string as parameter. It will be used as +the password required to use the \fICURLOPT_SSLKEY\fP private key. If the +password is not supplied, you will be prompted for +it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +(Added in 7.9.3) +.TP +.B CURLOPT_SSL_ENGINE +Pass a pointer to a zero terminated string as parameter. It will be used as +the identifier for the crypto engine you want to use for your private +key. (Added in 7.9.3) + +\fBNOTE:\fPIf the crypto device cannot be loaded, +\fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. +.TP +.B CURLOPT_SSL_ENGINEDEFAULT +Sets the actual crypto engine as the default for (asymetric) crypto +operations. (Added in 7.9.3) + +\fBNOTE:\fPIf the crypto device cannot be set, +\fICURLE_SSL_ENGINE_SETFAILED\fP is returned. +.TP +.B CURLOPT_SSLVERSION +Pass a long as parameter. Set what version of SSL to attempt to use, 2 or +3. By default, the SSL library will try to solve this by itself although some +servers make this difficult why you at times may have to use this option. +.TP +.B CURLOPT_SSL_VERIFYPEER +Pass a long that is set to a non-zero value to make curl verify the peer's +certificate. The certificate to verify against must be specified with the +CURLOPT_CAINFO option (Added in 7.4.2) or a certificate directory must be specified +with the CURLOPT_CAPATH option (Added in 7.9.8). +.TP +.B CURLOPT_CAINFO +Pass a char * to a zero terminated string naming a file holding one or more +certificates to verify the peer with. This only makes sense when used in +combination with the CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2) +.TP +.B CURLOPT_CAPATH +Pass a char * to a zero terminated string naming a directory holding multiple +CA certificates to verify the peer with. The certificate directory must be +prepared using the openssl c_rehash utility. This only makes sense when used +in combination with the CURLOPT_SSL_VERIFYPEER option. The CAPATH function +apparently does not work in Windows due to some limitation in openssl. (Added +in 7.9.8) +.TP +.B CURLOPT_RANDOM_FILE +Pass a char * to a zero terminated file name. The file will be used to read +from to seed the random engine for SSL. The more random the specified file is, +the more secure the SSL connection will become. +.TP +.B CURLOPT_EGDSOCKET +Pass a char * to the zero terminated path name to the Entropy Gathering Daemon +socket. It will be used to seed the random engine for SSL. .TP .B CURLOPT_SSL_VERIFYHOST Pass a long. Set if we should verify the Common name from the peer certificate in the SSL handshake, set 1 to check existence, 2 to ensure that it matches the provided hostname. (Added in 7.8.1) .TP -.B CURLOPT_COOKIEJAR -Pass a file name as char *, zero terminated. This will make libcurl dump all -internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP -is called. If no cookies are known, no file will be created. Specify "-" to -instead have the cookies written to stdout. Using this option also enables -cookies for this session, so if you for example follow a location it will make -matching cookies get sent accordingly. - -(Added in 7.9) -.TP .B 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 syntactly correct, it @@ -665,64 +750,12 @@ compile OpenSSL. You'll find more details about cipher lists on this URL: \fIhttp://www.openssl.org/docs/apps/ciphers.html\fP .TP -.B CURLOPT_HTTP_VERSION -Pass a long, set to one of the values described below. They force libcurl to -use the specific HTTP versions. This is not sensible to do unless you have a -good reason. -.RS -.TP 5 -.B CURL_HTTP_VERSION_NONE -We don't care about what version the library uses. libcurl will use whatever -it thinks fit. -.TP -.B CURL_HTTP_VERSION_1_0 -Enforce HTTP 1.0 requests. -.TP -.B CURL_HTTP_VERSION_1_1 -Enforce HTTP 1.1 requests. -.RE -.TP -.B CURLOPT_FTP_USE_EPSV -Pass a long. If the value is non-zero, it tells curl to use the EPSV command -when doing passive FTP downloads (which it always does by default). Using EPSV -means that it will first attempt to use EPSV before using PASV, but if you -pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. -.TP -.B CURLOPT_DNS_CACHE_TIMEOUT -Pass a long, this sets the timeout in seconds. Name resolves will be kept in -memory for this number of seconds. Set to zero (0) to completely disable -caching, or set to -1 to make the cached entries remain forever. By default, -libcurl caches info for 60 seconds. (Added in 7.9.3) -.TP -.B CURLOPT_DNS_USE_GLOBAL_CACHE -Pass a long. If the value is non-zero, it tells curl to use a global DNS cache -that will survive between easy handle creations and deletions. This is not -thread-safe and this will use a global varible. (Added in 7.9.3) -.TP -.B CURLOPT_DEBUGFUNCTION -Function pointer that should match the following prototype: \fIint -curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP -This function will receive debug information if CURLOPT_VERBOSE is -enabled. The curl_infotype argument specifies what kind of information it -is. This funtion must return 0. -.TP -.B CURLOPT_DEBUGDATA -Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in -the last void * argument. This pointer is not used by libcurl, it is only -passed to the callback. -.TP -.B CURLOPT_BUFFERSIZE -Pass a long specifying your prefered size for the receive buffer in libcurl. -The main point of this would be that the write callback gets called more often -and with smaller chunks. This is just treated as a request, not an order. You -cannot be guaranteed to actually get the given size. (Added in 7.10) -.TP -.B CURLOPT_NOSIGNAL -Pass a long. If it is non-zero, libcurl will not use any functions that -install signal handlers or any functions that cause signals to be sent to the -process. This option is mainly here to allow multi-threaded unix applications -to still set/use all timeout options etc, without risking getting signals. -(Added in 7.10) +.B CURLOPT_KRB4LEVEL +Pass a char * as parameter. Set the krb4 security level, this also enables +krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or +\&'private'. If the string is set but doesn't match one of these, 'private' +will be used. Set the string to NULL to disable kerberos4. The kerberos +support only works for FTP. (Added in 7.3) .PP .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an -- cgit v1.2.1 From 24e703682233aa333899a3c507442f05e2fe7de7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 Sep 2002 12:11:12 +0000 Subject: Walter J. Mack's curl_free addition --- docs/libcurl/curl_escape.3 | 52 +++++++++++++++++++++--------------------- docs/libcurl/curl_free.3 | 17 ++++++++++++++ docs/libcurl/curl_unescape.3 | 54 ++++++++++++++++++++++---------------------- 3 files changed, 70 insertions(+), 53 deletions(-) create mode 100644 docs/libcurl/curl_free.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index ba81303c5..395363e64 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -1,26 +1,26 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ -.\" -.TH curl_escape 3 "6 March 2002" "libcurl 7.9" "libcurl Manual" -.SH NAME -curl_escape - URL encodes the given string -.SH SYNOPSIS -.B #include -.sp -.BI "char *curl_escape( char *" url ", int "length " );" -.ad -.SH DESCRIPTION -This function will convert the given input string to an URL encoded string and -return that as a new allocated string. All input characters that are not a-z, -A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a -two-digit hexadecimal number). - -If the 'length' argument is set to 0, curl_escape() will use strlen() on the -input 'url' string to find out the size. - -You must free() the returned string when you're done with it. -.SH RETURN VALUE -A pointer to a zero terminated string or NULL if it failed. -.SH "SEE ALSO" -.I curl_unescape(), RFC 2396 +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_escape 3 "6 March 2002" "libcurl 7.9" "libcurl Manual" +.SH NAME +curl_escape - URL encodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_escape( char *" url ", int "length " );" +.ad +.SH DESCRIPTION +This function will convert the given input string to an URL encoded string and +return that as a new allocated string. All input characters that are not a-z, +A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a +two-digit hexadecimal number). + +If the 'length' argument is set to 0, curl_escape() will use strlen() on the +input 'url' string to find out the size. + +You must curl_free() the returned string when you're done with it. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.I curl_unescape(), curl_free(), RFC 2396 diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 new file mode 100644 index 000000000..718b86e28 --- /dev/null +++ b/docs/libcurl/curl_free.3 @@ -0,0 +1,17 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id: +.\" +.TH curl_free 3 "24 Sept 2002" "libcurl 7.10" "libcurl Manual" +.SH NAME +curl_free - reclaim memory that has been obtained through a libcurl call +.SH SYNOPSIS +.B #include +.sp +.BI "void *curl_free( char *" ptr " );" +.ad +.SH DESCRIPTION +curl_free reclaims memory that has been obtained through a libcurl call. +Use curl_free() instead of free() to avoid anomalies that can result from differences in memory management between your application and libcurl. +.SH "SEE ALSO" +.I curl_unescape(), curl_free() diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index 756ab45ac..5432d5e1b 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -1,27 +1,27 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ -.\" -.TH curl_unescape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" -.SH NAME -curl_unescape - URL decodes the given string -.SH SYNOPSIS -.B #include -.sp -.BI "char *curl_unescape( char *" url ", int "length " );" -.ad -.SH DESCRIPTION -This function will convert the given URL encoded input string to a "plain -string" and return that as a new allocated string. All input characters that -are URL encoded (%XX where XX is a two-digit hexadecimal number, or +) will be -converted to their plain text versions (up to a ? letter, no + letters to the -right of a ? letter will be converted). - -If the 'length' argument is set to 0, curl_unescape() will use strlen() on the -input 'url' string to find out the size. - -You must free() the returned string when you're done with it. -.SH RETURN VALUE -A pointer to a zero terminated string or NULL if it failed. -.SH "SEE ALSO" -.I curl_escape(), RFC 2396 +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_unescape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" +.SH NAME +curl_unescape - URL decodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_unescape( char *" url ", int "length " );" +.ad +.SH DESCRIPTION +This function will convert the given URL encoded input string to a "plain +string" and return that as a new allocated string. All input characters that +are URL encoded (%XX where XX is a two-digit hexadecimal number, or +) will be +converted to their plain text versions (up to a ? letter, no + letters to the +right of a ? letter will be converted). + +If the 'length' argument is set to 0, curl_unescape() will use strlen() on the +input 'url' string to find out the size. + +You must curl_free() the returned string when you're done with it. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.I curl_escape(), curl_free(), RFC 2396 -- cgit v1.2.1 From 9de4b99fc7c48749ab430c9fb4e20479bc935d36 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 Sep 2002 12:21:08 +0000 Subject: added curl_free --- docs/libcurl/Makefile.am | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 76c17cff1..4e549cb44 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -21,6 +21,7 @@ man_MANS = \ curl_version.3 \ curl_escape.3 \ curl_unescape.3 \ + curl_free.3 \ curl_strequal.3 \ curl_strnequal.3 \ curl_mprintf.3 \ @@ -54,6 +55,7 @@ HTMLPAGES = \ curl_version.html \ curl_escape.html \ curl_unescape.html \ + curl_free.html \ curl_strequal.html \ curl_strnequal.html \ curl_mprintf.html \ -- cgit v1.2.1 From 3fc2c813cc59eb1e2752749772a5555e9f3c82bb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 Sep 2002 12:24:46 +0000 Subject: added curl_free and an "overview" section --- docs/libcurl/index.html | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 1d2d8df19..a14679860 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -11,8 +11,12 @@ HTML>

curl-config.html

curl.html -

Library routines

+

Overviews

libcurl.html +

libcurl-multi.html +

libcurl-errors.html + +

Library routines

curl_easy_cleanup.html

curl_easy_duphandle.html

curl_easy_getinfo.html @@ -23,6 +27,7 @@ HTML>

curl_formadd.html

curl_formfree.html

curl_formparse.html +

curl_free.html

curl_getdate.html

curl_getenv.html

curl_global_cleanup.html @@ -42,7 +47,7 @@ HTML>

curl_multi_init.html

curl_multi_perform.html

curl_multi_remove_handle.html -

libcurl-multi.html + -- cgit v1.2.1 From 9247daf953bb48d19948199feb12b0031f825fa0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 26 Sep 2002 13:03:22 +0000 Subject: enhanced curl_version_info --- docs/libcurl/Makefile.am | 2 + docs/libcurl/curl_version_info.3 | 81 ++++++++++++++++++++++++++++++++++++++++ docs/libcurl/index.html | 68 ++++++++++++++++----------------- 3 files changed, 117 insertions(+), 34 deletions(-) create mode 100644 docs/libcurl/curl_version_info.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 4e549cb44..3a6c266c0 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -19,6 +19,7 @@ man_MANS = \ curl_slist_append.3 \ curl_slist_free_all.3 \ curl_version.3 \ + curl_version_info.3 \ curl_escape.3 \ curl_unescape.3 \ curl_free.3 \ @@ -53,6 +54,7 @@ HTMLPAGES = \ curl_slist_append.html \ curl_slist_free_all.html \ curl_version.html \ + curl_version_info.html \ curl_escape.html \ curl_unescape.html \ curl_free.html \ diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 new file mode 100644 index 000000000..83becb608 --- /dev/null +++ b/docs/libcurl/curl_version_info.3 @@ -0,0 +1,81 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_version_info 3 "25 Sep 2002" "libcurl 7.10" "libcurl Manual" +.SH NAME +curl_version_info - returns run-time libcurl version info +.SH SYNOPSIS +.B #include +.sp +.BI "curl_version_info_data *curl_version_info( );" +.ad +.SH DESCRIPTION +Returns a pointer to a filled in struct with information about various +run-time features in libcurl. + +Applications should use this information to judge if things are possible to do +or not, instead of using compile-time checks, as dynamic/DLL libraries can be +changed independent of applications. + +The curl_version_info_data struct looks like this + +.nf +typedef struct { + const char *version; /* human readable string */ + unsigned int version_num; /* numeric representation */ + const char *host; /* human readable string */ + int features; /* bitmask, see below */ + char *ssl_version; /* human readable string */ + long ssl_version_num; /* number */ + char *libz_version; /* human readable string */ + const char *protocols[]; /* list of protocols */ +} curl_version_info_data; +.fi + +\fIversion\fP is just an ascii string for the libcurl version. + +\fIversion_num\fP is a 6 digit hexadecimal number created like this: <2 digits +major number> | <2 digits minor number> | <2 digits patch number>. Version +7.9.8 is therefore returned as 0x070908. + +\fIhost\fP is an ascii string showing what host information that this libcurl +was built for. As discovered by a configure script or set by the build +environment. + +\fIfeatures\fP can have none, one or more bits set, and the currently defined +bits are: +.TP 5.5 +.B CURL_VERSION_IPV6 +supports IPv6 +.TP +.B CURL_VERSION_KERBEROS4 +supports kerberos4 (when using FTP) +.TP +.B CURL_VERSION_SSL +supports SSL (HTTPS/FTPS) +.TP +.B CURL_VERSION_LIBZ +supports HTTP deflate using libz +.PP +\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 +libcurl has no libz support, this is NULL. + +\fIprotocols\fP is a pointer to an array of char * pointers, containing the +names protocols that libcurl supports (using lowercase letters). The protocol +names are the same as would be used in URLs. The array is terminated by a NULL +entry. + + +.SH RETURN VALUE +A pointer to a curl_version_info_data struct. +.SH "SEE ALSO" +\fIcurl_version(3)\fP +.SH BUGS +No known bugs. diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index a14679860..a1d5f8301 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -8,46 +8,46 @@ HTML>

Index to Curl documentation

Programs

-

curl-config.html -

curl.html +

curl-config +

curl

Overviews

-

libcurl.html -

libcurl-multi.html -

libcurl-errors.html +

libcurl +

libcurl-multi +

libcurl-errors

Library routines

-

curl_easy_cleanup.html -

curl_easy_duphandle.html -

curl_easy_getinfo.html +

curl_easy_cleanup +

curl_easy_duphandle +

curl_easy_getinfo

curl_easy_init.html -

curl_easy_perform.html -

curl_easy_setopt.html -

curl_escape.html -

curl_formadd.html -

curl_formfree.html -

curl_formparse.html -

curl_free.html -

curl_getdate.html -

curl_getenv.html -

curl_global_cleanup.html -

curl_global_init.html -

curl_mprintf.html -

curl_slist_append.html -

curl_slist_free_all.html -

curl_strequal.html -

curl_strnequal.html -

curl_unescape.html -

curl_version.html +

curl_easy_perform +

curl_easy_setopt +

curl_escape +

curl_formadd +

curl_formfree +

curl_formparse +

curl_free +

curl_getdate +

curl_getenv +

curl_global_cleanup +

curl_global_init +

curl_mprintf +

curl_slist_append +

curl_slist_free_all +

curl_strequal +

curl_strnequal +

curl_unescape +

curl_version +

curl_version_info

-

curl_multi_add_handle.html -

curl_multi_cleanup.html -

curl_multi_fdset.html -

curl_multi_info_read.html -

curl_multi_init.html -

curl_multi_perform.html -

curl_multi_remove_handle.html - +

curl_multi_add_handle +

curl_multi_cleanup +

curl_multi_fdset +

curl_multi_info_read +

curl_multi_init +

curl_multi_perform +

curl_multi_remove_handle -- cgit v1.2.1 From b1579aed2fce804f2207cec237327deaf9eebd98 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 26 Sep 2002 13:03:55 +0000 Subject: fixed html tag --- docs/libcurl/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index a1d5f8301..f0195027e 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -1,4 +1,4 @@ -HTML> + Index to Curl documentation -- cgit v1.2.1 From 29d0174253d7049c1308f0af948b06d26031ffaa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 26 Sep 2002 13:12:48 +0000 Subject: nicer html --- docs/libcurl/index.html | 76 ++++++++++++++++++++++++------------------------- 1 file changed, 37 insertions(+), 39 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index f0195027e..29afbae2f 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -1,53 +1,51 @@ -Index to Curl documentation +Index to libcurl documentation -

Index to Curl documentation

+

Index to libcurl documentation

Programs

-

curl-config -

curl +

curl and tools

Overviews

-

libcurl -

libcurl-multi -

libcurl-errors +libcurl +
libcurl-multi +
libcurl-errors -

Library routines

-

curl_easy_cleanup -

curl_easy_duphandle -

curl_easy_getinfo -

curl_easy_init.html -

curl_easy_perform -

curl_easy_setopt -

curl_escape -

curl_formadd -

curl_formfree -

curl_formparse -

curl_free -

curl_getdate -

curl_getenv -

curl_global_cleanup -

curl_global_init -

curl_mprintf -

curl_slist_append -

curl_slist_free_all -

curl_strequal -

curl_strnequal -

curl_unescape -

curl_version -

curl_version_info -

-

curl_multi_add_handle -

curl_multi_cleanup -

curl_multi_fdset -

curl_multi_info_read -

curl_multi_init -

curl_multi_perform -

curl_multi_remove_handle +

Library Functions (A-Z)

+curl_easy_cleanup +
curl_easy_duphandle +
curl_easy_getinfo +
curl_easy_init +
curl_easy_perform +
curl_easy_setopt +
curl_escape +
curl_formadd +
curl_formfree +
curl_formparse +
curl_free +
curl_getdate +
curl_getenv +
curl_global_cleanup +
curl_global_init +
curl_mprintf +
curl_multi_add_handle +
curl_multi_cleanup +
curl_multi_fdset +
curl_multi_info_read +
curl_multi_init +
curl_multi_perform +
curl_multi_remove_handle +
curl_slist_append +
curl_slist_free_all +
curl_strequal +
curl_strnequal +
curl_unescape +
curl_version +
curl_version_info -- cgit v1.2.1 From 3b33540c997df1e5bda343c7cf89b7990e9a0c54 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 26 Sep 2002 13:16:08 +0000 Subject: point out more docs --- docs/libcurl/index.html | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 29afbae2f..52d11e219 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -14,6 +14,7 @@ libcurl
libcurl-multi
libcurl-errors +
libcurl-the-guide (plain text)

Library Functions (A-Z)

curl_easy_cleanup -- cgit v1.2.1 From dc9e415602c32bb575b58422f52965c5d741fda3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 30 Sep 2002 19:51:05 +0000 Subject: get an argument and add a 'age' field to the struct --- docs/libcurl/curl_version_info.3 | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 83becb608..cc14c0e59 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -2,17 +2,23 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_version_info 3 "25 Sep 2002" "libcurl 7.10" "libcurl Manual" +.TH curl_version_info 3 "30 Sep 2002" "libcurl 7.10" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS .B #include .sp -.BI "curl_version_info_data *curl_version_info( );" +.BI "curl_version_info_data *curl_version_info( CURLversion "type ");" .ad .SH DESCRIPTION Returns a pointer to a filled in struct with information about various -run-time features in libcurl. +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 +recent one for the library you have installed: + + data = curl_version_info(CURLVERSION_NOW); Applications should use this information to judge if things are possible to do or not, instead of using compile-time checks, as dynamic/DLL libraries can be @@ -22,6 +28,7 @@ The curl_version_info_data struct looks like this .nf typedef struct { + CURLversion age; /* 0 - this kind of struct */ const char *version; /* human readable string */ unsigned int version_num; /* numeric representation */ const char *host; /* human readable string */ @@ -33,6 +40,11 @@ typedef struct { } curl_version_info_data; .fi +\fIage\fP describes what kind of struct this is. It is always 0 now. In a +future libcurl, if this struct changes, this age counter may be increased, and +then the struct for number 1 will look different (except for this first struct +field). + \fIversion\fP is just an ascii string for the libcurl version. \fIversion_num\fP is a 6 digit hexadecimal number created like this: <2 digits -- cgit v1.2.1 From bb8c8d273c77df63fc783b6d2557fcb8927f59b8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 13 Oct 2002 10:18:10 +0000 Subject: added more info --- docs/libcurl/libcurl-multi.3 | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 0dc3f6216..3caa69d82 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl-multi 5 "20 March 2001" "libcurl 7.9.5" "libcurl multi interface" +.TH libcurl-multi 5 "13 Oct 2001" "libcurl 7.10.1" "libcurl multi interface" .SH NAME libcurl-multi \- how to use the multi interface .SH DESCRIPTION @@ -37,7 +37,7 @@ curl_multi_* functions. Each single transfer is built up with an easy handle. You must create them, and setup the appropriate options for each easy handle, as outlined in the -\fIlibcurl(3)\fP man page. +\fIlibcurl(3)\fP man page, using \fIcurl_easy_setopt(3)\fP. When the easy handle is setup for a transfer, then instead of using \fIcurl_easy_perform\fP (as when using the easy interface for transfers), you @@ -49,11 +49,11 @@ handles. Should you change your mind, the easy handle is again removed from the multi stack using \fIcurl_multi_remove_handle\fP. Once removed from the multi handle, you can again use other easy interface functions like -curl_easy_perform or whatever you think is necessary. +\fIcurl_easy_perform\fP on the handle or whatever you think is necessary. -Adding the easy handles to the multi handle does not start any -transfer. Remember that one of the main ideas with this interface is to let -your application drive. You drive the transfers by invoking +Adding the easy handle to the multi handle does not start the transfer. +Remember that one of the main ideas with this interface is to let your +application drive. You drive the transfers by invoking \fIcurl_multi_perform\fP. libcurl will then transfer data if there is anything available to transfer. It'll use the callbacks and everything else you have setup in the individual easy handles. It'll transfer data on all current @@ -62,24 +62,39 @@ all, it may be none. Your application can acquire knowledge from libcurl when it would like to get invoked to transfer data, so that you don't have to busy-loop and call that -\fIcurl_multi_perform\fP like a mad man! \fIcurl_multi_fdset\fP offers an +\fIcurl_multi_perform\fP like crazy. \fIcurl_multi_fdset\fP offers an interface using which you can extract fd_sets from libcurl to use in select() or poll() calls in order to get to know when the transfers in the multi stack might need attention. This also makes it very easy for your program to wait for input on your own private file descriptors at the same time or perhaps timeout every now and then, should you want that. +A little note here about the return codes from the multi functions, and +especially the \fIcurl_multi_perform\fP: if you receive +\fICURLM_CALL_MULTI_PERFORM\fP, this basicly means that you should call +\fIcurlm_call_multi_perform\fP again, before you select() on more 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". + \fIcurl_multi_perform\fP stores the number of still running transfers in one of its input arguments, and by reading that you can figure out when all the transfers in the multi handles are done. 'done' does not mean successful. One -or more of the transfers may have failed. +or more of the transfers may have failed. Tracking when this number changes, +you know when one or more transfers are done. To get information about completed transfers, to figure out success or not and similar, \fIcurl_multi_info_read\fP should be called. It can return a message about a current or previous transfer. Repeated invokes of the function get -more messages until the message queue is empty. +more messages until the message queue is empty. The information you receive +there includes an easy handle pointer which you may use to identify which easy +handle the information regards. When all transfers in the multi stack are done, cleanup the multi handle with \fIcurl_multi_cleanup\fP. Be careful and please note that you \fBMUST\fP invoke separate \fIcurl_easy_cleanup\fP calls on every single easy handle to clean them up properly. + +If you want to re-use an easy handle that was added to the multi handle for +transfer, you must first remove it from the multi stack and then re-add it +again (possbily after having altered some options at your own choice). -- cgit v1.2.1 From e6367abae97f15dd6dca65a493c6037e9e5d47b3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 14 Oct 2002 07:39:49 +0000 Subject: generate and include PDF versions of the docs in the release archive --- docs/libcurl/Makefile.am | 44 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 3a6c266c0..34a15711d 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -75,7 +75,42 @@ HTMLPAGES = \ libcurl-errors.html \ index.html -EXTRA_DIST = $(man_MANS) $(HTMLPAGES) +PDFPAGES = \ + curl_easy_cleanup.pdf \ + curl_easy_getinfo.pdf \ + curl_easy_init.pdf \ + curl_easy_perform.pdf \ + curl_easy_setopt.pdf \ + curl_easy_duphandle.pdf \ + curl_formadd.pdf \ + curl_formparse.pdf \ + curl_formfree.pdf \ + curl_getdate.pdf \ + curl_getenv.pdf \ + curl_slist_append.pdf \ + curl_slist_free_all.pdf \ + curl_version.pdf \ + curl_version_info.pdf \ + curl_escape.pdf \ + curl_unescape.pdf \ + curl_free.pdf \ + curl_strequal.pdf \ + curl_strnequal.pdf \ + curl_mprintf.pdf \ + curl_global_init.pdf \ + curl_global_cleanup.pdf \ + libcurl.pdf \ + curl_multi_add_handle.pdf \ + curl_multi_cleanup.pdf \ + curl_multi_fdset.pdf \ + curl_multi_info_read.pdf \ + curl_multi_init.pdf \ + curl_multi_perform.pdf \ + curl_multi_remove_handle.pdf \ + libcurl-multi.pdf \ + libcurl-errors.pdf + +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) $(PDFPAGES) MAN2HTML= gnroff -man $< | man2html >$@ @@ -88,3 +123,10 @@ html: $(HTMLPAGES) .1.html: $(MAN2HTML) + +pdf: + for file in $(man_MANS); do \ + foo=`echo $$file | sed -e 's/\.[0-9]$$//g'`; \ + groff -Tps -man $$file >$$foo.ps; \ + ps2pdf $$foo.ps $$foo.pdf; \ + done -- cgit v1.2.1 From b6dac2b484f7e96732802b7e6bedffd8c75fb011 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 14 Oct 2002 07:47:40 +0000 Subject: ignore .ps and .pdf files too --- docs/libcurl/.cvsignore | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/.cvsignore b/docs/libcurl/.cvsignore index 09e145216..f7954dff0 100644 --- a/docs/libcurl/.cvsignore +++ b/docs/libcurl/.cvsignore @@ -1,3 +1,5 @@ Makefile Makefile.in *html +*ps +*pdf -- cgit v1.2.1 From 86a86d7afd217635532615cd8cb69e07210969f0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 15 Oct 2002 08:39:30 +0000 Subject: =?UTF-8?q?Andr=E9s=20Garc=EDa's=20corrections?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/libcurl/curl_easy_setopt.3 | 15 ++++++++++----- docs/libcurl/curl_multi_fdset.3 | 2 +- docs/libcurl/curl_multi_perform.3 | 2 +- docs/libcurl/curl_multi_remove_handle.3 | 2 +- 4 files changed, 13 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 38e00222a..672d9ca36 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,4 +1,3 @@ -.\" You can view this file with: .\" nroff -man [file] .\" $Id$ .\" @@ -166,7 +165,7 @@ code). (Added in 7.7.2) .B CURLOPT_WRITEHEADER Pass a pointer to be used to write the header part of the received data to. If you don't use your own callback to take care of the writing, this must be a -valid FILE *. See also the \fICURLOPT_HEADERFUNCTION\fP option below on how to +valid FILE *. See also the \fICURLOPT_HEADERFUNCTION\fP option above on how to set a custom get-all-headers callback. .TP .B CURLOPT_DEBUGFUNCTION @@ -235,7 +234,7 @@ you tunnel through the HTTP proxy. Such tunneling is activated with Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. .TP -.B CURLOPT_PROXTYPE +.B CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for this are CURLPROXY_HTTP and CURLPROXY_SOCKS5, with the HTTP one being default. (Added in 7.10) @@ -322,6 +321,12 @@ prompt function. .PP .SH HTTP OPTIONS .TP 0.4i +.B CURLOPT_ENCODING +Two encodings are supported \fIdentity\fP, which does nothing, and +\fIdeflate\fP to request the server to compress its reponse using the +zlib algorithm. This is not an order, the server may or may not do it. +See the special file lib/README.encoding for details. +.TP .B CURLOPT_FOLLOWLOCATION A non-zero parameter tells the library to follow any Location: header that the server sends as part of a HTTP header. @@ -577,7 +582,7 @@ aborting perfectly normal operations. This option will cause curl to use the SIGALRM to enable time-outing system calls. \fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as -it uses signals unless CURLOPT_NOSIGNAL (see below) is set. +it uses signals unless CURLOPT_NOSIGNAL (see above) is set. .TP .B CURLOPT_LOW_SPEED_LIMIT Pass a long as parameter. It contains the transfer speed in bytes per second @@ -640,7 +645,7 @@ connection timeout (it will then only timeout on the system's internal timeouts). See also the \fICURLOPT_TIMEOUT\fP option. \fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as -it uses signals unless CURLOPT_NOSIGNAL (see below) is set. +it uses signals unless CURLOPT_NOSIGNAL (see above) is set. .PP .SH SSL and SECURITY OPTIONS .TP 0.4i diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 0fab39e0b..2ec821029 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -2,7 +2,7 @@ .\" .TH curl_multi_fdset 3 "3 May 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME -curl_multi_fdset - add an easy handle to a multi session +curl_multi_fdset - extracts file descriptor information from a multi handle .SH SYNOPSIS #include diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index dae41ace8..a722856bb 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -2,7 +2,7 @@ .\" .TH curl_multi_perform 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME -curl_multi_perform - add an easy handle to a multi session +curl_multi_perform - reads/writes available data from each easy handle .SH SYNOPSIS #include diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 index a8d93eef4..7739f8c77 100644 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -2,7 +2,7 @@ .\" .TH curl_multi_remove_handle 3 "6 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME -curl_multi_remove_handle - add an easy handle to a multi session +curl_multi_remove_handle - remove an easy handle from a multi session .SH SYNOPSIS #include -- cgit v1.2.1 From d6654bfe00ae6d955d6f6f7367d2e7b1e11011b4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 16 Oct 2002 09:53:38 +0000 Subject: mucho fixed --- docs/libcurl/curl_formadd.3 | 158 ++++++++++++++++++++++++++------------------ 1 file changed, 92 insertions(+), 66 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 66d4ffefd..7a4cb4484 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -19,78 +19,104 @@ the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. \fIlastitem\fP is set after each call and on repeated invokes it should be left as set to allow repeated invokes to find the end of the list faster. -After the \fIlastitem\fP pointer follow the real arguments. (If the following -description confuses you, jump directly to the examples): - -\fBCURLFORM_COPYNAME\fP or \fBCURLFORM_PTRNAME\fP followed by a string is used -for the name of the section. Optionally one may use \fBCURLFORM_NAMELENGTH\fP -to specify the length of the name (allowing null characters within the -name). All options that use the word COPY in their names copy the given -contents, while the ones with PTR in their names simply points to the (static) -data you must make sure remain until curl no longer needs it. - -The options for providing values are: \fBCURLFORM_COPYCONTENTS\fP, -\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, \fBCURLFORM_BUFFER\fP, -or \fBCURLFORM_FILECONTENT\fP followed by a char or void pointer -(allowed for PTRCONTENTS). - -\fBCURLFORM_FILECONTENT\fP does a normal post like \fBCURLFORM_COPYCONTENTS\fP -but the actual value is read from the filename given as a string. - -Other arguments may be \fBCURLFORM_CONTENTTYPE\fP if the user wishes to -specify one (for FILE if no type is given the library tries to provide the -correct one; for CONTENTS no Content-Type is sent in this case). - -For \fBCURLFORM_PTRCONTENTS\fP or \fBCURLFORM_COPYNAME\fP the user may also -add \fBCURLFORM_CONTENTSLENGTH\fP followed by the length as a long (if not -given the library will use strlen to determine the length). - -For \fBCURLFORM_FILE\fP the user may send multiple files in one section by -providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename -(and each FILE is allowed to have a CONTENTTYPE). - -\fBCURLFORM_BUFFER\fP -tells libcurl that a buffer is to be used to upload data instead of using a -file. The value of the next parameter is used as the value of the "filename" -parameter in the content header. - -\fBCURLFORM_BUFFERPTR\fP -tells libcurl that the address of the next parameter is a pointer to the buffer -containing data to upload. The buffer containing this data must not be freed -until after curl_easy_cleanup is called. - -\fBCURLFORM_BUFFERLENGTH\fP -tells libcurl that the length of the buffer to upload is the value of the -next parameter. - -Another possibility to send options to curl_formadd() is the -\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as -its value. Each curl_forms structure element has a CURLformoption and a char -pointer. The final element in the array must be a CURLFORM_END. All available -options can be used in an array, except the CURLFORM_ARRAY option itself! - -Should you need to specify extra headers for the form POST section, use -\fBCURLFORM_CONTENTHEADER\fP. This takes a curl_slist prepared in the usual way -using \fBcurl_slist_append\fP and appends the list of headers to those Curl -automatically generates for \fBCURLFORM_CONTENTTYPE\fP and the content -disposition. The list must exist while the POST occurs, if you free it before -the post completes you may experience problems. - -The last argument in such an array must always be \fBCURLFORM_END\fP. +After the \fIlastitem\fP pointer follow the real arguments. The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to NULL in the first call to this function. All list-data will be allocated by the function itself. You must call \fIcurl_formfree\fP after the form post has been done to free the resources again. -This function will copy all input data except the data pointed to by the -arguments after \fBCURLFORM_PTRNAME\fP and \fBCURLFORM_PTRCONTENTS\fP and keep -its own version of it allocated until you call \fIcurl_formfree\fP. When -you've passed the pointer to \fIcurl_easy_setopt\fP, you must not free the -list until after you've called \fIcurl_easy_cleanup\fP for the curl handle. If -you provide a pointer as an arguments after \fBCURLFORM_PTRNAME\fP or -\fBCURLFORM_PTRCONTENTS\fP you must ensure that the pointer stays valid until -you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP. +First, there are some basics you need to understand about multipart/formdata +posts. Each part consists of at least a NAME and a CONTENTS part. If the part +is made for file upload, there are also a stored CONTENT-TYPE and a +FILENAME. Below here, we'll discuss on what options you use to set these +properties in the parts you want to add to your post. +.SH OPTIONS +.B CURLFORM_COPYNAME +followed by string is used to set the name of this part. libcurl copies the +given data, so your application doesn't need to keep it around after this +function call. If the name isn't zero terminated properly, or if you'd like it +to contain zero bytes, you need to set the length of the name with +\fBCURLFORM_NAMELENGTH\fP. + +.B CURLFORM_PTRNAME +followed by a string is used for the name of this part. libcurl will use the +pointer and refer to the data in your application, you must make sure it +remains until curl no longer needs it. If the name isn't zero terminated +properly, or if you'd like it to contain zero bytes, you need to set the +length of the name with \fBCURLFORM_NAMELENGTH\fP. + +.B CURLFORM_COPYCONTENTS +followed by a string is used for the contents of this part, the actual data to +send away. libcurl copies the given data, so your application doesn't need to +keep it around after this function call (\f). If the data isn't zero terminated +properly, or if you'd like it to contain zero bytes, you need to set the +length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. + +.B CURLFORM_PTRCONTENTS +followed by a string is used for the contents of this part, the actual data to +send away. libcurl will use the pointer and refer to the data in your +application, you must make sure it remains until curl no longer needs it. If +the data isn't zero terminated properly, or if you'd like it to contain zero +bytes, you need to set the length of the name with +\fBCURLFORM_CONTENTSLENGTH\fP. + +.B CURLFORM_FILECONTENT +followed by a file name, makes that file read and the contents will be used in +as data in this part. + +.B CURLFORM_FILE +followed by a file name, makes this part a file upload part. It sets the file +name field to the actual file name used here, it gets the contents of the file +and passes as data and sets the content-type if the given file match one of +the new internally known file extension. For \fBCURLFORM_FILE\fP the user may +send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP +arguments each followed by the filename (and each CURLFORM_FILE is allowed to +have a CURLFORM_CONTENTTYPE). + +.B CURLFORM_CONTENTTYPE +followed by a pointer to a string with a content-type will make curl use this +given content-type for this file upload part, possibly instead of an +internally chosen one. + +.B CURLFORM_FILENAME +followed by a pointer to a string to a name, will make libcurl use the given +name in the file upload part, intead of the actual file name given to +\fICURLFORM_FILE\fP. + +.B BCURLFORM_BUFFER +followed by a string, tells libcurl that a buffer is to be used to upload data +instead of using a file. The given string is used as the value of the file +name field in the content header. + +.B CURLFORM_BUFFERPTR +followed by a pointer to a data area, tells libcurl the address of the buffer +containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The +buffer containing this data must not be freed until after curl_easy_cleanup is +called. + +.B CURLFORM_BUFFERLENGTH +followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area, +tells libcurl the length of the buffer to upload. + +.B CURLFORM_ARRAY +Another possibility to send options to curl_formadd() is the +\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as +its value. Each curl_forms structure element has a CURLformoption and a char +pointer. The final element in the array must be a CURLFORM_END. All available +options can be used in an array, except the CURLFORM_ARRAY option itself! The +last argument in such an array must always be \fBCURLFORM_END\fP. + +.B CURLFORM_CONTENTHEADER +specifies extra headers for the form POST section. This takes a curl_slist +prepared in the usual way using \fBcurl_slist_append\fP and appends the list +of headers to those libcurl automatically generates. The list must exist while +the POST occurs, if you free it before the post completes you may experience +problems. + +When you've passed the HttpPost pointer to \fIcurl_easy_setopt\fP (using the +\fICURLOPT_HTTPPOST\fP option), you must not free the list until after you've +called \fIcurl_easy_cleanup\fP for the curl handle. See example below. .SH RETURN VALUE -- cgit v1.2.1 From f3875048f69a1b2cd40b356e307ca772789afc4e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Nov 2002 09:54:10 +0000 Subject: clarified that strings need to be kept around until the handle is closed or until the pointers are set to another value --- docs/libcurl/curl_easy_cleanup.3 | 5 ++++- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 2 files changed, 7 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index eea1df27c..4026cf240 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_cleanup 3 "4 March 2002" "libcurl 7.7" "libcurl Manual" +.TH curl_easy_cleanup 3 "13 Nov 2002" "libcurl 7.7" "libcurl Manual" .SH NAME curl_easy_cleanup - End a libcurl easy session .SH SYNOPSIS @@ -18,6 +18,9 @@ opposite of the \fIcurl_easy_init\fP function and must be called with the same This will effectively close all connections this handle has used and possibly has kept open until now. Don't call this function if you intend to transfer more files. + +When you've called this, you can safely remove all the strings you've +previously told libcurl to use, as it won't use them anymore now. .SH RETURN VALUE None .SH "SEE ALSO" diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 672d9ca36..0aff920be 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "18 Sep 2002" "libcurl 7.10" "libcurl Manual" +.TH curl_easy_setopt 3 "13 Nov 2002" "libcurl 7.10" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -22,7 +22,8 @@ curl_easy_setopt() calls in the setup phase. \fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be copied by the library. Instead you should keep them available until libcurl no longer needs them. Failing to do so will cause very odd behavior or even -crashes. +crashes. libcurl will them until you call curl_easy_cleanup() or you set the +same option again to use a different pointer. \fBNOTE2:\fP options set with this function call are valid for the forthcoming data transfers that are performed when you invoke \fIcurl_easy_perform\fP. -- cgit v1.2.1 From 75194373e0ed5856821dbcd06bcadeff44925331 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Nov 2002 09:55:00 +0000 Subject: language --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0aff920be..1d17ebb8e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -22,8 +22,8 @@ curl_easy_setopt() calls in the setup phase. \fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be copied by the library. Instead you should keep them available until libcurl no longer needs them. Failing to do so will cause very odd behavior or even -crashes. libcurl will them until you call curl_easy_cleanup() or you set the -same option again to use a different pointer. +crashes. libcurl will need them until you call curl_easy_cleanup() or you set +the same option again to use a different pointer. \fBNOTE2:\fP options set with this function call are valid for the forthcoming data transfers that are performed when you invoke \fIcurl_easy_perform\fP. -- cgit v1.2.1 From 3836a70f976e5024ddc3af6b66f167e730791c61 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 15 Nov 2002 14:13:46 +0000 Subject: removed nroff mistake --- docs/libcurl/curl_formadd.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 7a4cb4484..8ede2bbb2 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -49,7 +49,7 @@ length of the name with \fBCURLFORM_NAMELENGTH\fP. .B CURLFORM_COPYCONTENTS followed by a string is used for the contents of this part, the actual data to send away. libcurl copies the given data, so your application doesn't need to -keep it around after this function call (\f). If the data isn't zero terminated +keep it around after this function call. If the data isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. -- cgit v1.2.1 From 8bca5e05b8e96bbfaaef9cc8dcecc33ce7ef6a15 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 20 Nov 2002 19:11:22 +0000 Subject: Kjetil Jacobsen's patch that introduces CURLOPT_PRIVATE and CURLINFO_PRIVATE for storage and retrieval of private data in the curl handle. --- docs/libcurl/curl_easy_getinfo.3 | 6 +++++- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 2 files changed, 12 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 9f1e6a07e..ae149264d 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -115,8 +115,12 @@ Pass a pointer to a 'char *' to receive the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get NULL, it means that the server didn't send a valid Content-Type header or that the protocol used doesn't support this. (Added in 7.9.4) +.TP +.B CURLINFO_PRIVATE +Pass a pointer to a 'char *' to receive the pointer to the private data +associated with the curl handle (set with the CURLOPT_PRIVATE option to curl_easy_setopt). +(Added in 7.10.3) .PP - .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 1d17ebb8e..b387445f4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -763,6 +763,13 @@ krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or will be used. Set the string to NULL to disable kerberos4. The kerberos support only works for FTP. (Added in 7.3) .PP +.SH OTHER OPTIONS +.TP 0.4i +.B CURLOPT_PRIVATE +Pass a char * as parameter, pointing to data that should be +associated with the curl handle. The pointer can be subsequently retrieved using +the CURLINFO_PRIVATE options to curl_easy_getinfo. (Added in 7.10.3) +.PP .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP -- cgit v1.2.1 From 4a555de1b22404d72467fc43611bc58acd797967 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 1 Dec 2002 11:23:06 +0000 Subject: wrapped the line for PRIVATE nicer --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b387445f4..8ecebd36e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -766,9 +766,9 @@ support only works for FTP. (Added in 7.3) .SH OTHER OPTIONS .TP 0.4i .B CURLOPT_PRIVATE -Pass a char * as parameter, pointing to data that should be -associated with the curl handle. The pointer can be subsequently retrieved using -the CURLINFO_PRIVATE options to curl_easy_getinfo. (Added in 7.10.3) +Pass a char * as parameter, pointing to data that should be associated with +the curl handle. The pointer can be subsequently retrieved using the +CURLINFO_PRIVATE options to curl_easy_getinfo. (Added in 7.10.3) .PP .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an -- cgit v1.2.1 From 3f8ba3a986f56bac535faa82fad5a32200869116 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 Dec 2002 06:47:16 +0000 Subject: clarified SSL_VERIFYPEER and SSL_VERIFYHOST a bit, thanks to Soren Spies --- docs/libcurl/curl_easy_setopt.3 | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8ecebd36e..423d29b7d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -712,10 +712,13 @@ Pass a long as parameter. Set what version of SSL to attempt to use, 2 or servers make this difficult why you at times may have to use this option. .TP .B CURLOPT_SSL_VERIFYPEER -Pass a long that is set to a non-zero value to make curl verify the peer's -certificate. The certificate to verify against must be specified with the -CURLOPT_CAINFO option (Added in 7.4.2) or a certificate directory must be specified -with the CURLOPT_CAPATH option (Added in 7.9.8). +Pass a long that is set to a zero value to stop curl from verifying the peer's +certificate (7.10 starting setting this option to TRUE by default). Alternate +certificates to verify against can be specified with the CURLOPT_CAINFO option +(Added in 7.4.2) or a certificate directory can be specified with the +CURLOPT_CAPATH option (Added in 7.9.8). As of 7.10, curl installs a default +bundle. CURLOPT_SSL_VERIFYHOST may also need to be set to 1 or 0 if +CURLOPT_SSL_VERIFYPEER is disabled (it defaults to 2). .TP .B CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more @@ -742,7 +745,8 @@ socket. It will be used to seed the random engine for SSL. .B CURLOPT_SSL_VERIFYHOST Pass a long. Set if we should verify the Common name from the peer certificate in the SSL handshake, set 1 to check existence, 2 to ensure that it matches -the provided hostname. (Added in 7.8.1) +the provided hostname. This is by default set to 2. (Added in 7.8.1, default +changed in 7.10) .TP .B CURLOPT_SSL_CIPHER_LIST Pass a char *, pointing to a zero terminated string holding the list of -- cgit v1.2.1 From 75145dd75328f9a014a8dcced6db911595985000 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Dec 2002 10:37:20 +0000 Subject: clarify the DEBUGFUNCTION data not being zero terminated --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 423d29b7d..9bc836c39 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -175,6 +175,10 @@ curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP This function will receive debug information if CURLOPT_VERBOSE is enabled. The curl_infotype argument specifies what kind of information it is. This funtion must return 0. + +NOTE: the data pointed to by the char * passed to this function WILL NOT be +zero terminated, but will be exactly of the size as told by the size_t +argument. .TP .B CURLOPT_DEBUGDATA Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in -- cgit v1.2.1 From b097c2cfb0b64eb04bb45ef84a7fece187d49129 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Dec 2002 12:40:12 +0000 Subject: clarified --- docs/libcurl/curl_easy_setopt.3 | 2 +- docs/libcurl/curl_multi_perform.3 | 6 ++++++ docs/libcurl/libcurl-multi.3 | 6 +++--- 3 files changed, 10 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9bc836c39..fc0b37753 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "13 Nov 2002" "libcurl 7.10" "libcurl Manual" +.TH curl_easy_setopt 3 "3 Dec 2002" "libcurl 7.10.3" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index a722856bb..5b54fea8d 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -19,6 +19,12 @@ integer-pointer. .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. +If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basicly means that you +should call \fIcurl_multi_perform\fP again, before you select() on more +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". + NOTE that this only returns errors etc regarding the whole multi stack. There might still have occurred problems on invidual transfers even when this function returns OK. diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 3caa69d82..7648ad2dd 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -72,9 +72,9 @@ timeout every now and then, should you want that. A little note here about the return codes from the multi functions, and especially the \fIcurl_multi_perform\fP: if you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basicly means that you should call -\fIcurlm_call_multi_perform\fP again, before you select() on more 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 +\fIcurl_multi_perform\fP again, before you select() on more 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". \fIcurl_multi_perform\fP stores the number of still running transfers in one -- cgit v1.2.1 From 81f45ba92ac15bc7054280a14acf92a1b1402c7b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 16 Dec 2002 17:33:21 +0000 Subject: writefunction data is not zero terminated --- docs/libcurl/curl_easy_setopt.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index fc0b37753..3b32967b8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -70,10 +70,10 @@ Function pointer that should match the following prototype: \fBsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This function gets called by libcurl as soon as there is data reveiced that needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP -multiplied with \fInmemb\fP. Return the number of bytes actually taken care -of. If that amount differs from the amount passed to your function, it'll -signal an error to the library and it will abort the transfer and return -\fICURLE_WRITE_ERROR\fP. +multiplied with \fInmemb\fP, it will not be zero terminated. Return the number +of bytes actually taken care of. If that amount differs from the amount passed +to your function, it'll signal an error to the library and it will abort the +transfer and return \fICURLE_WRITE_ERROR\fP. Set the \fIstream\fP argument with the \fBCURLOPT_FILE\fP option. -- cgit v1.2.1 From efbe930a69b83b88b16b9935301a76b6368dda03 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 18 Dec 2002 16:51:02 +0000 Subject: CURLE_HTTP_NOT_FOUND => CURLE_HTTP_RETURNED_ERROR --- docs/libcurl/libcurl-errors.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 7181e0b08..bc0bbe64b 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl-errors 3 "10 April 2002" "libcurl 7.9.6" "libcurl errors" +.TH libcurl-errors 3 "18 Dec 2002" "libcurl 7.10.3" "libcurl errors" .SH NAME error codes in libcurl .SH DESCRIPTION @@ -104,7 +104,7 @@ After a completed file transfer, the FTP server did not respond a proper When sending custom "QUOTE" commands to the remote server, one of the commands returned an error code that was 400 or higher. .TP -.B CURLE_HTTP_NOT_FOUND (22) +.B CURLE_HTTP_RETURNED_ERROR (22) This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server returns an error code that is >= 400. .TP -- cgit v1.2.1 From 76e107506f1886951a4ed2bf86eb2ecb69db3427 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 9 Jan 2003 14:58:54 +0000 Subject: Philippe Raoult's added note for HTTPHEADER --- docs/libcurl/curl_easy_setopt.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3b32967b8..0af47326f 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -405,7 +405,11 @@ 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 internally used header will get disabled. Thus, using this option you can add -new headers, replace internal headers and remove internal headers. +new headers, replace internal headers and remove internal headers. 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 you specified. \fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. -- cgit v1.2.1 From 2ede47b8c89c60e2d0f91d82d038dd5f73af31ea Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 9 Jan 2003 15:04:55 +0000 Subject: Wai (Simon) Liu provided the HTTP200ALIASES paragraph. --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0af47326f..b5f0de9a8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -414,6 +414,22 @@ of the headers you specified. \fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. .TP +.B CURLOPT_HTTP200ALIASES +Pass a pointer to a linked list of aliases to be treated as valid HTTP 200 +responses. Some servers respond with a custom header response line. For +example, IceCast servers respond with "ICY 200 OK". By including this string +in your list of aliases, the response will be treated as a valid HTTP header +line such as "HTTP/1.0 200 OK". (Added in 7.10.3) + +The linked list should be a fully valid list of struct curl_slist structs, and +be 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. + +\fBNOTE:\fPThe alias itself is not parsed for any version strings. So if your +alias is "MYHTTP/9.9", Libcurl will not treat the server as responding with +HTTP version 9.9. Instead Libcurl will use the value set by option +\fICURLOPT_HTTP_VERSION\fP. +.TP .B CURLOPT_COOKIE Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be -- cgit v1.2.1 From 9faf57ee8d53c1ca253c318364e80f74c707eeca Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 17 Feb 2003 23:23:11 +0000 Subject: how to disable FTP PORT --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b5f0de9a8..8b3a7f30a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -502,6 +502,9 @@ 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 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. .TP .B CURLOPT_QUOTE Pass a pointer to a linked list of FTP commands to pass to the server prior to -- cgit v1.2.1 From a6834160818363a9518f82b2a2592993cb52cbf0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 21 Feb 2003 15:19:50 +0000 Subject: added an EXAMPLE section --- docs/libcurl/curl_slist_append.3 | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 index 4737b989b..fbf993229 100644 --- a/docs/libcurl/curl_slist_append.3 +++ b/docs/libcurl/curl_slist_append.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_slist_append 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" +.TH curl_slist_append 3 "21 Feb 2003" "libcurl 7.10.4" "libcurl Manual" .SH NAME curl_slist_append - add a string to an slist .SH SYNOPSIS @@ -13,17 +13,26 @@ curl_slist_append - add a string to an slist .ad .SH DESCRIPTION curl_slist_append() appends a specified string to a linked list of -strings. The existing -.I list -should be passed as the first argument while the new list is returned from -this function. The specified -.I string -has been appended when this function returns. +strings. The existing \fIlist\fP should be passed as the first argument while +the new list is returned from this function. The specified \fIstring\fP has +been appended when this function returns. + +The list should be freed again (after usage) with \fBcurl_slist_free_all()\fP. .SH RETURN VALUE A null pointer is returned if anything went wrong, otherwise the new list pointer is returned. +.SH EXAMPLE + CURL handle; + curl_slist *slist=NULL; + + slist = curl_slist_append(slist, "pragma:"); + curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); + + curl_easy_perform(handle); + + curl_slist_free_all(slist); /* free the list again */ .SH "SEE ALSO" .BR curl_slist_free_all "(3), " .SH BUGS -Surely there are some, you tell me! +None. -- cgit v1.2.1 From 248eb47329aa80752980f1790a31dcb7a30b56cd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 27 Feb 2003 14:25:54 +0000 Subject: Updated to better reflect reality. Also displays how the CURLMsg struct looks like. --- docs/libcurl/curl_multi_info_read.3 | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 8fcaeb576..4abd91e51 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_info_read 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.TH curl_multi_info_read 3 "27 Feb 2002" "libcurl 7.10.3" "libcurl Manual" .SH NAME curl_multi_info_read - read multi stack informationals .SH SYNOPSIS @@ -10,15 +10,15 @@ CURLMsg *curl_multi_info_read( CURLM *multi_handle, int *msgs_in_queue); .ad .SH DESCRIPTION -Ask the multi handle if there's any messages/informationals from the -individual transfers. Messages include informationals such as an error code -from the transfer or just the fact that a transfer is completed. More details -on these should be written down as well. +Ask the multi handle if there are any messages/informationals from the +individual transfers. Messages may include informationals such as an error +code from the transfer or just the fact that a transfer is completed. More +details on these should be written down as well. Repeated calls to this function will return a new struct each time, until a -special "end of msgs" struct is returned as a signal that there is no more to -get at this point. The integer pointed to with \fImsgs_in_queue\fP will -contain the number of remaining messages after this function was called. +NULL is returned as a signal that there is no more to get at this point. The +integer pointed to with \fImsgs_in_queue\fP will contain the number of +remaining messages after this function was called. The data the returned pointer points to will not survive calling curl_multi_cleanup(). @@ -26,10 +26,19 @@ curl_multi_cleanup(). The 'CURLMsg' struct is very simple and only contain very basic informations. If more involved information is wanted, the particular "easy handle" in present in that struct and can thus be used in subsequent regular -curl_easy_getinfo() calls (or similar). +curl_easy_getinfo() calls (or similar): + + struct CURLMsg { + CURLMSG msg; /* what this message means */ + CURL *easy_handle; /* the handle it concerns */ + union { + void *whatever; /* message-specific data */ + CURLcode result; /* return code for transfer */ + } data; + }; .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 read) in the integer the second argument points to. .SH "SEE ALSO" -.BR curl_multi_cleanup "(3)," curl_multi_init "(3)," curl_multi_perform "(3)" +.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " curl_multi_perform "(3)" -- cgit v1.2.1 From bc1102922bd5d6b4e2a6f7a3c3b25e63897a07f6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 28 Feb 2003 07:53:31 +0000 Subject: spell out that POSTFIELDS should be url-encoded in most cases --- docs/libcurl/curl_easy_setopt.3 | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8b3a7f30a..3f8ef88a5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -361,9 +361,14 @@ will imply this option. .TP .B CURLOPT_POSTFIELDS Pass a char * as parameter, which should be the full data to post in a HTTP -post operation. This is a normal application/x-www-form-urlencoded kind, which -is the most commonly used one by HTML forms. See also the CURLOPT_POST. Since -7.8, using CURLOPT_POSTFIELDS implies CURLOPT_POST. +post operation. You need to make sure that the data is formatted the way you +want the server to receive it. libcurl will not convert or encode it for +you. Most web servers will assume this data to be url-encoded. Take note. + +This POST is a normal application/x-www-form-urlencoded kind (and libcurl will +set that Content-Type by default when this option is used), which is the most +commonly used one by HTML forms. See also the CURLOPT_POST. Using +CURLOPT_POSTFIELDS implies CURLOPT_POST. \fBNote:\fP to make multipart/formdata posts (aka rfc1867-posts), check out the \fICURLOPT_HTTPPOST\fP option. -- cgit v1.2.1 From 957b618fdcd4efe77623a863f091b2def53dadec Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 10 Mar 2003 20:43:59 +0000 Subject: clarify --- docs/libcurl/curl_multi_remove_handle.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 index 7739f8c77..f905b54e8 100644 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -14,6 +14,9 @@ specified easy handle be removed from this multi handle's control. When the easy handle has been removed from a multi stack, it is again perfectly legal to invoke \fIcurl_easy_perform()\fP on this easy handle. + +Removing a handle while being used, will effectively halt all transfers in +progress. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" -- cgit v1.2.1 From 9a075f53dc0179e516b59f0039d135b0d39f7b2e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 31 Mar 2003 04:04:40 +0000 Subject: clarify USERPWD somewhat more --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3f8ef88a5..a1bb2c6df 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -315,8 +315,16 @@ user. .TP .B CURLOPT_USERPWD Pass a char * as parameter, which should be [user name]:[password] to use for -the connection. If the password is left out, you will be prompted for it. -\fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +the connection. If both the colon and password is left out, you will be +prompted for it while using a colon with no password will make libcurl use an +empty password. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own +prompt function. + +When using HTTP and CURLOPT_FOLLOWLOCATION, libcurl might perform several +requests to possibly different hosts. libcurl will only send this user and +password information to hosts using the initial host name, so if libcurl +follows locations to other hosts it will not send the user and password to +those. This is enforced to prevent accidental information leakage. .TP .B CURLOPT_PROXYUSERPWD Pass a char * as parameter, which should be [user name]:[password] to use for -- cgit v1.2.1 From 25f611ca4279927d38327b3c8b4a9f81702cd127 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 31 Mar 2003 04:41:05 +0000 Subject: Guillaume Cottenceau's patch that adds CURLOPT_UNRESTRICTED_AUTH that disables the host name check in the FOLLOWLOCATION code. With that option set, libcurl will send user+password to all hosts. --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a1bb2c6df..4763c871a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -349,6 +349,11 @@ new location and follow new Location: headers all the way until no more such headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects libcurl will follow. .TP +.B CURLOPT_UNRESTRICTED_AUTH +A non-zero parameter tells the library it can continue to send authentication +(user+password) when following locations, even when hostname changed. Note +that this is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. +.TP .B CURLOPT_MAXREDIRS Pass a long. The set number will be the redirection limit. If that many redirections have been followed, the next redirect will cause an error -- cgit v1.2.1 From 0b0a88b78d98935f7f63ff70a79a58bdc7bf4c52 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 11 Apr 2003 08:19:06 +0000 Subject: when saving a cookie jar fails, you don't get an error code or anything, just a warning in the verbose output stream --- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4763c871a..c8720c27a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -478,6 +478,13 @@ is called. If no cookies are known, no file will be created. Specify "-" to instead have the cookies written to stdout. Using this option also enables cookies for this session, so if you for example follow a location it will make matching cookies get sent accordingly. (Added in 7.9) + +.B NOTE +If the cookie jar file can't be created or written to (when the +curl_easy_cleanup() is called), libcurl will not and cannot report an error +for this. Using CURLOPT_VERBOSE or CURLOPT_DEBUGFUNCTION will get a warning to +display, but that is the only visible feedback you get about this possibly +lethal situation. .TP .B CURLOPT_TIMECONDITION Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE time value is -- cgit v1.2.1 From c06c44f286d4017eaa49c0d88582af6f082b6cb5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 11 Apr 2003 08:51:24 +0000 Subject: Dan Fandrich's added gzip support documented. --- docs/libcurl/curl_easy_setopt.3 | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c8720c27a..8024197ec 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -335,10 +335,13 @@ prompt function. .SH HTTP OPTIONS .TP 0.4i .B CURLOPT_ENCODING -Two encodings are supported \fIdentity\fP, which does nothing, and -\fIdeflate\fP to request the server to compress its reponse using the -zlib algorithm. This is not an order, the server may or may not do it. -See the special file lib/README.encoding for details. +Three encodings are supported: \fIidentity\fP, which does nothing, +\fIdeflate\fP which requests the server to compress its response using the +zlib algorithm, and \fIgzip\fP which requests the gzip algorithm. This +is a request, not an order; the server may or may not do it. This +option must be set (to any value) or else any unsolicited encoding done +by the server is ignored. See the special file lib/README.encoding for +details. .TP .B CURLOPT_FOLLOWLOCATION A non-zero parameter tells the library to follow any Location: header that the -- cgit v1.2.1 From f9781afafd3f0d01d00e6d58df081c3a870f8b8e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 11 Apr 2003 16:52:30 +0000 Subject: clarified the CURLINFO_SIZE_DOWNLOAD somewhat on Juan F. Codagnone's suggestion --- docs/libcurl/curl_easy_getinfo.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index ae149264d..72171b9a6 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -78,7 +78,8 @@ uploaded. .TP .B CURLINFO_SIZE_DOWNLOAD Pass a pointer to a double to receive the total amount of bytes that were -downloaded. +downloaded. The amount is only for the latest transfer and will be reset again +for each new transfer. .TP .B CURLINFO_SPEED_DOWNLOAD Pass a pointer to a double to receive the average download speed that curl -- cgit v1.2.1 From 8f85933d7c9f48e1ef5caf552df0055449b8e27a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 May 2003 12:47:35 +0000 Subject: Dan F clarified the CURLOPT_ENCODING description after his changes to allow "" to enable all support formats. --- docs/libcurl/curl_easy_setopt.3 | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8024197ec..26b0b246b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -335,13 +335,18 @@ prompt function. .SH HTTP OPTIONS .TP 0.4i .B CURLOPT_ENCODING -Three encodings are supported: \fIidentity\fP, which does nothing, -\fIdeflate\fP which requests the server to compress its response using the -zlib algorithm, and \fIgzip\fP which requests the gzip algorithm. This -is a request, not an order; the server may or may not do it. This -option must be set (to any value) or else any unsolicited encoding done -by the server is ignored. See the special file lib/README.encoding for -details. +Sets the contents of the Accept-Encoding: header sent in an HTTP +request, and enables decoding of a response when a Content-Encoding: +header is received. Three encodings are supported: \fIidentity\fP, +which does nothing, \fIdeflate\fP which requests the server to +compress its response using the zlib algorithm, and \fIgzip\fP which +requests the gzip algorithm. If a zero-length string is set, then an +Accept-Encoding: header containing all supported encodings is sent. + +This is a request, not an order; the server may or may not do it. This +option must be set (to any non-NULL value) or else any unsolicited +encoding done by the server is ignored. See the special file +lib/README.encoding for details. .TP .B CURLOPT_FOLLOWLOCATION A non-zero parameter tells the library to follow any Location: header that the -- cgit v1.2.1 From 1094e797490b429fdd3ed3280f14f24a87cbcd2d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 14 May 2003 09:03:51 +0000 Subject: documented CURLOPT_FTP_USE_EPRT --- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 26b0b246b..4eeaac79d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -575,6 +575,13 @@ and symbolic links. A non-zero parameter tells the library to append to the remote file instead of overwrite it. This is only useful when uploading to a ftp site. .TP +.B CURLOPT_FTP_USE_EPRT +Pass a long. If the value is non-zero, it tells curl to use the EPRT (and +LPRT) command when doing active FTP downloads (which is enabled by +CURLOPT_FTPPORT). Using EPRT means that it will first attempt to use EPRT and +then LPRT before using PORT, but if you pass FALSE (zero) to this option, it +will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5) +.TP .B CURLOPT_FTP_USE_EPSV Pass a long. If the value is non-zero, it tells curl to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV -- cgit v1.2.1 From e56ae1426cb7a0a4a427cf8d6099a821fdaae428 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Jun 2003 12:22:19 +0000 Subject: Daniel Kouril's patch that adds HTTP negotiation support to libcurl was added. --- docs/libcurl/curl_easy_setopt.3 | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4eeaac79d..ea66ace5b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -272,7 +272,7 @@ The main point of this would be that the write callback gets called more often and with smaller chunks. This is just treated as a request, not an order. You cannot be guaranteed to actually get the given size. (Added in 7.10) .PP -.SH NAMES and PASSWORDS OPTIONS +.SH NAMES and PASSWORDS OPTIONS (Authentication) .TP 0.4i .B CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and @@ -322,15 +322,31 @@ prompt function. When using HTTP and CURLOPT_FOLLOWLOCATION, libcurl might perform several requests to possibly different hosts. libcurl will only send this user and -password information to hosts using the initial host name, so if libcurl -follows locations to other hosts it will not send the user and password to -those. This is enforced to prevent accidental information leakage. +password information to hosts using the initial host name (unless +CURLOPT_UNRESTRICTED_AUTH is set), so if libcurl follows locations to other +hosts it will not send the user and password to those. This is enforced to +prevent accidental information leakage. .TP .B CURLOPT_PROXYUSERPWD Pass a char * as parameter, which should be [user name]:[password] to use for the connection to the HTTP proxy. If the password is left out, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +.TP +.B CURLOPT_HTTPDIGEST +Pass a long set to a non-zero value to enable HTTP Digest authentication. +Digest authentication is defined in RFC2617 and is a somewhat more secure way +to do user+password checking over public networks than the regular +old-fashioned Basic authentication. By default, libcurl uses Basic. Set name +and password with the CURLOPT_USERPWD option. (Added in 7.10.6) +.TP +.B CURLOPT_HTTPNEGOTIATE +Pass a long set to a non-zero value to enable HTTP Negotiate authentication. +The Negotiate method was designed by Microsoft and is used in their web +aplications. It is primarily meant as a support for Kerberos5 authentication +but may be also used along with another authentication methods. For more +information see IETF draft draft-brezak-spnego-http-04.txt. Set name and +password with the CURLOPT_USERPWD option. (Added in 7.10.6) .PP .SH HTTP OPTIONS .TP 0.4i -- cgit v1.2.1 From 39ea557360eb40ccab00fe153fd28284477ddd0e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Jun 2003 12:58:40 +0000 Subject: CURLOPT_HTTPAUTH docu --- docs/libcurl/curl_easy_setopt.3 | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ea66ace5b..8e0c7d850 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "3 Dec 2002" "libcurl 7.10.3" "libcurl Manual" +.TH curl_easy_setopt 3 "10 Jun 2003" "libcurl 7.10.6" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -333,20 +333,29 @@ the connection to the HTTP proxy. If the password is left out, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. .TP -.B CURLOPT_HTTPDIGEST -Pass a long set to a non-zero value to enable HTTP Digest authentication. -Digest authentication is defined in RFC2617 and is a somewhat more secure way -to do user+password checking over public networks than the regular -old-fashioned Basic authentication. By default, libcurl uses Basic. Set name -and password with the CURLOPT_USERPWD option. (Added in 7.10.6) -.TP -.B CURLOPT_HTTPNEGOTIATE -Pass a long set to a non-zero value to enable HTTP Negotiate authentication. -The Negotiate method was designed by Microsoft and is used in their web -aplications. It is primarily meant as a support for Kerberos5 authentication -but may be also used along with another authentication methods. For more -information see IETF draft draft-brezak-spnego-http-04.txt. Set name and -password with the CURLOPT_USERPWD option. (Added in 7.10.6) +.B CURLOPT_HTTPAUTH +Pass a long set to one of the curl_httpauth values, to tell libcurl what +authentication method you want it to use. Set the actual name and password +with the \fICURLOPT_USERPWD\fP option. (Added in 7.10.6) +.RS +.TP 5 +.B CURLHTTP_BASIC +enables HTTP Basic authentication. This is the default choice, and the only +method that is in wide-spread use and supported everywhere. +.TP +.B CURLHTTP_DIGEST +enables HTTP Digest authentication. Digest authentication is defined in +RFC2617 and is a somewhat more secure way to do user+password checking over +public networks than the regular old-fashioned Basic authentication. By +default, libcurl uses Basic. +.TP +.B CURLHTTP_NEGOTIATE +enables HTTP Negotiate authentication. The Negotiate method was designed by +Microsoft and is used in their web aplications. It is primarily meant as a +support for Kerberos5 authentication but may be also used along with another +authentication methods. For more information see IETF draft +draft-brezak-spnego-http-04.txt. +.RE .PP .SH HTTP OPTIONS .TP 0.4i -- cgit v1.2.1 From 4c80e103a055b719de04818615349be2b28b7858 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Jun 2003 13:06:38 +0000 Subject: clarify the CUSTOMREQUEST and HTTPHEADER options slightly --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8e0c7d850..8aefb4ae8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -462,6 +462,10 @@ 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 you specified. +The first line in a request (usually containing a GET or POST) is not a header +and cannot be replaced using this option. Only the lines following the +request-line are headers. + \fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. .TP @@ -643,6 +647,14 @@ Pass a pointer to a zero terminated string as parameter. It will be user instead of GET or HEAD when doing the HTTP request. 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. + +NOTE: many people have wrongly used this option to replace the entire request +with their own, including multiple headers and POST contents. While that might +work in many cases, it will cause libcurl to send invalid requests and it +could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and +\fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to +replace or extend the set of headers sent by libcurl. Use +\fICURLOPT_HTTP_VERSION\fP to change HTTP version. .TP .B CURLOPT_FILETIME Pass a long. If it is a non-zero value, libcurl will attempt to get the -- cgit v1.2.1 From 3130b44535232b1bfa87ac9a834bbabdb61e2d04 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 26 Jun 2003 11:40:44 +0000 Subject: added lots, mostly the new auth-related option(s) --- docs/libcurl/curl_easy_setopt.3 | 49 +++++++++++++++++++++++++++++------------ 1 file changed, 35 insertions(+), 14 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8aefb4ae8..2566ea0f5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -334,27 +334,47 @@ prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. .TP .B CURLOPT_HTTPAUTH -Pass a long set to one of the curl_httpauth values, to tell libcurl what -authentication method you want it to use. Set the actual name and password -with the \fICURLOPT_USERPWD\fP option. (Added in 7.10.6) +Pass a long as parameter, which is set to a bitmask, to tell libcurl what +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 +it to use. Note that for some methods, this will induce an extra network +round-trip. Set the actual name and password with the \fICURLOPT_USERPWD\fP +option. (Added in 7.10.6) .RS .TP 5 .B CURLHTTP_BASIC -enables HTTP Basic authentication. This is the default choice, and the only -method that is in wide-spread use and supported everywhere. +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 +the user name and password over the network in plain text, easily captured by +others. .TP .B CURLHTTP_DIGEST -enables HTTP Digest authentication. Digest authentication is defined in -RFC2617 and is a somewhat more secure way to do user+password checking over -public networks than the regular old-fashioned Basic authentication. By -default, libcurl uses Basic. +HTTP Digest authentication. Digest authentication is defined in RFC2617 and +is a more secure way to do authentication over public networks than the +regular old-fashioned Basic method. .TP -.B CURLHTTP_NEGOTIATE -enables HTTP Negotiate authentication. The Negotiate method was designed by +.B CURLHTTP_GSSNEGOTIATE +HTTP GSS-Negotiate authentication. The GSS-Negotiate method was designed by Microsoft and is used in their web aplications. It is primarily meant as a support for Kerberos5 authentication but may be also used along with another authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. +.TP +.B CURLHTTP_NTLM +HTTP NTLM authentication. A proprietary protocol invented and used by +Microsoft. It uses a challenge-response and hash concept similar to Digest to +prevent the password from being evesdropped. +.TP +.B CURLHTTP_ANY +This is a convenience macro that sets all bits and thus makes libcurl pick any +it finds suitable. libcurl will automaticly select the one it finds most +secure. +.TP +.B CURLHTTP_ANYSAFE +This is a convenience macro that sets all bits except Basic and thus makes +libcurl pick any it finds suitable. libcurl will automaticly select the one it +finds most secure. .RE .PP .SH HTTP OPTIONS @@ -644,9 +664,10 @@ want the transfer to start from. .TP .B CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user -instead of GET or HEAD when doing the HTTP request. 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. +instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST +when doing an 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. NOTE: many people have wrongly used this option to replace the entire request with their own, including multiple headers and POST contents. While that might -- cgit v1.2.1 From b7c14b3c27d42d09e0e493ed3bf3ac279ed6800a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 26 Jun 2003 11:41:08 +0000 Subject: mention that it copies the string you add --- docs/libcurl/curl_slist_append.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 index fbf993229..b47a38320 100644 --- a/docs/libcurl/curl_slist_append.3 +++ b/docs/libcurl/curl_slist_append.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_slist_append 3 "21 Feb 2003" "libcurl 7.10.4" "libcurl Manual" +.TH curl_slist_append 3 "19 Jun 2003" "libcurl 7.10.4" "libcurl Manual" .SH NAME curl_slist_append - add a string to an slist .SH SYNOPSIS @@ -15,7 +15,8 @@ curl_slist_append - add a string to an slist curl_slist_append() appends a specified string to a linked list of strings. The existing \fIlist\fP should be passed as the first argument while the new list is returned from this function. The specified \fIstring\fP has -been appended when this function returns. +been appended when this function returns. curl_slist_append() copies the +string. The list should be freed again (after usage) with \fBcurl_slist_free_all()\fP. .SH RETURN VALUE -- cgit v1.2.1 From 73071dfd4f63b10e2fe9b2e5990810a9b9efcbbb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 26 Jun 2003 11:41:24 +0000 Subject: mention the new flag bits we support --- docs/libcurl/curl_version_info.3 | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index cc14c0e59..e48df03b3 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_version_info 3 "30 Sep 2002" "libcurl 7.10" "libcurl Manual" +.TH curl_version_info 3 "17 Jun 2003" "libcurl 7.10.6" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -69,6 +69,16 @@ supports SSL (HTTPS/FTPS) .TP .B CURL_VERSION_LIBZ supports HTTP deflate using libz +.TP +.B CURL_VERSION_NTLM +supports HTTP NTLM (added in 7.10.6) +.TP +.B CURL_VERSION_GSSNEGOTIATE +supports HTTP GSS-Negotiate (added in 7.10.6) +.TP +.B CURL_VERSION_DEBUG +libcurl was built with extra debug capabilities built-in. This is mainly of +interest for libcurl hackers. (added in 7.10.6) .PP \fIssl_version\fP is an ascii string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. @@ -83,8 +93,6 @@ libcurl has no libz support, this is NULL. names protocols that libcurl supports (using lowercase letters). The protocol names are the same as would be used in URLs. The array is terminated by a NULL entry. - - .SH RETURN VALUE A pointer to a curl_version_info_data struct. .SH "SEE ALSO" -- cgit v1.2.1 From 58b6b3df0691b9b484dd0b56adf3d7fdeddd026c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 15 Jul 2003 22:44:48 +0000 Subject: Dan Winship pointed out this flaw --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2566ea0f5..0e32a0435 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -343,35 +343,35 @@ round-trip. Set the actual name and password with the \fICURLOPT_USERPWD\fP option. (Added in 7.10.6) .RS .TP 5 -.B CURLHTTP_BASIC +.B 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 the user name and password over the network in plain text, easily captured by others. .TP -.B CURLHTTP_DIGEST +.B CURLAUTH_DIGEST HTTP Digest authentication. Digest authentication is defined in RFC2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. .TP -.B CURLHTTP_GSSNEGOTIATE +.B CURLAUTH_GSSNEGOTIATE HTTP GSS-Negotiate authentication. The GSS-Negotiate method was designed by Microsoft and is used in their web aplications. It is primarily meant as a support for Kerberos5 authentication but may be also used along with another authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. .TP -.B CURLHTTP_NTLM +.B CURLAUTH_NTLM HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest to prevent the password from being evesdropped. .TP -.B CURLHTTP_ANY +.B CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automaticly select the one it finds most secure. .TP -.B CURLHTTP_ANYSAFE +.B CURLAUTH_ANYSAFE This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automaticly select the one it finds most secure. -- cgit v1.2.1 From 065c8d7a95c6999870eb5acf749c004a31afaba0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Aug 2003 21:23:42 +0000 Subject: Domenico Andreoli fixed the section number in the main meta data --- docs/libcurl/libcurl-multi.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 7648ad2dd..0fdff2e0b 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl-multi 5 "13 Oct 2001" "libcurl 7.10.1" "libcurl multi interface" +.TH libcurl-multi 3 "13 Oct 2001" "libcurl 7.10.1" "libcurl multi interface" .SH NAME libcurl-multi \- how to use the multi interface .SH DESCRIPTION -- cgit v1.2.1 From 6d36796135065063c69d6de57e28f3324f61c874 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 8 Aug 2003 07:07:15 +0000 Subject: corrected main meta data title --- docs/libcurl/curl_easy_getinfo.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 72171b9a6..b1c7adc96 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_init 3 "25 Apr 2002" "libcurl 7.9.7" "libcurl Manual" +.TH curl_easy_getinfo 3 "25 Apr 2002" "libcurl 7.9.7" "libcurl Manual" .SH NAME curl_easy_getinfo - Extract information from a curl session (added in 7.4) .SH SYNOPSIS -- cgit v1.2.1 From d987676ef061e78344933a3c680cab6389924bf1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 8 Aug 2003 11:04:35 +0000 Subject: added CURLOPT_FTP_CREATE_MISSING_DIRS --- docs/libcurl/curl_easy_setopt.3 | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0e32a0435..0030f3929 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "10 Jun 2003" "libcurl 7.10.6" "libcurl Manual" +.TH curl_easy_setopt 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -636,6 +636,11 @@ Pass a long. If the value is non-zero, it tells curl to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. +.TP +.B CURLOPT_FTP_CREATE_MISSING_DIRS +Pass a long. If the value is non-zero, curl will attempt to create any remote +directory that it fails to CWD into. CWD is the command that changes working +directory. (Added in 7.10.7) .PP .SH PROTOCOL OPTIONS .TP 0.4i -- cgit v1.2.1 From 3c294691aad2c6b913cf8e3ee480fedf7f8946b0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Aug 2003 07:23:49 +0000 Subject: remove the BUGS section --- docs/libcurl/curl_easy_setopt.3 | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0030f3929..bd1ffdd73 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -910,7 +910,3 @@ error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP man page for the full list with descriptions. .SH "SEE ALSO" .BR curl_easy_init "(3), " curl_easy_cleanup "(3), " -.SH BUGS -If you find any bugs, or just have questions, subscribe to one of the mailing -lists and post. We won't bite. - -- cgit v1.2.1 From 8fa43b469a221a6f87ade73b077a6178d6b8e4b7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Aug 2003 07:25:02 +0000 Subject: documenting the share interface --- docs/libcurl/curl_share_cleanup.3 | 19 ++++++++++++++++ docs/libcurl/curl_share_init.3 | 21 ++++++++++++++++++ docs/libcurl/curl_share_setopt.3 | 46 +++++++++++++++++++++++++++++++++++++++ docs/libcurl/libcurl-share.3 | 46 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 132 insertions(+) create mode 100644 docs/libcurl/curl_share_cleanup.3 create mode 100644 docs/libcurl/curl_share_init.3 create mode 100644 docs/libcurl/curl_share_setopt.3 create mode 100644 docs/libcurl/libcurl-share.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 new file mode 100644 index 000000000..2510213eb --- /dev/null +++ b/docs/libcurl/curl_share_cleanup.3 @@ -0,0 +1,19 @@ +.\" $Id$ +.\" +.TH curl_share_cleanup 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" +.SH NAME +curl_share_cleanup - Clean up a shared object +.SH SYNOPSIS +.B #include +.sp +.BI "CURLSHcode curl_share_cleanup( );" +.ad +.SH DESCRIPTION +This function deletes a shared object. The share handle cannot be used anymore +when this function has been called. + +.SH RETURN VALUE +If this function returns non-zero, the object was not properly deleted and it +still remains! +.SH "SEE ALSO" +.BR curl_share_init "(3), " curl_share_setopt "(3)" diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 new file mode 100644 index 000000000..2f6581363 --- /dev/null +++ b/docs/libcurl/curl_share_init.3 @@ -0,0 +1,21 @@ +.\" $Id$ +.\" +.TH curl_share_init 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" +.SH NAME +curl_share_init - Create a shared object +.SH SYNOPSIS +.B #include +.sp +.BI "CURLSH *curl_share_init( );" +.ad +.SH DESCRIPTION +This function returns a CURLSH handle to be used as input to all the other +share-functions, sometimes refered to as a share handle on 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. +.SH RETURN VALUE +If this function returns NULL, something went wrong and you got no share +object to use. +.SH "SEE ALSO" +.BR curl_share_cleanup "(3), " curl_share_setopt "(3)" + diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 new file mode 100644 index 000000000..583c14645 --- /dev/null +++ b/docs/libcurl/curl_share_setopt.3 @@ -0,0 +1,46 @@ +.\" $Id$ +.\" +.TH curl_share_setopt 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" +.SH NAME +curl_share_setopt - Set options for a shared object +.SH SYNOPSIS +.B #include +.sp +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter); +.ad +.SH DESCRIPTION +Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP. +.SH OPTIONS +.TP 0.4i +.B CURLSHOPT_LOCKFUNC +The \fIparameter\fP must be a pointer to a function matching the following +prototype: + +void lock_function(CURL *handle, curl_lock_data data, curl_lock_access access, +void *userptr); + +\fIdata\fP defines what data libcurl wants to lock, and you must make sure that +only one lock is given at any time for each kind of data. + +\fIaccess\fP defines what access type libcurl wants, shared or single. + +\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDAT\fP. + +.TP +.B CURLSHOPT_UNLOCKFUNC +hej +.TP +.B CURLSHOPT_SHARE +hej +.TP +.B CURLSHOPT_UNSHARE +hej +.TP +.B CURLSHOPT_USERDATA +hej +.PP +.SH RETURN VALUE +If this function returns non-zero, something was wrong! + +.SH "SEE ALSO" +.BR curl_share_cleanup "(3), " curl_share_init "(3)" diff --git a/docs/libcurl/libcurl-share.3 b/docs/libcurl/libcurl-share.3 new file mode 100644 index 000000000..6a8e22fb3 --- /dev/null +++ b/docs/libcurl/libcurl-share.3 @@ -0,0 +1,46 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH libcurl-share 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl share interface" +.SH NAME +libcurl-share \- how to use the share interface +.SH DESCRIPTION +This is an overview on how to use the libcurl share interface in your C +programs. There are specific man pages for each function mentioned in +here. + +All functions in the share interface are prefixed with curl_share. + +.SH "OBJECTIVES" +The share interface was added to enable sharing of data between curl +\&"handles". +.SH "ONE SET OF DATA - MANY TRANSFERS" +You can have multiple easy handles share data between them. Have them update +and use the \fBsame\fP cookie database or DNS cache! This way, each single +transfer will take advantage from data updates made by the other transfer(s). +.SH "SHARE OBJECT" +You create a shared object with \fIcurl_share_init()\fP. It returns a handle +for a newly created one. + +You tell the shared object what data you want it to share by using +\fIcurl_share_setopt()\fP. Currently you can only share DNS and/or COOKIE +data. + +Since you can use this share from multiple threads, and libcurl has no +internal thread synchronization, you must provide mutex callbacks if you're +using this multi-threaded. You set lock and unlock functions with +\fIcurl_share_setopt()\fP too. + +Then, you make an easy handle to use this share, you set the CURLOPT_SHARE +option with \fIcurl_easy_setopt\fP, and pass in share handle. You can make any +number of easy handles share the same share handle. + +To make an easy handle stop using that particular share, you set CURLOPT_SHARE +to NULL for that easy handle. To make a handle stop sharing a particular data, +you can CURLSHOPT_UNSHARE it. + +When you're done using the share, make sure that no easy handle is still using +it, and call \fIcurl_share_cleanup()\fP on the handle. +.SH "SEE ALSO" +.BR curl_share_init "(3), " curl_share_setopt "(3), " curl_share_cleanup "(3)" -- cgit v1.2.1 From 3e122a765d7a42435658354852a902e100264ae9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Aug 2003 11:29:33 +0000 Subject: Christian Beutenmueller corrected the CURLOPT_FILE referer, as we nowadays call it CURLOPT_WRITEDATA. --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index bd1ffdd73..830428cec 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -75,7 +75,7 @@ of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library and it will abort the transfer and return \fICURLE_WRITE_ERROR\fP. -Set the \fIstream\fP argument with the \fBCURLOPT_FILE\fP option. +Set the \fIstream\fP argument with the \fBCURLOPT_WRITEDATA\fP option. \fBNOTE:\fP you will be passed as much data as possible in all invokes, but you cannot possibly make any assumptions. It may be one byte, it may be -- cgit v1.2.1 From 1679993e3baa9f14932031b718d7a8ea24ccae57 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Aug 2003 11:54:14 +0000 Subject: CURLOPT_PROXYAUTH explained --- docs/libcurl/curl_easy_setopt.3 | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 830428cec..e2cdcf3b9 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -376,6 +376,17 @@ This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automaticly select the one it finds most secure. .RE +.TP +.B CURLOPT_PROXYAUTH +Pass a long as parameter, which is set to a bitmask, to tell libcurl what +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 +use. Note that for some methods, this will induce an extra network +round-trip. Set the actual name and password with the +\fICURLOPT_PROXYUSERPWD\fP option. The bitmask can be constructed by or'ing +together the bits listed above for the \fICURLOPT_HTTPAUTH\fP option. As of +this writing, only Basic and NTLM work. (Added in 7.10.7) .PP .SH HTTP OPTIONS .TP 0.4i -- cgit v1.2.1 From cc9ac6ad14f8af85ed187df7b789a7bee7ecf1eb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Aug 2003 23:07:38 +0000 Subject: mention curl_version_info --- docs/libcurl/curl_version.3 | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version.3 b/docs/libcurl/curl_version.3 index 5ddaa03f5..4998c7556 100644 --- a/docs/libcurl/curl_version.3 +++ b/docs/libcurl/curl_version.3 @@ -13,15 +13,7 @@ curl_version - returns the libcurl version string .SH DESCRIPTION Returns a human readable string with the version number of libcurl and some of its important components (like OpenSSL version). - -Note: this returns the actual running lib's version, you might have installed -a newer lib's include files in your system which may turn your LIBCURL_VERSION -#define value to differ from this result. .SH RETURN VALUE A pointer to a zero terminated string. .SH "SEE ALSO" -The -.I LIBCURL_VERSION -#define in -.SH BUGS -Surely there are some, you tell me! +.BR curl_version_info "(3)" -- cgit v1.2.1 From e2aecfe80f395841f561ac3f471beab3d3c7bf8b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Aug 2003 08:26:38 +0000 Subject: added the asynchdns bit --- docs/libcurl/curl_version_info.3 | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index e48df03b3..15bcb7b42 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_version_info 3 "17 Jun 2003" "libcurl 7.10.6" "libcurl Manual" +.TH curl_version_info 3 "12 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -79,6 +79,11 @@ supports HTTP GSS-Negotiate (added in 7.10.6) .B CURL_VERSION_DEBUG libcurl was built with extra debug capabilities built-in. This is mainly of interest for libcurl hackers. (added in 7.10.6) +.TP +.B CURL_VERSION_ASYNCHDNS +libcurl was built with support for asynchronous name lookups, which allows +more exact timeouts (even on Windows) and less blocking when using the multi +interface. (added in 7.10.7) .PP \fIssl_version\fP is an ascii string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. @@ -97,5 +102,4 @@ entry. A pointer to a curl_version_info_data struct. .SH "SEE ALSO" \fIcurl_version(3)\fP -.SH BUGS -No known bugs. + -- cgit v1.2.1 From a3e5d817651a91a52cb1dfc1ad022e95db80720f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Aug 2003 08:46:02 +0000 Subject: separated the easy-specific stuff into a new libcurl-easy.3 man page and made the libcurl.3 one a more generic overview --- docs/libcurl/libcurl-easy.3 | 29 +++++++++++++++++++++++ docs/libcurl/libcurl.3 | 56 ++++++++++++++++++++++----------------------- 2 files changed, 57 insertions(+), 28 deletions(-) create mode 100644 docs/libcurl/libcurl-easy.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 new file mode 100644 index 000000000..b3aaacea9 --- /dev/null +++ b/docs/libcurl/libcurl-easy.3 @@ -0,0 +1,29 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH libcurl 3 "12 Aug 2003" "libcurl 7.10.7" "libcurl easy interface" +.SH NAME +libcurl-easy \- easy interface overview +.SH DESCRIPTION +When using libcurl's "easy" interface you init your session and get a handle +(often referred to as an "easy handle" in various docs and sources), which you +use as input to the easy interface functions you use. Use +\fIcurl_easy_init()\fP to get the handle. + +You continue by setting all the options you want in the upcoming transfer, the +most important among them is the URL itself (you can't transfer anything +without a specified URL as you may have figured out yourself). You might want +to set some callbacks as well that will be called from the library when data +is available etc. \fIcurl_easy_setopt()\fP is used for all this. + +When all is setup, you tell libcurl to perform the transfer using +\fIcurl_easy_perform()\fP. It will then do the entire operation and won't +return until it is done (successfully or not). + +After the transfer has been made, you can set new options and make another +transfer, or if you're done, cleanup the session by calling +\fIcurl_easy_cleanup()\fP. If you want persistant connections, you don't +cleanup immediately, but instead run ahead and perform other transfers using +the same easy handle. + diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 10ff177d1..c474d3176 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -7,38 +7,37 @@ libcurl \- client-side URL transfers .SH DESCRIPTION This is an overview on how to use libcurl in your C programs. There are -specific man pages for each function mentioned in here. There's also the -libcurl-the-guide document for a complete tutorial to programming with -libcurl. +specific man pages for each function mentioned in here. There are also the +\fIlibcurl-easy\fP man page, the \fIlibcurl-multi\fP man page, the +\fIlibcurl-share\fP man page and the \fIlibcurl-the-guide\fP document for +further reading on how to do programming with libcurl. -There are a dozen custom bindings that bring libcurl access to your favourite -language. Look elsewhere for documentation on those. +There exist more than a dozen custom bindings that bring libcurl access to +your favourite language. Look elsewhere for documentation on those. All applications that use libcurl should call \fIcurl_global_init()\fP exactly once before any libcurl function can be used. After all usage of libcurl is complete, it \fBmust\fP call \fIcurl_global_cleanup()\fP. In between those two calls, you can use libcurl as described below. -When using libcurl's "easy" interface you init your session and get a handle, -which you use as input to the easy interface functions you use. Use -\fIcurl_easy_init()\fP to get the handle. There is also the so called "multi" -interface, try the \fIlibcurl-multi(3)\fP man page for an overview of that. +To transfer files, you always set up an "easy handle" using +\fIcurl_easy_init()\fP, but when you want the file(s) transfered you have the +option of using the "easy" interface, or the "multi" interface. -You continue by setting all the options you want in the upcoming transfer, -most important among them is the URL itself (you can't transfer anything -without a specified URL as you may have figured out yourself). You might want -to set some callbacks as well that will be called from the library when data -is available etc. \fIcurl_easy_setopt()\fP is there for this. +The easy interface is a synchronous interface with which you call +\fIcurl_easy_perform\fP and let it perform the transfer. When it is completed, +the function return and you can continue. More details are found in the +\fIlibcurl-easy\fP man page. -When all is setup, you tell libcurl to perform the transfer using -\fIcurl_easy_perform()\fP. It will then do the entire operation and won't -return until it is done (successfully or not). +The multi interface on the other hand is an asynchronous interface, that you +call and that performs only a little piece of the tranfer on each invoke. It +is perfect if you want to do things while the transfer is in progress, or +similar. The multi interface allows you to select() on libcurl action, and +even to easily download multiple files simultaneously using a single thread. -After the transfer has been made, you can set new options and make another -transfer, or if you're done, cleanup the session by calling -\fIcurl_easy_cleanup()\fP. If you want persistant connections, you don't -cleanup immediately, but instead run ahead and perform other transfers using -the same handle. See the chapter below for Persistant Connections. +You can have multiple easy handles share certain data, even if they are used +in different threads. This magic is setup using the share interface, as +described in the \fIlibcurl-share\fP man page. There is also a series of other helpful functions to use. They are: @@ -107,14 +106,15 @@ Persistent connections means that libcurl can re-use the same connection for several transfers, if the conditions are right. libcurl will *always* attempt to use persistent connections. Whenever you use -curl_easy_perform(), libcurl will attempt to use an existing connection to do -the transfer, and if none exists it'll open a new one that will be subject for -re-use on a possible following call to curl_easy_perform(). +\fIcurl_easy_perform()\fP or \fIcurl_multi_perform()\fP, libcurl will attempt +to use an existing connection to do the transfer, and if none exists it'll +open a new one that will be subject for re-use on a possible following call to +\fIcurl_easy_perform()\fP or \fIcurl_multi_perform()\fP. To allow libcurl to take full advantage of persistent connections, you should do as many of your file transfers as possible using the same curl handle. When -you call curl_easy_cleanup(), all the possibly open connections held by +you call \fIcurl_easy_cleanup()\fP, all the possibly open connections held by libcurl will be closed and forgotten. -Note that the options set with curl_easy_setopt() will be used in on every -repeat curl_easy_perform() call +Note that the options set with \fIcurl_easy_setopt()\fP will be used in on +every repeated \fIcurl_easy_perform()\fP call. -- cgit v1.2.1 From 8ffbb6acd410ff374a3272a31c198b4e0b0fb799 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Aug 2003 08:51:23 +0000 Subject: added the new curl_share_* man pages, the libcurl-easy, the libcurl-share, made the generated pdf and html files get removed on 'make clean'. Made the pdf conversion remove the temporary .ps files. --- docs/libcurl/Makefile.am | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 34a15711d..7297f06aa 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -28,7 +28,6 @@ man_MANS = \ curl_mprintf.3 \ curl_global_init.3 \ curl_global_cleanup.3 \ - libcurl.3 \ curl_multi_add_handle.3 \ curl_multi_cleanup.3 \ curl_multi_fdset.3 \ @@ -36,7 +35,11 @@ man_MANS = \ curl_multi_init.3 \ curl_multi_perform.3 \ curl_multi_remove_handle.3 \ + curl_share_cleanup.3 curl_share_init.3 curl_share_setopt.3 \ + libcurl.3 \ + libcurl-easy.3 \ libcurl-multi.3 \ + libcurl-share.3 \ libcurl-errors.3 HTMLPAGES = \ @@ -63,7 +66,6 @@ HTMLPAGES = \ curl_mprintf.html \ curl_global_init.html \ curl_global_cleanup.html \ - libcurl.html \ curl_multi_add_handle.html \ curl_multi_cleanup.html \ curl_multi_fdset.html \ @@ -71,7 +73,11 @@ HTMLPAGES = \ curl_multi_init.html \ curl_multi_perform.html \ curl_multi_remove_handle.html \ + curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ + libcurl.html \ libcurl-multi.html \ + libcurl-easy.html \ + libcurl-share.html \ libcurl-errors.html \ index.html @@ -99,7 +105,6 @@ PDFPAGES = \ curl_mprintf.pdf \ curl_global_init.pdf \ curl_global_cleanup.pdf \ - libcurl.pdf \ curl_multi_add_handle.pdf \ curl_multi_cleanup.pdf \ curl_multi_fdset.pdf \ @@ -107,9 +112,15 @@ PDFPAGES = \ curl_multi_init.pdf \ curl_multi_perform.pdf \ curl_multi_remove_handle.pdf \ + curl_share_cleanup.pdf curl_share_init.pdf curl_share_setopt.pdf \ + libcurl.pdf \ libcurl-multi.pdf \ + libcurl-easy.pdf \ + libcurl-share.pdf \ libcurl-errors.pdf +CLEANFILES = $(HTMLPAGES) $(PDFPAGES) + EXTRA_DIST = $(man_MANS) $(HTMLPAGES) $(PDFPAGES) MAN2HTML= gnroff -man $< | man2html >$@ @@ -129,4 +140,5 @@ pdf: foo=`echo $$file | sed -e 's/\.[0-9]$$//g'`; \ groff -Tps -man $$file >$$foo.ps; \ ps2pdf $$foo.ps $$foo.pdf; \ + rm $$foo.ps; \ done -- cgit v1.2.1 From c13236de258ec54d2971cff059dfa7c6e3efab4c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Aug 2003 08:58:15 +0000 Subject: corrected return type --- docs/libcurl/curl_free.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 index 718b86e28..d07fccd4e 100644 --- a/docs/libcurl/curl_free.3 +++ b/docs/libcurl/curl_free.3 @@ -2,16 +2,16 @@ .\" nroff -man [file] .\" $Id: .\" -.TH curl_free 3 "24 Sept 2002" "libcurl 7.10" "libcurl Manual" +.TH curl_free 3 "12 Aug 2003" "libcurl 7.10" "libcurl Manual" .SH NAME curl_free - reclaim memory that has been obtained through a libcurl call .SH SYNOPSIS .B #include .sp -.BI "void *curl_free( char *" ptr " );" +.BI "void curl_free( char *" ptr " );" .ad .SH DESCRIPTION curl_free reclaims memory that has been obtained through a libcurl call. Use curl_free() instead of free() to avoid anomalies that can result from differences in memory management between your application and libcurl. .SH "SEE ALSO" -.I curl_unescape(), curl_free() +.I curl_unescape() -- cgit v1.2.1 From 9687571a84e43d9bedab97e8ceb9fe2f7b714cc3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Aug 2003 08:58:23 +0000 Subject: added the new man pages --- docs/libcurl/index.html | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 52d11e219..997e6cea1 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -12,7 +12,9 @@

Overviews

libcurl +
libcurl-easy
libcurl-multi +
libcurl-share
libcurl-errors
libcurl-the-guide (plain text) @@ -40,6 +42,9 @@
curl_multi_init
curl_multi_perform
curl_multi_remove_handle +
curl_share_cleanup +
curl_share_init +
curl_share_setopt
curl_slist_append
curl_slist_free_all
curl_strequal -- cgit v1.2.1 From b46745759b75cc86a55f19c4f91f18ad37a920b6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Aug 2003 08:58:46 +0000 Subject: don't treat index.html as the generated HTML pages --- docs/libcurl/Makefile.am | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 7297f06aa..ccc98ac24 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -78,8 +78,7 @@ HTMLPAGES = \ libcurl-multi.html \ libcurl-easy.html \ libcurl-share.html \ - libcurl-errors.html \ - index.html + libcurl-errors.html PDFPAGES = \ curl_easy_cleanup.pdf \ @@ -121,7 +120,7 @@ PDFPAGES = \ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -EXTRA_DIST = $(man_MANS) $(HTMLPAGES) $(PDFPAGES) +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) MAN2HTML= gnroff -man $< | man2html >$@ -- cgit v1.2.1 From c46da652632a4c0719e4343d7d7030266c92588d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 12 Aug 2003 09:08:05 +0000 Subject: nicer make target for the pdf conversion --- docs/libcurl/Makefile.am | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index ccc98ac24..c90a99003 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -124,20 +124,18 @@ EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) MAN2HTML= gnroff -man $< | man2html >$@ -SUFFIXES = .1 .3 .html +SUFFIXES = .3 .html html: $(HTMLPAGES) .3.html: $(MAN2HTML) -.1.html: - $(MAN2HTML) +pdf: $(PDFPAGES) -pdf: - for file in $(man_MANS); do \ - foo=`echo $$file | sed -e 's/\.[0-9]$$//g'`; \ - groff -Tps -man $$file >$$foo.ps; \ - ps2pdf $$foo.ps $$foo.pdf; \ - rm $$foo.ps; \ - done +.3.pdf: + @(foo=`echo $@ | sed -e 's/\.[0-9]$$//g'`; \ + groff -Tps -man $< >$$foo.ps; \ + ps2pdf $$foo.ps $@; \ + rm $$foo.ps; \ + echo "converted $< to $@") -- cgit v1.2.1 From 6fc55467f4b50e3e8a344f3a9df28fa6a18ab3a1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 15 Aug 2003 06:35:41 +0000 Subject: removed lots of "added in [version]" where [version] is resonably old --- docs/libcurl/curl_easy_setopt.3 | 56 ++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 31 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e2cdcf3b9..b88a0ab8f 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -143,12 +143,11 @@ operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned. is a zero-terminated string that is text that prefixes the input request. \fIbuffer\fP is a pointer to data where the entered password should be stored and \fIbuflen\fP is the maximum number of bytes that may be written in the -buffer. (Added in 7.4.2) +buffer. .TP .B CURLOPT_PASSWDDATA Pass a void * to whatever data you want. The passed pointer will be the first -argument sent to the specifed \fICURLOPT_PASSWDFUNCTION\fP function. (Added in -7.4.2) +argument sent to the specifed \fICURLOPT_PASSWDFUNCTION\fP function. .TP .B CURLOPT_HEADERFUNCTION Function pointer that should match the following prototype: \fIsize_t @@ -161,7 +160,7 @@ multiplied with \fInmemb\fP. The pointer named \fIstream\fP will be the one you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the number of bytes actually written or return -1 to signal error to the library (it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return -code). (Added in 7.7.2) +code). .TP .B CURLOPT_WRITEHEADER Pass a pointer to be used to write the header part of the received data to. If @@ -248,23 +247,23 @@ default. (Added in 7.10) Set the parameter to non-zero to get the library to tunnel all operations through a given HTTP proxy. Note that 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. (Added in 7.3) +probably don't want this tunneling option. .TP .B 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 -name. (Added in 7.3) +name. .TP .B CURLOPT_DNS_CACHE_TIMEOUT Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero (0) to completely disable caching, or set to -1 to make the cached entries remain forever. By default, -libcurl caches info for 60 seconds. (Added in 7.9.3) +libcurl caches info for 60 seconds. .TP .B CURLOPT_DNS_USE_GLOBAL_CACHE Pass a long. If the value is non-zero, it tells curl to use a global DNS cache that will survive between easy handle creations and deletions. This is not -thread-safe and this will use a global varible. (Added in 7.9.3) +thread-safe and this will use a global varible. .TP .B CURLOPT_BUFFERSIZE Pass a long specifying your prefered size for the receive buffer in libcurl. @@ -422,7 +421,7 @@ that this is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. Pass a long. The set number will be the redirection limit. If that many redirections have been followed, the next redirect will cause an error (\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the -\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. (Added in 7.5) +\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. .TP .B CURLOPT_PUT A non-zero parameter tells the library to use HTTP PUT to transfer data. The @@ -454,8 +453,7 @@ the \fICURLOPT_HTTPPOST\fP option. If you want to post data to the server without letting libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If this -size is set to zero, the library will use strlen() to get the size. (Added in -libcurl 7.2) +size is set to zero, the library will use strlen() to get the size. .TP .B CURLOPT_HTTPPOST Tells libcurl you want a multipart/formdata HTTP POST to be made and you @@ -545,7 +543,7 @@ internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP is called. If no cookies are known, no file will be created. Specify "-" to instead have the cookies written to stdout. Using this option also enables cookies for this session, so if you for example follow a location it will make -matching cookies get sent accordingly. (Added in 7.9) +matching cookies get sent accordingly. .B NOTE If the cookie jar file can't be created or written to (when the @@ -567,7 +565,7 @@ CURLOPT_TIMECONDITION. .B CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. Only really usable if POST, PUT or a custom request have been used -previously using the same curl handle. (Added in 7.8.1) +previously using the same curl handle. .TP .B CURLOPT_HTTP_VERSION Pass a long, set to one of the values described below. They force libcurl to @@ -698,8 +696,7 @@ Pass a long. If it is a non-zero value, libcurl will attempt to get the modification date of the remote document in this operation. This requires that the remote server sends the time or replies to a time querying command. The \fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument -can be used after a transfer to extract the received time (if any). (Added in -7.5) +can be used after a transfer to extract the received time (if any). .TP .B CURLOPT_NOBODY A non-zero parameter tells the library to not include the body-part in the @@ -750,7 +747,7 @@ open connections to increase. \fBNOTE:\fP if you already have performed transfers with this curl handle, setting a smaller MAXCONNECTS than before may cause open connections to get -closed unnecessarily. (Added in 7.7) +closed unnecessarily. .TP .B CURLOPT_CLOSEPOLICY Pass a long. This option sets what policy libcurl should use when the @@ -761,7 +758,7 @@ the connection that was least recently used, that connection is also least likely to be capable of re-use. Use \fICURLCLOSEPOLICY_OLDEST\fP to make libcurl close the oldest connection, the one that was created first among the ones in the connection cache. The other close policies are not support -yet. (Added in 7.7) +yet. .TP .B CURLOPT_FRESH_CONNECT Pass a long. Set to non-zero to make the next transfer use a new (fresh) @@ -769,7 +766,7 @@ connection by force. If the connection cache is full before this connection, one of the existing connections will be closed as according to the selected or default policy. This option should be used with caution and only if you understand what it does. Set this to 0 to have libcurl attempt re-using an -existing connection (default behavior). (Added in 7.7) +existing connection (default behavior). .TP .B CURLOPT_FORBID_REUSE Pass a long. Set to non-zero to make the next transfer explicitly close the @@ -777,7 +774,7 @@ 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. 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 -re-use (default behavior). (Added in 7.7) +re-use (default behavior). .TP .B CURLOPT_CONNECTTIMEOUT Pass a long. It should contain the maximum time in seconds that you allow the @@ -814,12 +811,11 @@ a certificate but you need one to load your private key. .B CURLOPT_SSLKEY Pass a pointer to a zero terminated string as parameter. The string should be the file name of your private key. The default format is "PEM" and can be -changed with \fICURLOPT_SSLKEYTYPE\fP. (Added in 7.9.3) +changed with \fICURLOPT_SSLKEYTYPE\fP. .TP .B CURLOPT_SSLKEYTYPE Pass a pointer to a zero terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG". -(Added in 7.9.3) \fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to @@ -830,19 +826,18 @@ Pass a pointer to a zero terminated string as parameter. It will be used as the password required to use the \fICURLOPT_SSLKEY\fP private key. If the password is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. -(Added in 7.9.3) .TP .B CURLOPT_SSL_ENGINE Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private -key. (Added in 7.9.3) +key. \fBNOTE:\fPIf the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. .TP .B CURLOPT_SSL_ENGINEDEFAULT Sets the actual crypto engine as the default for (asymetric) crypto -operations. (Added in 7.9.3) +operations. \fBNOTE:\fPIf the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is returned. @@ -856,15 +851,15 @@ servers make this difficult why you at times may have to use this option. Pass a long that is set to a zero value to stop curl from verifying the peer's certificate (7.10 starting setting this option to TRUE by default). Alternate certificates to verify against can be specified with the CURLOPT_CAINFO option -(Added in 7.4.2) or a certificate directory can be specified with the -CURLOPT_CAPATH option (Added in 7.9.8). As of 7.10, curl installs a default -bundle. CURLOPT_SSL_VERIFYHOST may also need to be set to 1 or 0 if +or a certificate directory can be specified with the CURLOPT_CAPATH option +(Added in 7.9.8). As of 7.10, curl installs a default bundle. +CURLOPT_SSL_VERIFYHOST may also need to be set to 1 or 0 if CURLOPT_SSL_VERIFYPEER is disabled (it defaults to 2). .TP .B CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This only makes sense when used in -combination with the CURLOPT_SSL_VERIFYPEER option. (Added in 7.4.2) +combination with the CURLOPT_SSL_VERIFYPEER option. .TP .B CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple @@ -886,8 +881,7 @@ socket. It will be used to seed the random engine for SSL. .B CURLOPT_SSL_VERIFYHOST Pass a long. Set if we should verify the Common name from the peer certificate in the SSL handshake, set 1 to check existence, 2 to ensure that it matches -the provided hostname. This is by default set to 2. (Added in 7.8.1, default -changed in 7.10) +the provided hostname. This is by default set to 2. (default changed in 7.10) .TP .B CURLOPT_SSL_CIPHER_LIST Pass a char *, pointing to a zero terminated string holding the list of @@ -906,7 +900,7 @@ Pass a char * as parameter. Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or \&'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos4. The kerberos -support only works for FTP. (Added in 7.3) +support only works for FTP. .PP .SH OTHER OPTIONS .TP 0.4i -- cgit v1.2.1 From bd78878cc3c0bb85316c38f947e3175e0d10ba82 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 20 Aug 2003 15:44:03 +0000 Subject: CURLINFO_RESPONSE_CODE instead of CURLINFO_HTTP_CODE --- docs/libcurl/curl_easy_getinfo.3 | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index b1c7adc96..f3473bc3a 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_getinfo 3 "25 Apr 2002" "libcurl 7.9.7" "libcurl Manual" +.TH curl_easy_getinfo 3 "20 Aug 2003" "libcurl 7.10.8" "libcurl Manual" .SH NAME curl_easy_getinfo - Extract information from a curl session (added in 7.4) .SH SYNOPSIS @@ -25,8 +25,9 @@ These are informations that can be extracted: .B CURLINFO_EFFECTIVE_URL Pass a pointer to a 'char *' to receive the last used effective URL. .TP -.B CURLINFO_HTTP_CODE -Pass a pointer to a long to receive the last received HTTP code. +.B CURLINFO_RESPONSE_CODE +Pass a pointer to a long to receive the last received HTTP or FTP code. This +option was known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. .TP .B CURLINFO_FILETIME Pass a pointer to a long to receive the remote time of the retrieved -- cgit v1.2.1 From 359c0eac0ddc8849334e4b05012ec41540892f02 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 5 Sep 2003 11:02:11 +0000 Subject: Early Ehlinger's CURLOPT_FTP_RESPONSE_TIMEOUT option documented by himself. --- docs/libcurl/curl_easy_setopt.3 | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b88a0ab8f..a4cd9e7de 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -650,6 +650,15 @@ pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. Pass a long. If the value is non-zero, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working directory. (Added in 7.10.7) +.TP +.B CURLOPT_FTP_RESPONSE_TIMEOUT +Pass a long. Causes curl to set a timeout period (in seconds) on the amount +of time that the server is allowed to take in order to generate a response +message for a command before the session is considered hung. Note that while +curl is waiting for a response, this value overrides CURLOPT_TIMEOUT. It is +recommended that if used in conjunction with CURLOPT_TIMEOUT, you set +CURLOPT_FTP_RESPONSE_TIMEOUT to a value smaller than CURLOPT_TIMEOUT. +(Added in 7.10.8) .PP .SH PROTOCOL OPTIONS .TP 0.4i -- cgit v1.2.1 From 6e16985156b17976a3ba037a7caa5e2d295ef1f9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Sep 2003 18:35:38 +0000 Subject: Added more docs for DEBUGFUNCTION as suggsted by Mohun Biswas --- docs/libcurl/curl_easy_setopt.3 | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a4cd9e7de..a91fc1e32 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" +.TH curl_easy_setopt 3 "13 Sep 2003" "libcurl 7.10.8" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -171,13 +171,30 @@ set a custom get-all-headers callback. .B CURLOPT_DEBUGFUNCTION Function pointer that should match the following prototype: \fIint curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP -This function will receive debug information if CURLOPT_VERBOSE is -enabled. The curl_infotype argument specifies what kind of information it -is. This funtion must return 0. +CURLOPT_DEBUGFUNCTION replaces the standard debug function used when +CURLOPT_VERBOSE is in effect. This callback receives debug information, as +specified with the \fIcurl_infotype\fP argument. This funtion must return 0. +The data pointed to by the char * passed to this function WILL NOT be zero +terminated, but will be exactly of the size as told by the size_t argument. -NOTE: the data pointed to by the char * passed to this function WILL NOT be -zero terminated, but will be exactly of the size as told by the size_t -argument. +Available curl_infotype values: +.RS +.TP 5 +.B CURLINFO_TEXT +The data is informational text. +.TP +.B CURLINFO_HEADER_IN +The data is header (or header-like) data received from the peer. +.TP +.B CURLINFO_HEADER_OUT +The data is header (or header-like) data sent to the peer. +.TP +.B CURLINFO_DATA_IN +The data is protocol data received from the peer. +.TP +.B CURLINFO_DATA_OUT +The data is protocol data sent to the peer. +.RE .TP .B CURLOPT_DEBUGDATA Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in -- cgit v1.2.1 From 09ccfcdcd422fc0b0421562bbdcf53f78a3f3e4b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 19 Sep 2003 12:56:22 +0000 Subject: Markus Moeller's SPNEGO patch applied, with my edits, additions and minor cleanups. --- docs/libcurl/curl_version_info.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 15bcb7b42..ed1327b21 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_version_info 3 "12 Aug 2003" "libcurl 7.10.7" "libcurl Manual" +.TH curl_version_info 3 "19 Sep 2003" "libcurl 7.10.8" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -84,6 +84,10 @@ interest for libcurl hackers. (added in 7.10.6) libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi interface. (added in 7.10.7) +.TP +.B CURL_VERSION_SPNEGO +libcurl was built with support for SPNEGO authentication (Simple and Protected +GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) .PP \fIssl_version\fP is an ascii string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. -- cgit v1.2.1 From b864e25011ff109307bcac8fffffc3aeb983aaec Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 4 Oct 2003 14:01:41 +0000 Subject: CURLOPT_NOBODY means HEAD on HTTP servers --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a91fc1e32..6ae4ae9b9 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -727,7 +727,7 @@ can be used after a transfer to extract the received time (if any). .B CURLOPT_NOBODY A non-zero parameter tells the library to not include the body-part in the output. This is only relevant for protocols that have separate header and body -parts. +parts. On HTTP(S) servers, this will make libcurl do a HEAD request. .TP .B CURLOPT_INFILESIZE When uploading a file to a remote site, this option should be used to tell -- cgit v1.2.1 From 5911485f38a31f2b26ace84e8a3edabd3b7fc056 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 13 Oct 2003 00:10:45 +0000 Subject: use $(NROFF), not gnroff (patch by Domenico Andreoli) --- docs/libcurl/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index c90a99003..41e4838b6 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -122,7 +122,7 @@ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) -MAN2HTML= gnroff -man $< | man2html >$@ +MAN2HTML= $(NROFF) -man $< | man2html >$@ SUFFIXES = .3 .html -- cgit v1.2.1 From 8f5b80c715112fee46a7709851fc4f5a6b073f09 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 16 Oct 2003 14:14:45 +0000 Subject: removed the passwd options that are no longer supported --- docs/libcurl/curl_easy_setopt.3 | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6ae4ae9b9..22563a1ff 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "13 Sep 2003" "libcurl 7.10.8" "libcurl Manual" +.TH curl_easy_setopt 3 "16 Oct 2003" "libcurl 7.10.8" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -132,23 +132,6 @@ function actually get called. Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. .TP -.B CURLOPT_PASSWDFUNCTION -Pass a pointer to a \fIcurl_passwd_callback\fP function that will be called -instead of the internal one if libcurl requests a password. The function must -match this prototype: \fBint getpass(void *client, char *prompt, char* buffer, -int buflen );\fP. If set to NULL, it sets back the function to the internal -default one. If the function returns a non-zero value, it will abort the -operation and an error (CURLE_BAD_PASSWORD_ENTERED) will be returned. -\fIclient\fP is a generic pointer, see \fICURLOPT_PASSWDDATA\fP. \fIprompt\fP -is a zero-terminated string that is text that prefixes the input request. -\fIbuffer\fP is a pointer to data where the entered password should be stored -and \fIbuflen\fP is the maximum number of bytes that may be written in the -buffer. -.TP -.B CURLOPT_PASSWDDATA -Pass a void * to whatever data you want. The passed pointer will be the first -argument sent to the specifed \fICURLOPT_PASSWDFUNCTION\fP function. -.TP .B CURLOPT_HEADERFUNCTION Function pointer that should match the following prototype: \fIsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This -- cgit v1.2.1 From ce5db9a86ea1508b0caaeec38adc5397e390dc3e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 17 Oct 2003 13:11:00 +0000 Subject: Dominick Meglio implemented CURLOPT_MAXFILESIZE and --max-filesize. --- docs/libcurl/curl_easy_setopt.3 | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 22563a1ff..b9aa05682 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -719,6 +719,15 @@ libcurl what the expected size of the infile is. .B CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The CURLOPT_READDATA and CURLOPT_INFILESIZE are also interesting for uploads. +.TP +.B CURLOPT_MAXFILESIZE +Pass a long as parameter. This allows you to specify the maximum size (in +bytes) of a file to download. If the file requested is larger than this value, +the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. + +NOTE: The file size is not always known prior to download, and for such files +this option has no effect even if the file transfer ends up being larger than +this given limit. This concerns both FTP and HTTP transfers. .PP .SH CONNECTION OPTIONS .TP 0.4i -- cgit v1.2.1 From b3591ec464cd26e536354fb700aa33292440d936 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 18 Oct 2003 11:53:42 +0000 Subject: Added a few undocumented errors --- docs/libcurl/libcurl-errors.3 | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index bc0bbe64b..e25932250 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl-errors 3 "18 Dec 2002" "libcurl 7.10.3" "libcurl errors" +.TH libcurl-errors 3 "18 Oct 2003" "libcurl 7.10.8" "libcurl errors" .SH NAME error codes in libcurl .SH DESCRIPTION @@ -230,6 +230,27 @@ Failed sending network data. .B CURLE_RECV_ERROR (56) Failure with receiving network data. .TP +.B CURLE_RECV_ERROR (57) +Failure with receiving network data. +.TP +.B CURLE_SSL_CERTPROBLEM (58) +problem with the local certificate +.TP +.B CURLE_SSL_CIPHER (59) +couldn't use specified cipher +.TP +.B CURLE_SSL_CACERT (60) +problem with the CA cert (path? access rights?) +.TP +.B CURLE_BAD_CONTENT_ENCODING (61) +Unrecognized transfer encoding +.TP +.B CURLE_LDAP_INVALID_URL (62) +Invalid LDAP URL +.TP +.B CURLE_FILESIZE_EXCEEDED (63) +Maximum file size exceeded +.TP .B CURL_LAST This is not an error, but in the curl/curl.h file this can be used to know how many existing error codes there are. -- cgit v1.2.1 From c020ee2eb68f4b2804cb814e4c752d5d8270e5d8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 Nov 2003 12:07:19 +0000 Subject: spell! --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b9aa05682..eab64d0c5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -50,7 +50,7 @@ output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). .TP .B CURLOPT_NOPROGRESS -A non-zero parameter tells the library to shut of the built-in progress meter +A non-zero parameter tells the library to shut off the built-in progress meter completely. \fBNOTE:\fP future versions of libcurl is likely to not have any built-in -- cgit v1.2.1 From ecfb53f06dba72700b3b6847581aba277c3f2092 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 Nov 2003 12:55:53 +0000 Subject: Use .IP instead of .TP and .B for each item. --- docs/libcurl/curl_easy_setopt.3 | 356 +++++++++++++--------------------------- 1 file changed, 115 insertions(+), 241 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index eab64d0c5..d8053eeb6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -8,7 +8,6 @@ curl_easy_setopt - set options for a curl easy handle #include CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); -.ad .SH DESCRIPTION curl_easy_setopt() is used to tell libcurl how to behave. By using the appropriate options to \fIcurl_easy_setopt\fP, you can change libcurl's @@ -34,8 +33,7 @@ transfers. The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. .SH BEHAVIOR OPTIONS -.TP 0.4i -.B CURLOPT_VERBOSE +.IP CURLOPT_VERBOSE Set the parameter to non-zero to get the library to display a lot of verbose information about its operations. Very useful for libcurl and/or protocol debugging and understanding. @@ -43,20 +41,17 @@ debugging and understanding. You hardly ever want this set in production use, you will almost always want this when you debug/report problems. Another neat option for debugging is the \fICURLOPT_DEBUGFUNCTION\fP. -.TP -.B CURLOPT_HEADER +.IP CURLOPT_HEADER A non-zero parameter tells the library to include the header in the body output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). -.TP -.B CURLOPT_NOPROGRESS +.IP CURLOPT_NOPROGRESS A non-zero parameter tells the library to shut off the built-in progress meter completely. \fBNOTE:\fP future versions of libcurl is likely to not have any built-in progress meter at all. -.TP -.B CURLOPT_NOSIGNAL +.IP CURLOPT_NOSIGNAL Pass a long. If it is non-zero, libcurl will not use any functions that install signal handlers or any functions that cause signals to be sent to the process. This option is mainly here to allow multi-threaded unix applications @@ -64,8 +59,7 @@ to still set/use all timeout options etc, without risking getting signals. (Added in 7.10) .PP .SH CALLBACK OPTIONS -.TP 0.4i -.B CURLOPT_WRITEFUNCTION +.IP CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This function gets called by libcurl as soon as there is data reveiced that needs @@ -81,8 +75,7 @@ Set the \fIstream\fP argument with the \fBCURLOPT_WRITEDATA\fP option. you cannot possibly make any assumptions. It may be one byte, it may be thousands. The maximum amount of data that can be passed to the write callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE. -.TP -.B CURLOPT_WRITEDATA +.IP CURLOPT_WRITEDATA Data pointer to pass to the file write function. Note that if you specify the \fICURLOPT_WRITEFUNCTION\fP, this is the pointer you'll get as input. If you don't use a callback, you must pass a 'FILE *' as libcurl will pass this to @@ -94,8 +87,7 @@ crashes. This option is also known with the older name \fBCURLOPT_FILE\fP, the name CURLOPT_WRITEDATA was introduced in 7.9.7. -.TP -.B CURLOPT_READFUNCTION +.IP CURLOPT_READFUNCTION Function pointer that should match the following prototype: \fBsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This function gets called by libcurl as soon as it needs to read data in order to @@ -104,8 +96,7 @@ filled with at most \fIsize\fP multiplied with \fInmemb\fP number of bytes. Your function must return the actual number of bytes that you stored in that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer. -.TP -.B CURLOPT_READDATA +.IP CURLOPT_READDATA Data pointer to pass to the file read function. Note that if you specify the \fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you don't specify a read callback, this must be a valid FILE *. @@ -115,8 +106,7 @@ don't specify a read callback, this must be a valid FILE *. This option is also known with the older name \fBCURLOPT_INFILE\fP, the name CURLOPT_READDATA was introduced in 7.9.7. -.TP -.B CURLOPT_PROGRESSFUNCTION +.IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of its internal equivalent with a frequent interval during data transfer. @@ -127,12 +117,10 @@ callback will cause libcurl to abort the transfer and return Also note that \fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually get called. -.TP -.B CURLOPT_PROGRESSDATA +.IP CURLOPT_PROGRESSDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. -.TP -.B CURLOPT_HEADERFUNCTION +.IP CURLOPT_HEADERFUNCTION Function pointer that should match the following prototype: \fIsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This function gets called by libcurl as soon as there is received header data that @@ -144,14 +132,12 @@ you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the number of bytes actually written or return -1 to signal error to the library (it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return code). -.TP -.B CURLOPT_WRITEHEADER +.IP CURLOPT_WRITEHEADER Pass a pointer to be used to write the header part of the received data to. If you don't use your own callback to take care of the writing, this must be a valid FILE *. See also the \fICURLOPT_HEADERFUNCTION\fP option above on how to set a custom get-all-headers callback. -.TP -.B CURLOPT_DEBUGFUNCTION +.IP CURLOPT_DEBUGFUNCTION Function pointer that should match the following prototype: \fIint curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP CURLOPT_DEBUGFUNCTION replaces the standard debug function used when @@ -162,31 +148,23 @@ terminated, but will be exactly of the size as told by the size_t argument. Available curl_infotype values: .RS -.TP 5 -.B CURLINFO_TEXT +.IP CURLINFO_TEXT The data is informational text. -.TP -.B CURLINFO_HEADER_IN +.IP CURLINFO_HEADER_IN The data is header (or header-like) data received from the peer. -.TP -.B CURLINFO_HEADER_OUT +.IP CURLINFO_HEADER_OUT The data is header (or header-like) data sent to the peer. -.TP -.B CURLINFO_DATA_IN +.IP CURLINFO_DATA_IN The data is protocol data received from the peer. -.TP -.B CURLINFO_DATA_OUT +.IP CURLINFO_DATA_OUT The data is protocol data sent to the peer. .RE -.TP -.B CURLOPT_DEBUGDATA +.IP CURLOPT_DEBUGDATA Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in the last void * argument. This pointer is not used by libcurl, it is only passed to the callback. -.PP .SH ERROR OPTIONS -.TP 0.4i -.B CURLOPT_ERRORBUFFER +.IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error messages in. This may be more helpful than just the return code from the library. The buffer must be at least CURL_ERROR_SIZE big. @@ -196,27 +174,22 @@ debug/trace why errors happen. \fBNote:\fP if the library does not return an error, the buffer may not have been touched. Do not rely on the contents in those cases. -.TP -.B CURLOPT_STDERR +.IP CURLOPT_STDERR Pass a FILE * as parameter. This is the stream to use instead of stderr internally when reporting errors. -.TP -.B CURLOPT_FAILONERROR +.IP CURLOPT_FAILONERROR A non-zero parameter tells the library to fail silently if the HTTP code returned is equal to or larger than 300. The default action would be to return the page normally, ignoring that code. -.PP .SH NETWORK OPTIONS -.TP 0.4i -.B CURLOPT_URL +.IP CURLOPT_URL The actual URL to deal with. The parameter should be a char * to a zero terminated string. The string must remain present until curl no longer needs it, as it doesn't copy the string. \fBNOTE:\fP this option is (the only one) required to be set before \fIcurl_easy_perform(3)\fP is called. -.TP -.B CURLOPT_PROXY +.IP CURLOPT_PROXY Set HTTP proxy to use. The parameter should be a char * to a zero terminated string holding the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may @@ -233,47 +206,38 @@ you tunnel through the HTTP proxy. Such tunneling is activated with \fBNOTE2:\fP libcurl respects the environment variables \fBhttp_proxy\fP, \fBftp_proxy\fP, \fBall_proxy\fP etc, if any of those is set. -.TP -.B CURLOPT_PROXYPORT +.IP CURLOPT_PROXYPORT Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. -.TP -.B CURLOPT_PROXYTYPE +.IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for this are CURLPROXY_HTTP and CURLPROXY_SOCKS5, with the HTTP one being default. (Added in 7.10) -.TP -.B CURLOPT_HTTPPROXYTUNNEL +.IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations through a given HTTP proxy. Note that 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. -.TP -.B CURLOPT_INTERFACE +.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 name. -.TP -.B CURLOPT_DNS_CACHE_TIMEOUT +.IP CURLOPT_DNS_CACHE_TIMEOUT Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero (0) to completely disable caching, or set to -1 to make the cached entries remain forever. By default, libcurl caches info for 60 seconds. -.TP -.B CURLOPT_DNS_USE_GLOBAL_CACHE +.IP CURLOPT_DNS_USE_GLOBAL_CACHE Pass a long. If the value is non-zero, it tells curl to use a global DNS cache that will survive between easy handle creations and deletions. This is not thread-safe and this will use a global varible. -.TP -.B CURLOPT_BUFFERSIZE +.IP CURLOPT_BUFFERSIZE Pass a long specifying your prefered size for the receive buffer in libcurl. The main point of this would be that the write callback gets called more often and with smaller chunks. This is just treated as a request, not an order. You cannot be guaranteed to actually get the given size. (Added in 7.10) -.PP .SH NAMES and PASSWORDS OPTIONS (Authentication) -.TP 0.4i -.B CURLOPT_NETRC +.IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and passwords from your \fI~/.netrc\fP file, relative to user names and passwords in the URL supplied with \fICURLOPT_URL\fP. @@ -284,8 +248,7 @@ controlled by this parameter. Pass a long, set to one of the values described below. .RS -.TP 5 -.B CURL_NETRC_OPTIONAL +.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, @@ -293,26 +256,22 @@ to find the first user name and password after that \fImachine\fP, which ever information is not specified in the URL. Undefined values of the option will have this effect. -.TP -.B CURL_NETRC_IGNORED +.IP CURL_NETRC_IGNORED The library will ignore the file and use only the information in the URL. This is the default. -.TP -.B CURL_NETRC_REQUIRED +.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. .RE -.TP Only machine name, user name and password are taken into account (init macros and similar things aren't supported). \fBNote:\fP libcurl does not verify that the file has the correct properties set (as the standard Unix ftp client does). It should only be readable by user. -.TP -.B CURLOPT_USERPWD +.IP CURLOPT_USERPWD Pass a char * as parameter, which should be [user name]:[password] to use for the connection. If both the colon and password is left out, you will be prompted for it while using a colon with no password will make libcurl use an @@ -325,14 +284,12 @@ password information to hosts using the initial host name (unless CURLOPT_UNRESTRICTED_AUTH is set), so if libcurl follows locations to other hosts it will not send the user and password to those. This is enforced to prevent accidental information leakage. -.TP -.B CURLOPT_PROXYUSERPWD +.IP CURLOPT_PROXYUSERPWD Pass a char * as parameter, which should be [user name]:[password] to use for the connection to the HTTP proxy. If the password is left out, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. -.TP -.B CURLOPT_HTTPAUTH +.IP CURLOPT_HTTPAUTH Pass a long as parameter, which is set to a bitmask, to tell libcurl what 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 @@ -341,42 +298,35 @@ it to use. Note that for some methods, this will induce an extra network round-trip. Set the actual name and password with the \fICURLOPT_USERPWD\fP option. (Added in 7.10.6) .RS -.TP 5 -.B CURLAUTH_BASIC +.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 the user name and password over the network in plain text, easily captured by others. -.TP -.B CURLAUTH_DIGEST +.IP CURLAUTH_DIGEST HTTP Digest authentication. Digest authentication is defined in RFC2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. -.TP -.B CURLAUTH_GSSNEGOTIATE +.IP CURLAUTH_GSSNEGOTIATE HTTP GSS-Negotiate authentication. The GSS-Negotiate method was designed by Microsoft and is used in their web aplications. It is primarily meant as a support for Kerberos5 authentication but may be also used along with another authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. -.TP -.B CURLAUTH_NTLM +.IP CURLAUTH_NTLM HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest to prevent the password from being evesdropped. -.TP -.B CURLAUTH_ANY +.IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automaticly select the one it finds most secure. -.TP -.B CURLAUTH_ANYSAFE +.IP CURLAUTH_ANYSAFE This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automaticly select the one it finds most secure. .RE -.TP -.B CURLOPT_PROXYAUTH +.IP CURLOPT_PROXYAUTH Pass a long as parameter, which is set to a bitmask, to tell libcurl what 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 @@ -386,10 +336,8 @@ round-trip. Set the actual name and password with the \fICURLOPT_PROXYUSERPWD\fP option. The bitmask can be constructed by or'ing together the bits listed above for the \fICURLOPT_HTTPAUTH\fP option. As of this writing, only Basic and NTLM work. (Added in 7.10.7) -.PP .SH HTTP OPTIONS -.TP 0.4i -.B CURLOPT_ENCODING +.IP CURLOPT_ENCODING Sets the contents of the Accept-Encoding: header sent in an HTTP request, and enables decoding of a response when a Content-Encoding: header is received. Three encodings are supported: \fIidentity\fP, @@ -402,8 +350,7 @@ This is a request, not an order; the server may or may not do it. This option must be set (to any non-NULL value) or else any unsolicited encoding done by the server is ignored. See the special file lib/README.encoding for details. -.TP -.B CURLOPT_FOLLOWLOCATION +.IP CURLOPT_FOLLOWLOCATION A non-zero parameter tells the library to follow any Location: header that the server sends as part of a HTTP header. @@ -411,31 +358,26 @@ server sends as part of a HTTP header. new location and follow new Location: headers all the way until no more such headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects libcurl will follow. -.TP -.B CURLOPT_UNRESTRICTED_AUTH +.IP CURLOPT_UNRESTRICTED_AUTH A non-zero parameter tells the library it can continue to send authentication (user+password) when following locations, even when hostname changed. Note that this is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. -.TP -.B CURLOPT_MAXREDIRS +.IP CURLOPT_MAXREDIRS Pass a long. The set number will be the redirection limit. If that many redirections have been followed, the next redirect will cause an error (\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the \fICURLOPT_FOLLOWLOCATION\fP is used at the same time. -.TP -.B CURLOPT_PUT +.IP CURLOPT_PUT A non-zero parameter tells the library to use HTTP PUT to transfer data. The data should be set with CURLOPT_READDATA and CURLOPT_INFILESIZE. -.TP -.B CURLOPT_POST +.IP CURLOPT_POST A non-zero parameter tells the library to do a regular HTTP post. This is a normal application/x-www-form-urlencoded kind, which is the most commonly used one by HTML forms. See the CURLOPT_POSTFIELDS option for how to specify the data to post and CURLOPT_POSTFIELDSIZE in how to set the data size. Starting with libcurl 7.8, this option is obsolete. Using the CURLOPT_POSTFIELDS option will imply this option. -.TP -.B CURLOPT_POSTFIELDS +.IP CURLOPT_POSTFIELDS Pass a char * as parameter, which should be the full data to post in a HTTP post operation. You need to make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for @@ -448,14 +390,12 @@ CURLOPT_POSTFIELDS implies CURLOPT_POST. \fBNote:\fP to make multipart/formdata posts (aka rfc1867-posts), check out the \fICURLOPT_HTTPPOST\fP option. -.TP -.B CURLOPT_POSTFIELDSIZE +.IP CURLOPT_POSTFIELDSIZE If you want to post data to the server without letting libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If this size is set to zero, the library will use strlen() to get the size. -.TP -.B CURLOPT_HTTPPOST +.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 HTTP post structs as parameter. The linked list should be a fully valid @@ -463,20 +403,17 @@ list of 'struct HttpPost' structs properly filled in. The best and most elegant way to do this, 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. -.TP -.B CURLOPT_REFERER +.IP CURLOPT_REFERER Pass a pointer to a zero terminated string as parameter. It will be used to set the Referer: header in the http request sent to the remote server. This can be used to fool servers or scripts. You can also set any custom header with \fICURLOPT_HTTPHEADER\fP. -.TP -.B CURLOPT_USERAGENT +.IP CURLOPT_USERAGENT Pass a pointer to a zero terminated string as parameter. It will be used to set the User-Agent: header in the http request sent to the remote server. This can be used to fool servers or scripts. You can also set any custom header with \fICURLOPT_HTTPHEADER\fP. -.TP -.B CURLOPT_HTTPHEADER +.IP CURLOPT_HTTPHEADER Pass a pointer to a linked list of HTTP headers to pass to the server in your HTTP request. The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to @@ -497,8 +434,7 @@ request-line are headers. \fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. -.TP -.B CURLOPT_HTTP200ALIASES +.IP CURLOPT_HTTP200ALIASES Pass a pointer to a linked list of aliases to be treated as valid HTTP 200 responses. Some servers respond with a custom header response line. For example, IceCast servers respond with "ICY 200 OK". By including this string @@ -513,8 +449,7 @@ be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and alias is "MYHTTP/9.9", Libcurl will not treat the server as responding with HTTP version 9.9. Instead Libcurl will use the value set by option \fICURLOPT_HTTP_VERSION\fP. -.TP -.B CURLOPT_COOKIE +.IP CURLOPT_COOKIE Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie @@ -526,8 +461,7 @@ cookies in one string like this: "name1=content1; name2=content2;" etc. Using this option multiple times will only make the latest string override the previously ones. -.TP -.B CURLOPT_COOKIEFILE +.IP CURLOPT_COOKIEFILE Pass a pointer to a zero terminated string as parameter. It should contain the name of your file holding cookie data to read. The cookie data may be in Netscape / Mozilla cookie data format or just regular HTTP-style headers @@ -536,8 +470,7 @@ dumped to a file. Given an empty or non-existing file, this option will enable cookies for this curl handle, making it understand and parse received cookies and then use matching cookies in future request. -.TP -.B CURLOPT_COOKIEJAR +.IP CURLOPT_COOKIEJAR Pass a file name as char *, zero terminated. This will make libcurl write all internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP is called. If no cookies are known, no file will be created. Specify "-" to @@ -545,48 +478,39 @@ instead have the cookies written to stdout. Using this option also enables cookies for this session, so if you for example follow a location it will make matching cookies get sent accordingly. -.B NOTE +.IP NOTE If the cookie jar file can't be created or written to (when the curl_easy_cleanup() is called), libcurl will not and cannot report an error for this. Using CURLOPT_VERBOSE or CURLOPT_DEBUGFUNCTION will get a warning to display, but that is the only visible feedback you get about this possibly lethal situation. -.TP -.B CURLOPT_TIMECONDITION +.IP CURLOPT_TIMECONDITION Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE time value is treated. You can set this parameter to TIMECOND_IFMODSINCE or TIMECOND_IFUNMODSINCE. This is a HTTP-only feature. (TBD) -.TP -.B CURLOPT_TIMEVALUE +.IP CURLOPT_TIMEVALUE 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 CURLOPT_TIMECONDITION. -.TP -.B CURLOPT_HTTPGET +.IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. Only really usable if POST, PUT or a custom request have been used previously using the same curl handle. -.TP -.B CURLOPT_HTTP_VERSION +.IP CURLOPT_HTTP_VERSION Pass a long, set to one of the values described below. They force libcurl to use the specific HTTP versions. This is not sensible to do unless you have a good reason. .RS -.TP 5 -.B CURL_HTTP_VERSION_NONE +.IP CURL_HTTP_VERSION_NONE We don't care about what version the library uses. libcurl will use whatever it thinks fit. -.TP -.B CURL_HTTP_VERSION_1_0 +.IP CURL_HTTP_VERSION_1_0 Enforce HTTP 1.0 requests. -.TP -.B CURL_HTTP_VERSION_1_1 +.IP CURL_HTTP_VERSION_1_1 Enforce HTTP 1.1 requests. .RE -.PP .SH FTP OPTIONS -.TP 0.4i -.B CURLOPT_FTPPORT +.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 tells the remote server to connect to our specified IP address. The string may @@ -596,8 +520,7 @@ 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. -.TP -.B CURLOPT_QUOTE +.IP CURLOPT_QUOTE Pass a pointer to a linked list of FTP commands to pass to the server prior to your ftp request. This will be done before any other FTP commands are issued (even before the CWD command). The linked list should be a fully valid list of @@ -605,22 +528,19 @@ your ftp request. This will be done before any other FTP commands are issued to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL to this option. -.TP -.B CURLOPT_POSTQUOTE +.IP CURLOPT_POSTQUOTE Pass a pointer to a linked list of FTP commands to pass to the 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. -.TP -.B CURLOPT_PREQUOTE +.IP CURLOPT_PREQUOTE Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. 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. -.TP -.B CURLOPT_FTPLISTONLY +.IP CURLOPT_FTPLISTONLY A non-zero parameter tells the library to just list the names of an ftp directory, instead of doing a full directory listing that would include file sizes, dates etc. @@ -628,30 +548,25 @@ sizes, dates etc. This causes an FTP NLST command to be sent. Beware that some FTP servers list only files in their response to NLST; they might not include subdirectories and symbolic links. -.TP -.B CURLOPT_FTPAPPEND +.IP CURLOPT_FTPAPPEND A non-zero parameter tells the library to append to the remote file instead of overwrite it. This is only useful when uploading to a ftp site. -.TP -.B CURLOPT_FTP_USE_EPRT +.IP CURLOPT_FTP_USE_EPRT Pass a long. If the value is non-zero, it tells curl to use the EPRT (and LPRT) command when doing active FTP downloads (which is enabled by CURLOPT_FTPPORT). Using EPRT means that it will first attempt to use EPRT and then LPRT before using PORT, but if you pass FALSE (zero) to this option, it will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5) -.TP -.B CURLOPT_FTP_USE_EPSV +.IP CURLOPT_FTP_USE_EPSV Pass a long. If the value is non-zero, it tells curl to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. -.TP -.B CURLOPT_FTP_CREATE_MISSING_DIRS +.IP CURLOPT_FTP_CREATE_MISSING_DIRS Pass a long. If the value is non-zero, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working directory. (Added in 7.10.7) -.TP -.B CURLOPT_FTP_RESPONSE_TIMEOUT +.IP CURLOPT_FTP_RESPONSE_TIMEOUT Pass a long. Causes curl to set a timeout period (in seconds) on the amount of time that the server is allowed to take in order to generate a response message for a command before the session is considered hung. Note that while @@ -659,33 +574,27 @@ curl is waiting for a response, this value overrides CURLOPT_TIMEOUT. It is recommended that if used in conjunction with CURLOPT_TIMEOUT, you set CURLOPT_FTP_RESPONSE_TIMEOUT to a value smaller than CURLOPT_TIMEOUT. (Added in 7.10.8) -.PP .SH PROTOCOL OPTIONS -.TP 0.4i -.B CURLOPT_TRANSFERTEXT +.IP CURLOPT_TRANSFERTEXT A non-zero parameter tells the library to use ASCII mode for ftp transfers, instead of the default binary transfer. For LDAP transfers it gets the data in plain text instead of HTML and 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 or similar. -.TP -.B CURLOPT_CRLF +.IP CURLOPT_CRLF Convert Unix newlines to CRLF newlines on transfers. -.TP -.B CURLOPT_RANGE +.IP CURLOPT_RANGE Pass a char * as parameter, which should contain the specified range you want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in \fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation techniques). -.TP -.B CURLOPT_RESUME_FROM +.IP CURLOPT_RESUME_FROM Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. -.TP -.B CURLOPT_CUSTOMREQUEST +.IP CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST when doing an ftp directory listing. This is useful for doing DELETE or other @@ -699,28 +608,23 @@ could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and \fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to replace or extend the set of headers sent by libcurl. Use \fICURLOPT_HTTP_VERSION\fP to change HTTP version. -.TP -.B CURLOPT_FILETIME +.IP CURLOPT_FILETIME Pass a long. If it is a non-zero value, libcurl will attempt to get the modification date of the remote document in this operation. This requires that the remote server sends the time or replies to a time querying command. The \fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument can be used after a transfer to extract the received time (if any). -.TP -.B CURLOPT_NOBODY +.IP CURLOPT_NOBODY A non-zero parameter tells the library to not include the body-part in the output. This is only relevant for protocols that have separate header and body parts. On HTTP(S) servers, this will make libcurl do a HEAD request. -.TP -.B CURLOPT_INFILESIZE +.IP CURLOPT_INFILESIZE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. -.TP -.B CURLOPT_UPLOAD +.IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The CURLOPT_READDATA and CURLOPT_INFILESIZE are also interesting for uploads. -.TP -.B CURLOPT_MAXFILESIZE +.IP CURLOPT_MAXFILESIZE Pass a long as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. @@ -728,10 +632,8 @@ the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. NOTE: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers. -.PP .SH CONNECTION OPTIONS -.TP 0.4i -.B CURLOPT_TIMEOUT +.IP CURLOPT_TIMEOUT Pass a long as parameter containing the maximum time in seconds that you allow the libcurl transfer operation to take. Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk @@ -740,18 +642,15 @@ SIGALRM to enable time-outing system calls. \fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as it uses signals unless CURLOPT_NOSIGNAL (see above) is set. -.TP -.B CURLOPT_LOW_SPEED_LIMIT +.IP CURLOPT_LOW_SPEED_LIMIT Pass a long as parameter. It contains the transfer speed in bytes per second that the transfer should be below during CURLOPT_LOW_SPEED_TIME seconds for the library to consider it too slow and abort. -.TP -.B CURLOPT_LOW_SPEED_TIME +.IP CURLOPT_LOW_SPEED_TIME Pass a long as parameter. It contains the time in seconds that the transfer should be below the CURLOPT_LOW_SPEED_LIMIT for the library to consider it too slow and abort. -.TP -.B CURLOPT_MAXCONNECTS +.IP CURLOPT_MAXCONNECTS 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. Default is 5, and there isn't much point in changing this @@ -766,8 +665,7 @@ open connections to increase. \fBNOTE:\fP if you already have performed transfers with this curl handle, setting a smaller MAXCONNECTS than before may cause open connections to get closed unnecessarily. -.TP -.B CURLOPT_CLOSEPOLICY +.IP CURLOPT_CLOSEPOLICY Pass a long. This option sets what policy libcurl should use when the connection cache is filled and one of the open connections has to be closed to make room for a new connection. This must be one of the CURLCLOSEPOLICY_* @@ -777,24 +675,21 @@ likely to be capable of re-use. Use \fICURLCLOSEPOLICY_OLDEST\fP to make libcurl close the oldest connection, the one that was created first among the ones in the connection cache. The other close policies are not support yet. -.TP -.B CURLOPT_FRESH_CONNECT +.IP CURLOPT_FRESH_CONNECT Pass a long. Set to non-zero to make the next transfer use a new (fresh) connection by force. If the connection cache is full before this connection, one of the existing connections will be closed as according to the selected or default policy. This option should be used with caution and only if you understand what it does. Set this to 0 to have libcurl attempt re-using an existing connection (default behavior). -.TP -.B CURLOPT_FORBID_REUSE +.IP CURLOPT_FORBID_REUSE Pass a long. Set to non-zero 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. 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 re-use (default behavior). -.TP -.B CURLOPT_CONNECTTIMEOUT +.IP CURLOPT_CONNECTTIMEOUT Pass a long. It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once it has connected, this option is of no more use. Set to zero to disable @@ -803,20 +698,16 @@ timeouts). See also the \fICURLOPT_TIMEOUT\fP option. \fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as it uses signals unless CURLOPT_NOSIGNAL (see above) is set. -.PP .SH SSL and SECURITY OPTIONS -.TP 0.4i -.B CURLOPT_SSLCERT +.IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be the file name of your certificate. The default format is "PEM" and can be changed with \fICURLOPT_SSLCERTTYPE\fP. -.TP -.B CURLOPT_SSLCERTTYPE +.IP CURLOPT_SSLCERTTYPE Pass a pointer to a zero terminated string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER". (Added in 7.9.3) -.TP -.B CURLOPT_SSLCERTPASSWD +.IP CURLOPT_SSLCERTPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as the password required to use the CURLOPT_SSLCERT certificate. If the password is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can @@ -825,47 +716,40 @@ be used to set your own prompt function. \fBNOTE:\fPThis option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and only cept for backward compatibility. You never needed a pass phrase to load a certificate but you need one to load your private key. -.TP -.B CURLOPT_SSLKEY +.IP CURLOPT_SSLKEY Pass a pointer to a zero terminated string as parameter. The string should be the file name of your private key. The default format is "PEM" and can be changed with \fICURLOPT_SSLKEYTYPE\fP. -.TP -.B CURLOPT_SSLKEYTYPE +.IP CURLOPT_SSLKEYTYPE Pass a pointer to a zero terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG". \fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to the engine. You have to set the crypto engine with \fICURLOPT_SSL_ENGINE\fP. -.TP -.B CURLOPT_SSLKEYPASSWD +.IP CURLOPT_SSLKEYPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as the password required to use the \fICURLOPT_SSLKEY\fP private key. If the password is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. -.TP -.B CURLOPT_SSL_ENGINE +.IP CURLOPT_SSL_ENGINE Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private key. \fBNOTE:\fPIf the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. -.TP -.B CURLOPT_SSL_ENGINEDEFAULT +.IP CURLOPT_SSL_ENGINEDEFAULT Sets the actual crypto engine as the default for (asymetric) crypto operations. \fBNOTE:\fPIf the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is returned. -.TP -.B CURLOPT_SSLVERSION +.IP CURLOPT_SSLVERSION Pass a long as parameter. Set what version of SSL to attempt to use, 2 or 3. By default, the SSL library will try to solve this by itself although some servers make this difficult why you at times may have to use this option. -.TP -.B CURLOPT_SSL_VERIFYPEER +.IP CURLOPT_SSL_VERIFYPEER Pass a long that is set to a zero value to stop curl from verifying the peer's certificate (7.10 starting setting this option to TRUE by default). Alternate certificates to verify against can be specified with the CURLOPT_CAINFO option @@ -873,35 +757,29 @@ or a certificate directory can be specified with the CURLOPT_CAPATH option (Added in 7.9.8). As of 7.10, curl installs a default bundle. CURLOPT_SSL_VERIFYHOST may also need to be set to 1 or 0 if CURLOPT_SSL_VERIFYPEER is disabled (it defaults to 2). -.TP -.B CURLOPT_CAINFO +.IP CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This only makes sense when used in combination with the CURLOPT_SSL_VERIFYPEER option. -.TP -.B CURLOPT_CAPATH +.IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate directory must be prepared using the openssl c_rehash utility. This only makes sense when used in combination with the CURLOPT_SSL_VERIFYPEER option. The CAPATH function apparently does not work in Windows due to some limitation in openssl. (Added in 7.9.8) -.TP -.B CURLOPT_RANDOM_FILE +.IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, the more secure the SSL connection will become. -.TP -.B CURLOPT_EGDSOCKET +.IP CURLOPT_EGDSOCKET Pass a char * to the zero terminated path name to the Entropy Gathering Daemon socket. It will be used to seed the random engine for SSL. -.TP -.B CURLOPT_SSL_VERIFYHOST +.IP CURLOPT_SSL_VERIFYHOST Pass a long. Set if we should verify the Common name from the peer certificate in the SSL handshake, set 1 to check existence, 2 to ensure that it matches the provided hostname. This is by default set to 2. (default changed in 7.10) -.TP -.B CURLOPT_SSL_CIPHER_LIST +.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 syntactly correct, it consists of one or more cipher strings separated by colons. Commas or spaces @@ -912,21 +790,17 @@ compile OpenSSL. You'll find more details about cipher lists on this URL: \fIhttp://www.openssl.org/docs/apps/ciphers.html\fP -.TP -.B CURLOPT_KRB4LEVEL +.IP CURLOPT_KRB4LEVEL Pass a char * as parameter. Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or \&'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos4. The kerberos support only works for FTP. -.PP .SH OTHER OPTIONS -.TP 0.4i -.B CURLOPT_PRIVATE +.IP CURLOPT_PRIVATE Pass a char * as parameter, pointing to data that should be associated with the curl handle. The pointer can be subsequently retrieved using the CURLINFO_PRIVATE options to curl_easy_getinfo. (Added in 7.10.3) -.PP .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP -- cgit v1.2.1 From 9b7c311929232566e91c02bfff7ef22a312a962c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 Nov 2003 13:03:45 +0000 Subject: .TP and .B replaced with .IP --- docs/libcurl/libcurl-errors.3 | 197 ++++++++++++++---------------------------- 1 file changed, 66 insertions(+), 131 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index e25932250..84dc5dd03 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -18,240 +18,175 @@ This man page is meant to describe libcurl 7.9.6 and later. Earlier versions might have had quirks not mentioned here. CURLcode is one of the following: -.RS 1 -.TP 5 -.B CURLE_OK (0) +.RS 0 +.IP "CURLE_OK (0)" All fine. Proceed as usual. -.TP -.B CURLE_UNSUPPORTED_PROTOCOL (1) +.IP "CURLE_UNSUPPORTED_PROTOCOL (1)" The URL you passed to libcurl used a protocol that this libcurl does not support. The support might be a compile-time option that you didn't use, it can be a misspelled protocol string or just a protocol libcurl has no code for. -.TP -.B CURLE_FAILED_INIT (2) +.IP "CURLE_FAILED_INIT (2)" Very early initialization code failed. This is likely to be an internal error or problem. -.TP -.B CURLE_URL_MALFORMAT (3) +.IP "CURLE_URL_MALFORMAT (3)" The URL was not properly formatted. -.TP -.B CURLE_URL_MALFORMAT_USER (4) +.IP "CURLE_URL_MALFORMAT_USER (4)" URL user malformatted. The user-part of the URL syntax was not correct. -.TP -.B CURLE_COULDNT_RESOLVE_PROXY (5) +.IP "CURLE_COULDNT_RESOLVE_PROXY (5)" Couldn't resolve proxy. The given proxy host could not be resolved. -.TP -.B CURLE_COULDNT_RESOLVE_HOST (6) +.IP "CURLE_COULDNT_RESOLVE_HOST (6)" Couldn't resolve host. The given remote host was not resolved. -.TP -.B CURLE_COULDNT_CONNECT (7) +.IP "CURLE_COULDNT_CONNECT (7)" Failed to connect() to host or proxy. -.TP -.B CURLE_FTP_WEIRD_SERVER_REPLY (8) +.IP "CURLE_FTP_WEIRD_SERVER_REPLY (8)" After connecting to a FTP server, libcurl expects to get a certain reply back. This error code implies that it god a strange or bad reply. The given remote server is probably not an OK FTP server. -.TP -.B CURLE_FTP_ACCESS_DENIED (9) +.IP "CURLE_FTP_ACCESS_DENIED (9)" We were denied access when trying to login to an FTP server or when trying to change working directory to the one given in the URL. -.TP -.B CURLE_FTP_USER_PASSWORD_INCORRECT (10) +.IP "CURLE_FTP_USER_PASSWORD_INCORRECT (10)" The username and/or the password were incorrect when trying to login to an FTP server. -.TP -.B CURLE_FTP_WEIRD_PASS_REPLY (11) +.IP "CURLE_FTP_WEIRD_PASS_REPLY (11)" After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. -.TP -.B CURLE_FTP_WEIRD_USER_REPLY (12) +.IP "CURLE_FTP_WEIRD_USER_REPLY (12)" After having sent user name to the FTP server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. -.TP -.B CURLE_FTP_WEIRD_PASV_REPLY (13) +.IP "CURLE_FTP_WEIRD_PASV_REPLY (13)" libcurl failed to get a sensible result back from the server as a response to either a PASV or a EPSV command. The server is flawed. -.TP -.B CURLE_FTP_WEIRD_227_FORMAT (14) +.IP "CURLE_FTP_WEIRD_227_FORMAT (14)" FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back. -.TP -.B CURLE_FTP_CANT_GET_HOST (15) +.IP "CURLE_FTP_CANT_GET_HOST (15)" An internal failure to lookup the host used for the new connection. -.TP -.B CURLE_FTP_CANT_RECONNECT (16) +.IP "CURLE_FTP_CANT_RECONNECT (16)" A bad return code on either PASV or EPSV was sent by the FTP server, preventing libcurl from being able to continue. -.TP -.B CURLE_FTP_COULDNT_SET_BINARY (17) +.IP "CURLE_FTP_COULDNT_SET_BINARY (17)" Received an error when trying to set the transfer mode to binary. -.TP -.B CURLE_PARTIAL_FILE (18) +.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 doesn't match the previously given size. -.TP -.B CURLE_FTP_COULDNT_RETR_FILE (19) +.IP "CURLE_FTP_COULDNT_RETR_FILE (19)" This was either a weird reply to a 'RETR' command or a zero byte transfer complete. -.TP -.B CURLE_FTP_WRITE_ERROR (20) +.IP "CURLE_FTP_WRITE_ERROR (20)" After a completed file transfer, the FTP server did not respond a proper \"transfer successful\" code. -.TP -.B CURLE_FTP_QUOTE_ERROR (21) +.IP "CURLE_FTP_QUOTE_ERROR (21)" When sending custom "QUOTE" commands to the remote server, one of the commands returned an error code that was 400 or higher. -.TP -.B CURLE_HTTP_RETURNED_ERROR (22) +.IP "CURLE_HTTP_RETURNED_ERROR (22)" This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server returns an error code that is >= 400. -.TP -.B CURLE_WRITE_ERROR (23) +.IP "CURLE_WRITE_ERROR (23)" An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback. -.TP -.B CURLE_MALFORMAT_USER (24) +.IP "CURLE_MALFORMAT_USER (24)" Malformat user. User name badly specified. *Not currently used* -.TP -.B CURLE_FTP_COULDNT_STOR_FILE (25) +.IP "CURLE_FTP_COULDNT_STOR_FILE (25)" FTP couldn't STOR file. The server denied the STOR operation. The error buffer usually contains the server's explanation to this. -.TP -.B CURLE_READ_ERROR (26) +.IP "CURLE_READ_ERROR (26)" There was a problem reading a local file or an error returned by the read callback. -.TP -.B CURLE_OUT_OF_MEMORY (27) +.IP "CURLE_OUT_OF_MEMORY (27)" Out of memory. A memory allocation request failed. This is serious badness and things are severly screwed up if this ever occur. -.TP -.B CURLE_OPERATION_TIMEOUTED (28) +.IP "CURLE_OPERATION_TIMEOUTED (28)" Operation timeout. The specified time-out period was reached according to the conditions. -.TP -.B CURLE_FTP_COULDNT_SET_ASCII (29) +.IP "CURLE_FTP_COULDNT_SET_ASCII (29)" libcurl failed to set ASCII transfer type (TYPE A). -.TP -.B CURLE_FTP_PORT_FAILED (30) +.IP "CURLE_FTP_PORT_FAILED (30)" The FTP PORT command returned error. This mostly happen when you haven't specified a good enough address for libcurl to use. See \fICURLOPT_FTPPORT\fP. -.TP -.B CURLE_FTP_COULDNT_USE_REST (31) +.IP "CURLE_FTP_COULDNT_USE_REST (31)" The FTP REST command returned error. This should never happen if the server is sane. -.TP -.B CURLE_FTP_COULDNT_GET_SIZE (32) +.IP "CURLE_FTP_COULDNT_GET_SIZE (32)" The FTP SIZE command returned errror. SIZE is not a kosher FTP command, it is an extension and not all servers support it. This is not a surprising error. -.TP -.B CURLE_HTTP_RANGE_ERROR (33) +.IP "CURLE_HTTP_RANGE_ERROR (33)" The HTTP server does not support or accept range requests. -.TP -.B CURLE_HTTP_POST_ERROR (34) +.IP "CURLE_HTTP_POST_ERROR (34)" This is an odd error that mainly occurs due to internal confusion. -.TP -.B CURLE_SSL_CONNECT_ERROR (35) +.IP "CURLE_SSL_CONNECT_ERROR (35)" A problem occured somewhere in the SSL/TLS handshake. You really want the error buffer and read the message there as it pinpoints the problem slightly more. Could be certificates (file formats, paths, permissions), passwords, and others. -.TP -.B CURLE_FTP_BAD_DOWNLOAD_RESUME (36) +.IP "CURLE_FTP_BAD_DOWNLOAD_RESUME (36)" Attempting FTP resume beyond file size. -.TP -.B CURLE_FILE_COULDNT_READ_FILE (37) +.IP "CURLE_FILE_COULDNT_READ_FILE (37)" A file given with FILE:// couldn't be opened. Most likely because the file path doesn't identify an existing file. Did you check file permissions? -.TP -.B CURLE_LDAP_CANNOT_BIND (38) +.IP "CURLE_LDAP_CANNOT_BIND (38)" LDAP cannot bind. LDAP bind operation failed. -.TP -.B CURLE_LDAP_SEARCH_FAILED (39) +.IP "CURLE_LDAP_SEARCH_FAILED (39)" LDAP search failed. -.TP -.B CURLE_LIBRARY_NOT_FOUND (40) +.IP "CURLE_LIBRARY_NOT_FOUND (40)" Library not found. The LDAP library was not found. -.TP -.B CURLE_FUNCTION_NOT_FOUND (41) +.IP "CURLE_FUNCTION_NOT_FOUND (41)" Function not found. A required LDAP function was not found. -.TP -.B CURLE_ABORTED_BY_CALLBACK (42) +.IP "CURLE_ABORTED_BY_CALLBACK (42)" Aborted by callback. A callback returned "abort" to libcurl. -.TP -.B CURLE_BAD_FUNCTION_ARGUMENT (43) +.IP "CURLE_BAD_FUNCTION_ARGUMENT (43)" Internal error. A function was called with a bad parameter. -.TP -.B CURLE_BAD_CALLING_ORDER (44) +.IP "CURLE_BAD_CALLING_ORDER (44)" Internal error. A function was called in a bad order. -.TP -.B CURLE_HTTP_PORT_FAILED (45) +.IP "CURLE_HTTP_PORT_FAILED (45)" Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections' source IP address with CURLOPT_INTERFACE. -.TP -.B CURLE_BAD_PASSWORD_ENTERED (46) +.IP "CURLE_BAD_PASSWORD_ENTERED (46)" Bad password entered. An error was signaled when the password was entered. This can also be the result of a "bad password" returned from a specified password callback. -.TP -.B CURLE_TOO_MANY_REDIRECTS (47) +.IP "CURLE_TOO_MANY_REDIRECTS (47)" Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS. -.TP -.B CURLE_UNKNOWN_TELNET_OPTION (48) +.IP "CURLE_UNKNOWN_TELNET_OPTION (48)" An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to the appropriate documentation. -.TP -.B CURLE_TELNET_OPTION_SYNTAX (49) +.IP "CURLE_TELNET_OPTION_SYNTAX (49)" A telnet option string was Illegally formatted. -.TP -.B CURLE_OBSOLETE (50) +.IP "CURLE_OBSOLETE (50)" This is not an error. This used to be another error code in an old libcurl version and is currently unused. -.TP -.B CURLE_SSL_PEER_CERTIFICATE (51) +.IP "CURLE_SSL_PEER_CERTIFICATE (51)" The remote server's SSL certificate was deemed not OK. -.TP -.B CURLE_GOT_NOTHING (52) +.IP "CURLE_GOT_NOTHING (52)" Nothing was returned from the server, and under the circumstances, getting nothing is considered an error. -.TP -.B CURLE_SSL_ENGINE_NOTFOUND (53) +.IP "CURLE_SSL_ENGINE_NOTFOUND (53)" The specified crypto engine wasn't found. -.TP -.B CURLE_SSL_ENGINE_SETFAILED (54) +.IP "CURLE_SSL_ENGINE_SETFAILED (54)" Failed setting the selected SSL crypto engine as default! -.TP -.B CURLE_SEND_ERROR (55) +.IP "CURLE_SEND_ERROR (55)" Failed sending network data. -.TP -.B CURLE_RECV_ERROR (56) +.IP "CURLE_RECV_ERROR (56)" Failure with receiving network data. -.TP -.B CURLE_RECV_ERROR (57) +.IP "CURLE_RECV_ERROR (57)" Failure with receiving network data. -.TP -.B CURLE_SSL_CERTPROBLEM (58) +.IP "CURLE_SSL_CERTPROBLEM (58)" problem with the local certificate -.TP -.B CURLE_SSL_CIPHER (59) +.IP "CURLE_SSL_CIPHER (59)" couldn't use specified cipher -.TP -.B CURLE_SSL_CACERT (60) +.IP "CURLE_SSL_CACERT (60)" problem with the CA cert (path? access rights?) -.TP -.B CURLE_BAD_CONTENT_ENCODING (61) +.IP "CURLE_BAD_CONTENT_ENCODING (61)" Unrecognized transfer encoding -.TP -.B CURLE_LDAP_INVALID_URL (62) +.IP "CURLE_LDAP_INVALID_URL (62)" Invalid LDAP URL -.TP -.B CURLE_FILESIZE_EXCEEDED (63) +.IP "CURLE_FILESIZE_EXCEEDED (63)" Maximum file size exceeded -.TP -.B CURL_LAST +.IP "CURL_LAST" This is not an error, but in the curl/curl.h file this can be used to know how many existing error codes there are. .RE -- cgit v1.2.1 From 445f54db57bf5a41c56ba9bf98316bf996070877 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 Nov 2003 13:27:28 +0000 Subject: consistant with other man pages --- docs/libcurl/curl_easy_getinfo.3 | 77 ++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 50 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index f3473bc3a..59d06e1da 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -4,12 +4,12 @@ .\" .TH curl_easy_getinfo 3 "20 Aug 2003" "libcurl 7.10.8" "libcurl Manual" .SH NAME -curl_easy_getinfo - Extract information from a curl session (added in 7.4) +curl_easy_getinfo - extract information from a curl handle .SH SYNOPSIS .B #include -.sp -.BI "CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );" -.ad + +.B "CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... );" + .SH DESCRIPTION Request internal information from the curl session with this function. The third argument @@ -21,108 +21,85 @@ CURLE_OK. This function is intended to get used *AFTER* a performed transfer, all results from this function are undefined until the transfer is completed. .SH AVAILABLE INFORMATION These are informations that can be extracted: -.TP 0.8i -.B CURLINFO_EFFECTIVE_URL +.IP CURLINFO_EFFECTIVE_URL Pass a pointer to a 'char *' to receive the last used effective URL. -.TP -.B CURLINFO_RESPONSE_CODE +.IP CURLINFO_RESPONSE_CODE Pass a pointer to a long to receive the last received HTTP or FTP code. This option was known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. -.TP -.B CURLINFO_FILETIME +.IP CURLINFO_FILETIME Pass a pointer to a long to receive the remote time of the retrieved document. If you get -1, it can be because of many reasons (unknown, the server hides it or the server doesn't support the command that tells document time etc) and the time of the document is unknown. Note that you must tell the server to collect this information before the transfer is made, by using the CURLOPT_FILETIME option to \fIcurl_easy_setopt(3)\fP. (Added in 7.5) -.TP -.B CURLINFO_TOTAL_TIME +.IP CURLINFO_TOTAL_TIME Pass a pointer to a double to receive the total transaction time in seconds for the previous transfer. This time does not include the connect time, so if you want the complete operation time, you should add the CURLINFO_CONNECT_TIME. -.TP -.B CURLINFO_NAMELOOKUP_TIME +.IP CURLINFO_NAMELOOKUP_TIME Pass a pointer to a double to receive the time, in seconds, it took from the start until the name resolving was completed. -.TP -.B CURLINFO_CONNECT_TIME +.IP CURLINFO_CONNECT_TIME Pass a pointer to a double to receive the time, in seconds, it took from the start until the connect to the remote host (or proxy) was completed. -.TP -.B CURLINFO_PRETRANSFER_TIME +.IP CURLINFO_PRETRANSFER_TIME Pass a pointer to a double to receive the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. -.TP -.B CURLINFO_STARTTRANSFER_TIME +.IP CURLINFO_STARTTRANSFER_TIME Pass a pointer to a double to receive the time, in seconds, it took from the start until the first byte is just about to be transfered. This includes CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate the result. -.TP -.B CURLINFO_REDIRECT_TIME +.IP CURLINFO_REDIRECT_TIME Pass a pointer to a double to receive the total time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. CURLINFO_REDIRECT_TIME contains the complete execution time for multiple redirections. (Added in 7.9.7) -.TP -.B CURLINFO_REDIRECT_COUNT +.IP CURLINFO_REDIRECT_COUNT Pass a pointer to a long to receive the total number of redirections that were actually followed. (Added in 7.9.7) -.TP -.B CURLINFO_SIZE_UPLOAD +.IP CURLINFO_SIZE_UPLOAD Pass a pointer to a double to receive the total amount of bytes that were uploaded. -.TP -.B CURLINFO_SIZE_DOWNLOAD +.IP CURLINFO_SIZE_DOWNLOAD Pass a pointer to a double to receive the total amount of bytes that were downloaded. The amount is only for the latest transfer and will be reset again for each new transfer. -.TP -.B CURLINFO_SPEED_DOWNLOAD +.IP CURLINFO_SPEED_DOWNLOAD Pass a pointer to a double to receive the average download speed that curl measured for the complete download. -.TP -.B CURLINFO_SPEED_UPLOAD +.IP CURLINFO_SPEED_UPLOAD Pass a pointer to a double to receive the average upload speed that curl measured for the complete upload. -.TP -.B CURLINFO_HEADER_SIZE +.IP CURLINFO_HEADER_SIZE Pass a pointer to a long to receive the total size of all the headers received. -.TP -.B CURLINFO_REQUEST_SIZE +.IP CURLINFO_REQUEST_SIZE Pass a pointer to a long to receive the total size of the issued requests. This is so far only for HTTP requests. Note that this may be more than one request if FOLLOWLOCATION is true. -.TP -.B CURLINFO_SSL_VERIFYRESULT +.IP CURLINFO_SSL_VERIFYRESULT Pass a pointer to a long to receive the result of the certification verification that was requested (using the CURLOPT_SSL_VERIFYPEER option to curl_easy_setopt). (Added in 7.4.2) -.TP -.B CURLINFO_CONTENT_LENGTH_DOWNLOAD +.IP CURLINFO_CONTENT_LENGTH_DOWNLOAD Pass a pointer to a double to receive the content-length of the download. This is the value read from the Content-Length: field. (Added in 7.6.1) -.TP -.B CURLINFO_CONTENT_LENGTH_UPLOAD +.IP CURLINFO_CONTENT_LENGTH_UPLOAD Pass a pointer to a double to receive the specified size of the upload. -(Added in 7.6.1) -.TP -.B CURLINFO_CONTENT_TYPE +.IP CURLINFO_CONTENT_TYPE Pass a pointer to a 'char *' to receive the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get NULL, it means that the server didn't send a valid Content-Type header or that the protocol used doesn't support this. (Added in 7.9.4) -.TP -.B CURLINFO_PRIVATE +.IP CURLINFO_PRIVATE Pass a pointer to a 'char *' to receive the pointer to the private data -associated with the curl handle (set with the CURLOPT_PRIVATE option to curl_easy_setopt). -(Added in 7.10.3) -.PP +associated with the curl handle (set with the CURLOPT_PRIVATE option to +curl_easy_setopt). (Added in 7.10.3) .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. -- cgit v1.2.1 From 344c3789969bcf35759f5fc09a216bbc64245a32 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 Nov 2003 13:30:27 +0000 Subject: use .BR to refer to other man pages to make it easier for parsers to know --- docs/libcurl/libcurl.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index c474d3176..c121941d3 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -27,7 +27,8 @@ option of using the "easy" interface, or the "multi" interface. The easy interface is a synchronous interface with which you call \fIcurl_easy_perform\fP and let it perform the transfer. When it is completed, the function return and you can continue. More details are found in the -\fIlibcurl-easy\fP man page. +.BR "libcurl-easy (3)" +man page. The multi interface on the other hand is an asynchronous interface, that you call and that performs only a little piece of the tranfer on each invoke. It -- cgit v1.2.1 From 7ffb8c6aeeda1d739fe8ab16bc524740fffe8f36 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 5 Nov 2003 15:51:25 +0000 Subject: use roffit to make HTML from man pages http://daniel.haxx.se/projects/roffit/ --- docs/libcurl/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 41e4838b6..9ef967d0a 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -122,7 +122,7 @@ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) -MAN2HTML= $(NROFF) -man $< | man2html >$@ +MAN2HTML= roffit < $< >$@ SUFFIXES = .3 .html -- cgit v1.2.1 From 67dcddbef715649f227b8dcbd7fa2203ed335661 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 5 Nov 2003 15:52:00 +0000 Subject: minor format edits --- docs/libcurl/curl_easy_cleanup.3 | 4 ++-- docs/libcurl/curl_easy_duphandle.3 | 4 ++-- docs/libcurl/curl_easy_init.3 | 4 ++-- docs/libcurl/curl_escape.3 | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index 4026cf240..6c76e92b5 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -7,9 +7,9 @@ curl_easy_cleanup - End a libcurl easy session .SH SYNOPSIS .B #include -.sp + .BI "void curl_easy_cleanup(CURL *" handle ");" -.ad + .SH DESCRIPTION This function must be the last function to call for an easy session. It is the opposite of the \fIcurl_easy_init\fP function and must be called with the same diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 index b570dc432..b8463345b 100644 --- a/docs/libcurl/curl_easy_duphandle.3 +++ b/docs/libcurl/curl_easy_duphandle.3 @@ -7,9 +7,9 @@ curl_easy_duphandle - Clone a libcurl session handle .SH SYNOPSIS .B #include -.sp + .BI "CURL *curl_easy_duphandle(CURL *"handle ");" -.ad + .SH DESCRIPTION This function will return a new curl handle, a duplicate, using all the options previously set in the input curl \fIhandle\fP. Both handles can diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 83f361f4b..1c2ec2be4 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -7,9 +7,9 @@ curl_easy_init - Start a libcurl easy session .SH SYNOPSIS .B #include -.sp + .BI "CURL *curl_easy_init( );" -.ad + .SH DESCRIPTION This function must be the first function to call, and it returns a CURL easy handle that you must use as input to other easy-functions. curl_easy_init diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 395363e64..7e40cc550 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -23,4 +23,4 @@ You must curl_free() the returned string when you're done with it. .SH RETURN VALUE A pointer to a zero terminated string or NULL if it failed. .SH "SEE ALSO" -.I curl_unescape(), curl_free(), RFC 2396 +.BR curl_unescape(), curl_free(), RFC 2396 -- cgit v1.2.1 From eee3f131349be028989afb8aa7ed0fea874f871c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 6 Nov 2003 12:52:48 +0000 Subject: removed the _last since that is by definition not an error code --- docs/libcurl/libcurl-errors.3 | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 84dc5dd03..4a737dbe3 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -186,9 +186,6 @@ Unrecognized transfer encoding Invalid LDAP URL .IP "CURLE_FILESIZE_EXCEEDED (63)" Maximum file size exceeded -.IP "CURL_LAST" -This is not an error, but in the curl/curl.h file this can be used to know how -many existing error codes there are. .RE .SH "CURLMcode" -- cgit v1.2.1 From fe0b5801ece9279dcbaadc73578e1fc57abb88b6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 7 Nov 2003 09:15:28 +0000 Subject: mark options better --- docs/libcurl/curl_easy_setopt.3 | 163 ++++++++++++++++++++-------------------- 1 file changed, 83 insertions(+), 80 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d8053eeb6..4ce0b841a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "16 Oct 2003" "libcurl 7.10.8" "libcurl Manual" +.TH curl_easy_setopt 3 "7 Nov 2003" "libcurl 7.10.8" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -57,6 +57,9 @@ install signal handlers or any functions that cause signals to be sent to the process. This option is mainly here to allow multi-threaded unix applications to still set/use all timeout options etc, without risking getting signals. (Added in 7.10) + +Consider building libcurl with ares support to enable asynchronous DNS +lookups. It enables nice timeouts for name resolves without signals. .PP .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION @@ -69,7 +72,7 @@ of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library and it will abort the transfer and return \fICURLE_WRITE_ERROR\fP. -Set the \fIstream\fP argument with the \fBCURLOPT_WRITEDATA\fP option. +Set the \fIstream\fP argument with the \fICURLOPT_WRITEDATA\fP option. \fBNOTE:\fP you will be passed as much data as possible in all invokes, but you cannot possibly make any assumptions. It may be one byte, it may be @@ -85,8 +88,8 @@ fwrite() when writing data. \fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience crashes. -This option is also known with the older name \fBCURLOPT_FILE\fP, the name -CURLOPT_WRITEDATA was introduced in 7.9.7. +This option is also known with the older name \fICURLOPT_FILE\fP, the name +\fICURLOPT_WRITEDATA\fP was introduced in 7.9.7. .IP CURLOPT_READFUNCTION Function pointer that should match the following prototype: \fBsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This @@ -104,8 +107,8 @@ don't specify a read callback, this must be a valid FILE *. \fBNOTE:\fP 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 \fBCURLOPT_INFILE\fP, the name -CURLOPT_READDATA was introduced in 7.9.7. +This option is also known with the older name \fICURLOPT_INFILE\fP, the name +\fICURLOPT_READDATA\fP was introduced in 7.9.7. .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of @@ -140,10 +143,10 @@ set a custom get-all-headers callback. .IP CURLOPT_DEBUGFUNCTION Function pointer that should match the following prototype: \fIint curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP -CURLOPT_DEBUGFUNCTION replaces the standard debug function used when -CURLOPT_VERBOSE is in effect. This callback receives debug information, as -specified with the \fIcurl_infotype\fP argument. This funtion must return 0. -The data pointed to by the char * passed to this function WILL NOT be zero +\fICURLOPT_DEBUGFUNCTION\fP replaces the standard debug function used when +\fICURLOPT_VERBOSE \fP is in effect. This callback receives debug information, +as specified with the \fBcurl_infotype\fP argument. This funtion must return +0. The data pointed to by the char * passed to this function WILL NOT be zero terminated, but will be exactly of the size as told by the size_t argument. Available curl_infotype values: @@ -160,9 +163,9 @@ The data is protocol data received from the peer. The data is protocol data sent to the peer. .RE .IP CURLOPT_DEBUGDATA -Pass a pointer to whatever you want passed in to your CURLOPT_DEBUGFUNCTION in -the last void * argument. This pointer is not used by libcurl, it is only -passed to the callback. +Pass a pointer to whatever you want passed in to your +\fICURLOPT_DEBUGFUNCTION\fP in the last void * argument. This pointer is not +used by libcurl, it is only passed to the callback. .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error @@ -175,8 +178,8 @@ debug/trace why errors happen. \fBNote:\fP if the library does not return an error, the buffer may not have been touched. Do not rely on the contents in those cases. .IP CURLOPT_STDERR -Pass a FILE * as parameter. This is the stream to use instead of stderr -internally when reporting errors. +Pass a FILE * as parameter. Tell libcurl to use this stream instead of stderr +when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data. .IP CURLOPT_FAILONERROR A non-zero parameter tells the library to fail silently if the HTTP code returned is equal to or larger than 300. The default action would be to return @@ -200,8 +203,8 @@ proxy's port number may optionally be specified with the separate option \fBNOTE:\fP when you tell the library to use a HTTP proxy, libcurl will transparently convert operations to HTTP even if you specify a FTP URL etc. This may have an impact on what other features of the library you can -use, such as CURLOPT_QUOTE and similar FTP specifics that don't work unless -you tunnel through the HTTP proxy. Such tunneling is activated with +use, such as \fICURLOPT_QUOTE\fP and similar FTP specifics that don't work +unless you tunnel through the HTTP proxy. Such tunneling is activated with \fICURLOPT_HTTPPROXYTUNNEL\fP. \fBNOTE2:\fP libcurl respects the environment variables \fBhttp_proxy\fP, @@ -211,8 +214,8 @@ Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. .IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for -this are CURLPROXY_HTTP and CURLPROXY_SOCKS5, with the HTTP one being -default. (Added in 7.10) +this are \fICURLPROXY_HTTP\fP and \fICURLPROXY_SOCKS5\fP, with the HTTP one +being default. (Added in 7.10) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations through a given HTTP proxy. Note that there is a big difference between using @@ -273,22 +276,18 @@ set (as the standard Unix ftp client does). It should only be readable by user. .IP CURLOPT_USERPWD Pass a char * as parameter, which should be [user name]:[password] to use for -the connection. If both the colon and password is left out, you will be -prompted for it while using a colon with no password will make libcurl use an -empty password. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own -prompt function. +the connection. Use \fICURLOPT_HTTPAUTH\fP to decide authentication method. -When using HTTP and CURLOPT_FOLLOWLOCATION, libcurl might perform several +When using HTTP and \fCURLOPT_FOLLOWLOCATION\fP, libcurl might perform several requests to possibly different hosts. libcurl will only send this user and password information to hosts using the initial host name (unless -CURLOPT_UNRESTRICTED_AUTH is set), so if libcurl follows locations to other -hosts it will not send the user and password to those. This is enforced to -prevent accidental information leakage. +\fICURLOPT_UNRESTRICTED_AUTH\fP is set), so if libcurl follows locations to +other hosts it will not send the user and password to those. This is enforced +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. If the password is left out, you will be -prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own -prompt function. +the connection to the HTTP proxy. Use \fICURLOPT_PROXYAUTH\fP to decide +authentication method. .IP CURLOPT_HTTPAUTH Pass a long as parameter, which is set to a bitmask, to tell libcurl what authentication method(s) you want it to use. The available bits are listed @@ -308,15 +307,20 @@ HTTP Digest authentication. Digest authentication is defined in RFC2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. .IP CURLAUTH_GSSNEGOTIATE -HTTP GSS-Negotiate authentication. The GSS-Negotiate method was designed by -Microsoft and is used in their web aplications. It is primarily meant as a -support for Kerberos5 authentication but may be also used along with another -authentication methods. For more information see IETF draft -draft-brezak-spnego-http-04.txt. +HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain +"Negotiate") method was designed by Microsoft and is used in their web +aplications. It is primarily meant as a support for Kerberos5 authentication +but may be also used along with another authentication methods. For more +information see IETF draft draft-brezak-spnego-http-04.txt. + +\fBNOTE\fP that you need to build libcurl with a suitable GSS-API library for +this to work. .IP CURLAUTH_NTLM HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest to prevent the password from being evesdropped. + +\fBNOTE\fP that you need to build libcurl with a SSL support for this to work. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automaticly select the one it finds most @@ -369,14 +373,13 @@ redirections have been followed, the next redirect will cause an error \fICURLOPT_FOLLOWLOCATION\fP is used at the same time. .IP CURLOPT_PUT A non-zero parameter tells the library to use HTTP PUT to transfer data. The -data should be set with CURLOPT_READDATA and CURLOPT_INFILESIZE. +data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP. .IP CURLOPT_POST A non-zero parameter tells the library to do a regular HTTP post. This is a normal application/x-www-form-urlencoded kind, which is the most commonly used -one by HTML forms. See the CURLOPT_POSTFIELDS option for how to specify the -data to post and CURLOPT_POSTFIELDSIZE in how to set the data size. Starting -with libcurl 7.8, this option is obsolete. Using the CURLOPT_POSTFIELDS option -will imply this option. +one by HTML forms. See the \fICURLOPT_POSTFIELDS\fP option for how to specify +the data to post and \fICURLOPT_POSTFIELDSIZE\fP in how to set the data +size. Using the \fICURLOPT_POSTFIELDS\fP option implies this option. .IP CURLOPT_POSTFIELDS Pass a char * as parameter, which should be the full data to post in a HTTP post operation. You need to make sure that the data is formatted the way you @@ -385,8 +388,8 @@ you. Most web servers will assume this data to be url-encoded. Take note. This POST is a normal application/x-www-form-urlencoded kind (and libcurl will set that Content-Type by default when this option is used), which is the most -commonly used one by HTML forms. See also the CURLOPT_POST. Using -CURLOPT_POSTFIELDS implies CURLOPT_POST. +commonly used one by HTML forms. See also the \fICURLOPT_POST\fP. Using +\fICURLOPT_POSTFIELDS\fP implies \fICURLOPT_POST\fP. \fBNote:\fP to make multipart/formdata posts (aka rfc1867-posts), check out the \fICURLOPT_HTTPPOST\fP option. @@ -433,7 +436,7 @@ and cannot be replaced using this option. Only the lines following the request-line are headers. \fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options -CURLOPT_COOKIE, CURLOPT_USERAGENT and CURLOPT_REFERER. +\fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP. .IP CURLOPT_HTTP200ALIASES Pass a pointer to a linked list of aliases to be treated as valid HTTP 200 responses. Some servers respond with a custom header response line. For @@ -478,20 +481,19 @@ instead have the cookies written to stdout. Using this option also enables cookies for this session, so if you for example follow a location it will make matching cookies get sent accordingly. -.IP NOTE -If the cookie jar file can't be created or written to (when the +\fBNOTE:\fP If the cookie jar file can't be created or written to (when the curl_easy_cleanup() is called), libcurl will not and cannot report an error -for this. Using CURLOPT_VERBOSE or CURLOPT_DEBUGFUNCTION will get a warning to -display, but that is the only visible feedback you get about this possibly -lethal situation. +for this. Using \fICURLOPT_VERBOSE\fP or \fICURLOPT_DEBUGFUNCTION\fP will get +a warning to display, but that is the only visible feedback you get about this +possibly lethal situation. .IP CURLOPT_TIMECONDITION -Pass a long as parameter. This defines how the CURLOPT_TIMEVALUE time value is -treated. You can set this parameter to TIMECOND_IFMODSINCE or -TIMECOND_IFUNMODSINCE. This is a HTTP-only feature. (TBD) +Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time +value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP +or \fICURL_TIMECOND_IFUNMODSINCE\fP. This is a HTTP-only feature. .IP CURLOPT_TIMEVALUE 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 -CURLOPT_TIMECONDITION. +\fICURLOPT_TIMECONDITION\fP. .IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. Only really usable if POST, PUT or a custom request have been used @@ -554,9 +556,9 @@ overwrite it. This is only useful when uploading to a ftp site. .IP CURLOPT_FTP_USE_EPRT Pass a long. If the value is non-zero, it tells curl to use the EPRT (and LPRT) command when doing active FTP downloads (which is enabled by -CURLOPT_FTPPORT). Using EPRT means that it will first attempt to use EPRT and -then LPRT before using PORT, but if you pass FALSE (zero) to this option, it -will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5) +\fICURLOPT_FTPPORT\fP). Using EPRT means that it will first attempt to use +EPRT and then LPRT before using PORT, but if you pass FALSE (zero) to this +option, it will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5) .IP CURLOPT_FTP_USE_EPSV Pass a long. If the value is non-zero, it tells curl to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV @@ -569,11 +571,11 @@ directory. (Added in 7.10.7) .IP CURLOPT_FTP_RESPONSE_TIMEOUT Pass a long. Causes curl to set a timeout period (in seconds) on the amount of time that the server is allowed to take in order to generate a response -message for a command before the session is considered hung. Note that while -curl is waiting for a response, this value overrides CURLOPT_TIMEOUT. It is -recommended that if used in conjunction with CURLOPT_TIMEOUT, you set -CURLOPT_FTP_RESPONSE_TIMEOUT to a value smaller than CURLOPT_TIMEOUT. -(Added in 7.10.8) +message for a command before the session is considered hung. Note that while +curl is waiting for a response, this value overrides \fICURLOPT_TIMEOUT\fP. It +is recommended that if used in conjunction with \fICURLOPT_TIMEOUT\fP, you set +\fICURLOPT_FTP_RESPONSE_TIMEOUT\fP to a value smaller than +\fICURLOPT_TIMEOUT\fP. (Added in 7.10.8) .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A non-zero parameter tells the library to use ASCII mode for ftp transfers, @@ -623,7 +625,8 @@ When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The -CURLOPT_READDATA and CURLOPT_INFILESIZE are also interesting for uploads. +\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP are also interesting for +uploads. .IP CURLOPT_MAXFILESIZE Pass a long as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, @@ -641,15 +644,15 @@ aborting perfectly normal operations. This option will cause curl to use the SIGALRM to enable time-outing system calls. \fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as -it uses signals unless CURLOPT_NOSIGNAL (see above) is set. +it uses signals unless \fICURLOPT_NOSIGNAL\fP (see above) is set. .IP CURLOPT_LOW_SPEED_LIMIT Pass a long as parameter. It contains the transfer speed in bytes per second -that the transfer should be below during CURLOPT_LOW_SPEED_TIME seconds for -the library to consider it too slow and abort. +that the transfer should be below during \fICURLOPT_LOW_SPEED_TIME\fP seconds +for the library to consider it too slow and abort. .IP CURLOPT_LOW_SPEED_TIME Pass a long as parameter. It contains the time in seconds that the transfer -should be below the CURLOPT_LOW_SPEED_LIMIT for the library to consider it too -slow and abort. +should be below the \fICURLOPT_LOW_SPEED_LIMIT\fP for the library to consider +it too slow and abort. .IP CURLOPT_MAXCONNECTS 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 @@ -697,7 +700,7 @@ connection timeout (it will then only timeout on the system's internal timeouts). See also the \fICURLOPT_TIMEOUT\fP option. \fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as -it uses signals unless CURLOPT_NOSIGNAL (see above) is set. +it uses signals unless \fICURLOPT_NOSIGNAL\fP (see above) is set. .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be @@ -709,9 +712,9 @@ the format of your certificate. Supported formats are "PEM" and "DER". (Added in 7.9.3) .IP CURLOPT_SSLCERTPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as -the password required to use the CURLOPT_SSLCERT certificate. If the password -is not supplied, you will be prompted for it. \fICURLOPT_PASSWDFUNCTION\fP can -be used to set your own prompt function. +the password required to use the \fICURLOPT_SSLCERT\fP certificate. If the +password is not supplied, you will be prompted for it. +\fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. \fBNOTE:\fPThis option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and only cept for backward compatibility. You never needed a pass phrase to load @@ -751,23 +754,23 @@ Pass a long as parameter. Set what version of SSL to attempt to use, 2 or servers make this difficult why you at times may have to use this option. .IP CURLOPT_SSL_VERIFYPEER Pass a long that is set to a zero value to stop curl from verifying the peer's -certificate (7.10 starting setting this option to TRUE by default). Alternate -certificates to verify against can be specified with the CURLOPT_CAINFO option -or a certificate directory can be specified with the CURLOPT_CAPATH option -(Added in 7.9.8). As of 7.10, curl installs a default bundle. -CURLOPT_SSL_VERIFYHOST may also need to be set to 1 or 0 if -CURLOPT_SSL_VERIFYPEER is disabled (it defaults to 2). +certificate (7.10 starting setting this option to non-zero by default). +Alternate certificates to verify against can be specified with the +\fICURLOPT_CAINFO\fP option or a certificate directory can be specified with +the \fICURLOPT_CAPATH\fP option. As of 7.10, curl installs a default bundle. +\fICURLOPT_SSL_VERIFYHOST\fP may also need to be set to 1 or 0 if +\fICURLOPT_SSL_VERIFYPEER\fP is disabled (it defaults to 2). .IP CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This only makes sense when used in -combination with the CURLOPT_SSL_VERIFYPEER option. +combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. .IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate directory must be prepared using the openssl c_rehash utility. This only makes sense when used -in combination with the CURLOPT_SSL_VERIFYPEER option. The CAPATH function -apparently does not work in Windows due to some limitation in openssl. (Added -in 7.9.8) +in combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. The +\fICURLOPT_CAPATH\fP function apparently does not work in Windows due to some +limitation in openssl. (Added in 7.9.8) .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, -- cgit v1.2.1 From 3dd40cca9a71061fc39f17ca46685e49929d4232 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 7 Nov 2003 13:26:45 +0000 Subject: Removed references to the no-longer existing PASSWDFUNCTION. That option existed in 7.10.7 and earlier, but has since been cut out. --- docs/libcurl/curl_easy_setopt.3 | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4ce0b841a..ab104cda3 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -712,13 +712,11 @@ the format of your certificate. Supported formats are "PEM" and "DER". (Added in 7.9.3) .IP CURLOPT_SSLCERTPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as -the password required to use the \fICURLOPT_SSLCERT\fP certificate. If the -password is not supplied, you will be prompted for it. -\fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +the password required to use the \fICURLOPT_SSLCERT\fP certificate. -\fBNOTE:\fPThis option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and only -cept for backward compatibility. You never needed a pass phrase to load -a certificate but you need one to load your private key. +This option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and should only be used +for backward compatibility. You never needed a pass phrase to load a +certificate but you need one to load your private key. .IP CURLOPT_SSLKEY Pass a pointer to a zero terminated string as parameter. The string should be the file name of your private key. The default format is "PEM" and can be @@ -732,9 +730,7 @@ engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to the engine. You have to set the crypto engine with \fICURLOPT_SSL_ENGINE\fP. .IP CURLOPT_SSLKEYPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as -the password required to use the \fICURLOPT_SSLKEY\fP private key. If the -password is not supplied, you will be prompted for -it. \fICURLOPT_PASSWDFUNCTION\fP can be used to set your own prompt function. +the password required to use the \fICURLOPT_SSLKEY\fP private key. .IP CURLOPT_SSL_ENGINE Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private -- cgit v1.2.1 From ad77f760cf8223548cd214b361591dfde5443dea Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 11 Nov 2003 14:30:43 +0000 Subject: Added CURLOPT_NETRC_FILE. --- docs/libcurl/curl_easy_setopt.3 | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ab104cda3..9096fdf30 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "7 Nov 2003" "libcurl 7.10.8" "libcurl Manual" +.TH curl_easy_setopt 3 "11 Nov 2003" "libcurl 7.10.9" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -274,6 +274,11 @@ Only machine name, user name and password are taken into account \fBNote:\fP libcurl does not verify that the file has the correct properties set (as the standard Unix ftp client does). It should only be readable by user. +.IP CURLOPT_NETRC_FILE +Pass a char * as parameter, pointing to a zero terminated string containing +the full path name to the file you want libcurl to use as .netrc file. If this +option is omitted, and CURLOPT_NETRC is set, libcurl will attempt to find the +a .netrc file in the current user's home directory. .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. -- cgit v1.2.1 From e42f806b3f5053a2a1e593e01c838c1dbfefcc5a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 12 Nov 2003 14:34:17 +0000 Subject: mention it was added in 7.10.9 --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9096fdf30..a06f259d0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -278,7 +278,7 @@ user. Pass a char * as parameter, pointing to a zero terminated string containing the full path name to the file you want libcurl to use as .netrc file. If this option is omitted, and CURLOPT_NETRC is set, libcurl will attempt to find the -a .netrc file in the current user's home directory. +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. -- cgit v1.2.1 From ea53aed841461a5a6f1cb7bfb39fa79d6873e6f8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 4 Dec 2003 12:56:05 +0000 Subject: cut out the wrong version blurb --- docs/libcurl/libcurl-errors.3 | 3 --- 1 file changed, 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 4a737dbe3..3e4b90a23 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -14,9 +14,6 @@ what, using \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. -This man page is meant to describe libcurl 7.9.6 and later. Earlier versions -might have had quirks not mentioned here. - CURLcode is one of the following: .RS 0 .IP "CURLE_OK (0)" -- cgit v1.2.1 From bff59dac12a9678b2474282b529ef7134dd115e7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 4 Dec 2003 13:01:30 +0000 Subject: minor edit of the PRIVATE option --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a06f259d0..157b3b62d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -803,8 +803,9 @@ support only works for FTP. .SH OTHER OPTIONS .IP CURLOPT_PRIVATE Pass a char * as parameter, pointing to data that should be associated with -the curl handle. The pointer can be subsequently retrieved using the -CURLINFO_PRIVATE options to curl_easy_getinfo. (Added in 7.10.3) +this curl handle. The pointer can subsequently be retrieved using +\fIcurl_easy_getinfo\fP with the CURLINFO_PRIVATE option. libcurl itself does +nothing with this data. (Added in 7.10.3) .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP -- cgit v1.2.1 From 90e9c64f72f2bbe7bf0f74338bf8be1a97119b8e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Dec 2003 07:16:20 +0000 Subject: Eric S. Raymond's fix of the NAME section --- docs/libcurl/libcurl-errors.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 3e4b90a23..eae506558 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -4,7 +4,7 @@ .\" .TH libcurl-errors 3 "18 Oct 2003" "libcurl 7.10.8" "libcurl errors" .SH NAME -error codes in libcurl +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. -- cgit v1.2.1 From 58cf10825153cc549ee0c28a48578e8133df1509 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 18 Dec 2003 13:33:14 +0000 Subject: =?UTF-8?q?Andr=E9s=20Garc=EDa's=20update?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/libcurl/curl_easy_getinfo.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 59d06e1da..f0642b86a 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -100,6 +100,13 @@ protocol used doesn't support this. (Added in 7.9.4) Pass a pointer to a 'char *' to receive the pointer to the private data associated with the curl handle (set with the CURLOPT_PRIVATE option to curl_easy_setopt). (Added in 7.10.3) +.IP CURLINFO_HTTPAUTH_AVAIL +Pass a pointer to a long to receive a bitmask indicating the authentication +method(s) available. The meaning of the bits is explained in the +CURLOPT_HTTPAUTH option for curl_easy_setopt. (Added in 7.10.8) +.IP CURLINFO_PROXYAUTH_AVAIL +Pass a pointer to a long to receive a bitmask indicating the authentication +method(s) available for your proxy athentication. (Added in 7.10.8) .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. -- cgit v1.2.1 From 61685fee7e8c6b4446eeb569d2099b8a34b5abe5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 22 Dec 2003 10:53:55 +0000 Subject: =?UTF-8?q?Andr=E9s=20Garc=EDa=20added=20CURLOPT=5FIPRESOLVE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/libcurl/curl_easy_setopt.3 | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 157b3b62d..a718608e1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_setopt 3 "11 Nov 2003" "libcurl 7.10.9" "libcurl Manual" +.TH curl_easy_setopt 3 "22 Dec 2003" "libcurl 7.11.0" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -706,6 +706,18 @@ timeouts). See also the \fICURLOPT_TIMEOUT\fP option. \fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as it uses signals unless \fICURLOPT_NOSIGNAL\fP (see above) is set. +.IP CURLOPT_IPRESOLVE +Allows an application to select what kind of IP addresses to use when +resolving host names. This is only interesting when using host names that +resolve addresses using more than one version of IP. The allowed values are: +.RS +.IP CURL_IPRESOLVE_WHATEVER +Default, resolves addresses to all IP versions that your system allows. +.IP CURL_IPRESOLVE_V4 +Resolve to ipv4 addresses. +.IP CURL_IPRESOLVE_V6 +Resolve to ipv6 addresses. +.RE .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be -- cgit v1.2.1 From 411d0cb71512b3434b4f46e5540f756bba6eb69a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Jan 2004 14:46:56 +0000 Subject: minor format flaw --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a718608e1..f477398a8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -283,9 +283,9 @@ a .netrc file in the current user's home directory. (Added in 7.10.9) Pass a char * as parameter, which should be [user name]:[password] to use for the connection. Use \fICURLOPT_HTTPAUTH\fP to decide authentication method. -When using HTTP and \fCURLOPT_FOLLOWLOCATION\fP, libcurl might perform several -requests to possibly different hosts. libcurl will only send this user and -password information to hosts using the initial host name (unless +When using HTTP and \fICURLOPT_FOLLOWLOCATION\fP, libcurl might perform +several requests to possibly different hosts. libcurl will only send this user +and password information to hosts using the initial host name (unless \fICURLOPT_UNRESTRICTED_AUTH\fP is set), so if libcurl follows locations to other hosts it will not send the user and password to those. This is enforced to prevent accidental information leakage. -- cgit v1.2.1 From 41c6f68d949bf6021fbf4d3488bbf38efa898816 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Jan 2004 14:56:46 +0000 Subject: minor wording change --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f477398a8..ac3408471 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -322,10 +322,11 @@ information see IETF draft draft-brezak-spnego-http-04.txt. this to work. .IP CURLAUTH_NTLM HTTP NTLM authentication. A proprietary protocol invented and used by -Microsoft. It uses a challenge-response and hash concept similar to Digest to +Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being evesdropped. -\fBNOTE\fP that you need to build libcurl with a SSL support for this to work. +\fBNOTE\fP that you need to build libcurl with SSL support for this option to +work. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automaticly select the one it finds most -- cgit v1.2.1 From b60e0fa97ed7ddc66d0ad6d00dfd78319bb6ad36 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Jan 2004 22:29:29 +0000 Subject: David J Meyer's large file support. --- docs/libcurl/curl_easy_setopt.3 | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ac3408471..be50940db 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -602,6 +602,9 @@ techniques). .IP CURLOPT_RESUME_FROM Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. +.IP CURLOPT_RESUME_FROM_LARGE +Pass an off_t as parameter. It contains the offset in number of bytes that you +want the transfer to start from. .IP CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST @@ -628,16 +631,29 @@ output. This is only relevant for protocols that have separate header and body parts. On HTTP(S) servers, this will make libcurl do a HEAD request. .IP CURLOPT_INFILESIZE When uploading a file to a remote site, this option should be used to tell -libcurl what the expected size of the infile is. +libcurl what the expected size of the infile is. This value should be passed +as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. +.IP CURLOPT_INFILESIZE_LARGE +When uploading a file to a remote site, this option should be used to tell +libcurl what the expected size of the infile is. This value should be passed +as an off_t. .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The -\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP are also interesting for -uploads. +\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE_LARGE\fP are also interesting +for uploads. .IP CURLOPT_MAXFILESIZE Pass a long as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. +NOTE: The file size is not always known prior to download, and for such files +this option has no effect even if the file transfer ends up being larger than +this given limit. This concerns both FTP and HTTP transfers. +.IP CURLOPT_MAXFILESIZE_LARGE +Pass an off_t as parameter. This allows you to specify the maximum size (in +bytes) of a file to download. If the file requested is larger than this value, +the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. + NOTE: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers. -- cgit v1.2.1 From feeef39ebf2049c585e5637688c98c83d24f3b5a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 7 Jan 2004 07:20:08 +0000 Subject: mention that the _LARGE options are added in 7.11.0, added a header to the file with the standard curl blurb --- docs/libcurl/curl_easy_setopt.3 | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index be50940db..bb2d7eb2f 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1,7 +1,27 @@ -.\" nroff -man [file] -.\" $Id$ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2004, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "22 Dec 2003" "libcurl 7.11.0" "libcurl Manual" +.TH curl_easy_setopt 3 "7 Jan 2004" "libcurl 7.11.0" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -604,7 +624,7 @@ Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. .IP CURLOPT_RESUME_FROM_LARGE Pass an off_t as parameter. It contains the offset in number of bytes that you -want the transfer to start from. +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 user instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST @@ -636,7 +656,7 @@ as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. .IP CURLOPT_INFILESIZE_LARGE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed -as an off_t. +as an off_t. (Added in 7.11.0) .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE_LARGE\fP are also interesting @@ -653,6 +673,7 @@ this given limit. This concerns both FTP and HTTP transfers. Pass an off_t as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. +(Added in 7.11.0) NOTE: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than -- cgit v1.2.1 From 84990cb176e30cd56e7264900e51b040f7fbd49f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 15 Jan 2004 10:38:08 +0000 Subject: Peter Sylvester's CURLOPT_SSL_CTX_FUNCTION docs I reworded some of the intial paragraphs to avoid 'NOTE2' --- docs/libcurl/curl_easy_setopt.3 | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index bb2d7eb2f..2842ebfc5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "7 Jan 2004" "libcurl 7.11.0" "libcurl Manual" +.TH curl_easy_setopt 3 "15 Jan 2004" "libcurl 7.11.0" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -38,18 +38,17 @@ carefully as bad input values may cause libcurl to behave badly! You can only set one option in each function call. A typical application uses many curl_easy_setopt() calls in the setup phase. +Options set with this function call are valid for all forthcoming transfers +performed using this \fIhandle\fP. The options are not in any way reset +between transfers, so if you want subsequent transfers with different options, +you must change them between the transfers. + \fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be copied by the library. Instead you should keep them available until libcurl no longer needs them. Failing to do so will cause very odd behavior or even crashes. libcurl will need them until you call curl_easy_cleanup() or you set the same option again to use a different pointer. -\fBNOTE2:\fP options set with this function call are valid for the forthcoming -data transfers that are performed when you invoke \fIcurl_easy_perform\fP. -The options are not in any way reset between transfers, so if you want -subsequent transfers with different options, you must change them between the -transfers. - The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. .SH BEHAVIOR OPTIONS @@ -186,6 +185,28 @@ The data is protocol data sent to the peer. Pass a pointer to whatever you want passed in to your \fICURLOPT_DEBUGFUNCTION\fP in the last void * argument. This pointer is not used by libcurl, it is only passed to the callback. +.IP CURLOPT_SSL_CTX_FUNCTION +Function pointer that should match the following prototype: \fBCURLcode +sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called +by libcurl just before the initialization of an SSL connection after having +processed all other SSL related options to give a last chance to an +application to modify the behaviour of openssl's ssl initilaization. The +\fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If +an error is returned no attempt to establish a connection is made and the +perform operation will return the error code from this callback function. Set +the \fIparm\fP argument with the \fICURLOPT_SSL_CTX_DATA\fP option. This +option was introduced in 7.11.0. + +\fBNOTE:\fP 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 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 +and trust file settings. +.IP CURLOPT_SSL_CTX_DATA +Data pointer to pass to the ssl context callback set by the option +\fICURLOPT_SSL_CTX_FUNCTION\fP, this is the pointer you'll get as third +parameter, otherwise \fBNULL\fP. (Added in 7.11.0) .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error -- cgit v1.2.1 From d204c62c39bb7b19ba7c1c8891519024bfe55e28 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 21 Jan 2004 07:46:17 +0000 Subject: clarified where VERBOSE output goes --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2842ebfc5..ae1cc23ca 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "15 Jan 2004" "libcurl 7.11.0" "libcurl Manual" +.TH curl_easy_setopt 3 "21 Jan 2004" "libcurl 7.11.0" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -55,7 +55,8 @@ The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or .IP CURLOPT_VERBOSE Set the parameter to non-zero to get the library to display a lot of verbose information about its operations. Very useful for libcurl and/or protocol -debugging and understanding. +debugging and understanding. The verbose information will be sent to stderr, +or the stream set with CURLOPT_STDERR. You hardly ever want this set in production use, you will almost always want this when you debug/report problems. Another neat option for debugging is the -- cgit v1.2.1 From 863c7c72820d4533fb0cc49148bdc8f73ea1fab5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Jan 2004 09:15:37 +0000 Subject: no large files on windows just yet --- docs/libcurl/curl_easy_setopt.3 | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ae1cc23ca..89a13d178 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "21 Jan 2004" "libcurl 7.11.0" "libcurl Manual" +.TH curl_easy_setopt 3 "22 Jan 2004" "libcurl 7.11.0" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -646,7 +646,8 @@ Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. .IP CURLOPT_RESUME_FROM_LARGE Pass an off_t as parameter. It contains the offset in number of bytes that you -want the transfer to start from. (Added in 7.11.0) +want the transfer to start from. This does not yet support large files on +Windows. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST @@ -678,7 +679,8 @@ as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. .IP CURLOPT_INFILESIZE_LARGE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed -as an off_t. (Added in 7.11.0) +as an off_t. This does not yet support large files on Windows. (Added in +7.11.0) .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE_LARGE\fP are also interesting @@ -695,7 +697,7 @@ this given limit. This concerns both FTP and HTTP transfers. Pass an off_t as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. -(Added in 7.11.0) +This does not yet support large files on Windows. (Added in 7.11.0) NOTE: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than -- cgit v1.2.1 From eaddf3d198d3b891f988b03dc16753da87099804 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Jan 2004 10:17:09 +0000 Subject: mark the option better --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 89a13d178..32bac6f97 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -56,7 +56,7 @@ The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or Set the parameter to non-zero to get the library to display a lot of verbose information about its operations. Very useful for libcurl and/or protocol debugging and understanding. The verbose information will be sent to stderr, -or the stream set with CURLOPT_STDERR. +or the stream set with \fICURLOPT_STDERR\fP. You hardly ever want this set in production use, you will almost always want this when you debug/report problems. Another neat option for debugging is the -- cgit v1.2.1 From 5a58d51993f1ddf2ec6d881546cdf0c9096c0472 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 23 Jan 2004 12:52:04 +0000 Subject: the *_LARGE options work fine on windows in 7.11.1 --- docs/libcurl/curl_easy_setopt.3 | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 32bac6f97..becb78d49 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "22 Jan 2004" "libcurl 7.11.0" "libcurl Manual" +.TH curl_easy_setopt 3 "22 Jan 2004" "libcurl 7.11.1" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -645,9 +645,8 @@ techniques). Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. .IP CURLOPT_RESUME_FROM_LARGE -Pass an off_t as parameter. It contains the offset in number of bytes that you -want the transfer to start from. This does not yet support large files on -Windows. (Added in 7.11.0) +Pass an curl_off_t as parameter. It contains the offset in number of bytes +that you want the transfer to start from. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST @@ -679,8 +678,7 @@ as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. .IP CURLOPT_INFILESIZE_LARGE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed -as an off_t. This does not yet support large files on Windows. (Added in -7.11.0) +as a curl_off_t. (Added in 7.11.0) .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE_LARGE\fP are also interesting @@ -694,10 +692,10 @@ NOTE: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers. .IP CURLOPT_MAXFILESIZE_LARGE -Pass an off_t as parameter. This allows you to specify the maximum size (in -bytes) of a file to download. If the file requested is larger than this value, -the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. -This does not yet support large files on Windows. (Added in 7.11.0) +Pass a curl_off_t as parameter. This allows you to specify the maximum size +(in bytes) of a file to download. If the file requested is larger than this +value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will be +returned. (Added in 7.11.0) NOTE: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than -- cgit v1.2.1 From 220caed248ec990c137a9f197710eddad4a608eb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 9 Feb 2004 09:07:26 +0000 Subject: Dominick Meglio's added share interface documentation --- docs/libcurl/curl_share_cleanup.3 | 6 +++-- docs/libcurl/curl_share_init.3 | 4 ++-- docs/libcurl/curl_share_setopt.3 | 47 ++++++++++++++++++++++++--------------- docs/libcurl/libcurl-errors.3 | 19 +++++++++++++--- 4 files changed, 51 insertions(+), 25 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 index 2510213eb..b668d072f 100644 --- a/docs/libcurl/curl_share_cleanup.3 +++ b/docs/libcurl/curl_share_cleanup.3 @@ -13,7 +13,9 @@ This function deletes a shared object. The share handle cannot be used anymore when this function has been called. .SH RETURN VALUE -If this function returns non-zero, the object was not properly deleted and it -still remains! +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP +man page for the full list with descriptions. If an error occurs, then the +share object will not be deleted. .SH "SEE ALSO" .BR curl_share_init "(3), " curl_share_setopt "(3)" diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index 2f6581363..35fd5a1c9 100644 --- a/docs/libcurl/curl_share_init.3 +++ b/docs/libcurl/curl_share_init.3 @@ -14,8 +14,8 @@ share-functions, sometimes refered to as a share handle on 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. .SH RETURN VALUE -If this function returns NULL, something went wrong and you got no share -object to use. +If this function returns NULL, something went wrong (out of memory, etc.) +and therefore the share object was not created. .SH "SEE ALSO" .BR curl_share_cleanup "(3), " curl_share_setopt "(3)" diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index 583c14645..858b41cc9 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -11,8 +11,7 @@ CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter); .SH DESCRIPTION Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP. .SH OPTIONS -.TP 0.4i -.B CURLSHOPT_LOCKFUNC +.IP CURLSHOPT_LOCKFUNC The \fIparameter\fP must be a pointer to a function matching the following prototype: @@ -24,23 +23,35 @@ only one lock is given at any time for each kind of data. \fIaccess\fP defines what access type libcurl wants, shared or single. -\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDAT\fP. +\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP. +.IP CURLSHOPT_UNLOCKFUNC +The \fIparameter\fP must be a pointer to a function matching the following +prototype: -.TP -.B CURLSHOPT_UNLOCKFUNC -hej -.TP -.B CURLSHOPT_SHARE -hej -.TP -.B CURLSHOPT_UNSHARE -hej -.TP -.B CURLSHOPT_USERDATA -hej -.PP -.SH RETURN VALUE -If this function returns non-zero, something was wrong! +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. + +\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP. +.IP CURLSHOPT_SHARE +The \fIparameter\fP specifies a type of data that should be shared. This may +be set to one of the values described below. +.IP CURL_LOCK_DATA_COOKIE +COOKIE data will be shared across the easy handles using this shared object. +.IP CURL_LOCK_DATA_DNS +Cached DNS hosts will be shared across the easy handles using this shared +object. +.IP CURLSHOPT_UNSHARE +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 +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 +error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP +man page for the full list with descriptions. .SH "SEE ALSO" .BR curl_share_cleanup "(3), " curl_share_init "(3)" diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index eae506558..9ca61752f 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -15,7 +15,6 @@ human readable error string that may offer more details about the error cause than just the error code does. CURLcode is one of the following: -.RS 0 .IP "CURLE_OK (0)" All fine. Proceed as usual. .IP "CURLE_UNSUPPORTED_PROTOCOL (1)" @@ -183,8 +182,22 @@ Unrecognized transfer encoding Invalid LDAP URL .IP "CURLE_FILESIZE_EXCEEDED (63)" Maximum file size exceeded -.RE - .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. + +This is left to be documented. +.SH "CURLSHcode" +The "share" interface will return a CURLSHcode to indicate when an +error has occurred. + +CURLSHcode is one of the following: +.IP "CURLSHE_OK (0)" +All fine. Proceed as usual. +.IP "CURLSHE_BAD_OPTION (1)" +An invalid option was passed to the function. +.IP "CURLSHE_IN_USE (2)" +The share object is currently in use. +.IP "CURLSHE_INVALID (3)" +An invalid share object was passed to the function. + -- cgit v1.2.1 From 283f68f660d989371c7eb8a527b93aab7584a071 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 9 Feb 2004 13:51:52 +0000 Subject: Dominick Meglio's update --- docs/libcurl/curl_easy_setopt.3 | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index becb78d49..d1de20316 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -534,14 +534,6 @@ curl_easy_cleanup() is called), libcurl will not and cannot report an error for this. Using \fICURLOPT_VERBOSE\fP or \fICURLOPT_DEBUGFUNCTION\fP will get a warning to display, but that is the only visible feedback you get about this possibly lethal situation. -.IP CURLOPT_TIMECONDITION -Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time -value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP -or \fICURL_TIMECOND_IFUNMODSINCE\fP. This is a HTTP-only feature. -.IP CURLOPT_TIMEVALUE -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. .IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. Only really usable if POST, PUT or a custom request have been used @@ -700,6 +692,18 @@ returned. (Added in 7.11.0) NOTE: The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this given limit. This concerns both FTP and HTTP transfers. +.IP CURLOPT_TIMECONDITION +Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time +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. + +NOTE: 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. +.IP CURLOPT_TIMEVALUE +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 .IP CURLOPT_TIMEOUT Pass a long as parameter containing the maximum time in seconds that you allow -- cgit v1.2.1 From afa592448775c9f7d20934137b9a840d33b5e934 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 19 Feb 2004 10:21:54 +0000 Subject: very minor phrase edit --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d1de20316..7ecfac1d7 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -271,7 +271,7 @@ name. Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero (0) to completely disable caching, or set to -1 to make the cached entries remain forever. By default, -libcurl caches info for 60 seconds. +libcurl caches this info for 60 seconds. .IP CURLOPT_DNS_USE_GLOBAL_CACHE Pass a long. If the value is non-zero, it tells curl to use a global DNS cache that will survive between easy handle creations and deletions. This is not -- cgit v1.2.1 From 0b1f7995c5296f53b577bbc73a55cb9acd85d33e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Feb 2004 09:01:08 +0000 Subject: correct the input data structs --- docs/libcurl/curl_formadd.3 | 4 ++-- docs/libcurl/curl_formfree.3 | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 8ede2bbb2..9802351d1 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -8,8 +8,8 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS .B #include .sp -.BI "CURLFORMcode curl_formadd(struct HttpPost ** " firstitem, -.BI "struct HttpPost ** " lastitem, " ...);" +.BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem, +.BI "struct curl_httppost ** " lastitem, " ...);" .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 3bf3f999b..263d9aa37 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -8,7 +8,7 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain .SH SYNOPSIS .B #include .sp -.BI "void curl_formfree(struct HttpPost *" form); +.BI "void curl_formfree(struct curl_httppost *" form); .ad .SH DESCRIPTION curl_formfree() is used to clean up data previously built/appended with -- cgit v1.2.1 From 9a7e3437aef161559ccafc2fb1b845497aec44ec Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 Feb 2004 12:20:41 +0000 Subject: added CURLOPT_SHARE --- docs/libcurl/curl_easy_setopt.3 | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7ecfac1d7..b62341fe2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "22 Jan 2004" "libcurl 7.11.1" "libcurl Manual" +.TH curl_easy_setopt 3 "25 Feb 2004" "libcurl 7.11.1" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -882,6 +882,13 @@ Pass a char * as parameter, pointing to data that should be associated with this curl handle. The pointer can subsequently be retrieved using \fIcurl_easy_getinfo\fP with the CURLINFO_PRIVATE option. libcurl itself does nothing with this data. (Added in 7.10.3) +.IP CURLOPT_SHARE +Pass a share handle as a parameter. The share handle must have been created by +a previous call to curl_share_init(). Setting this option, will make this curl +handle use the data from the shared handle instead of keeping the data to +itself. This enables several curl handles to share data. If the curl handles +are used simultaneously, you \fBMUST\fP use the locking methods in the share +handle. See \fIcurl_share_setopt(3)\fP for details. .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP -- cgit v1.2.1 From 403cbbe0c45db1ab73e7342085ebab32da7b533f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 Feb 2004 12:32:33 +0000 Subject: mark the function name --- docs/libcurl/curl_easy_setopt.3 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b62341fe2..10d4fda74 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -884,11 +884,11 @@ this curl handle. The pointer can subsequently be retrieved using nothing with this data. (Added in 7.10.3) .IP CURLOPT_SHARE Pass a share handle as a parameter. The share handle must have been created by -a previous call to curl_share_init(). Setting this option, will make this curl -handle use the data from the shared handle instead of keeping the data to -itself. This enables several curl handles to share data. If the curl handles -are used simultaneously, you \fBMUST\fP use the locking methods in the share -handle. See \fIcurl_share_setopt(3)\fP for details. +a previous call to \fIcurl_share_init(3)\fP. Setting this option, will make +this curl handle use the data from the shared handle instead of keeping the +data to itself. This enables several curl handles to share data. If the curl +handles are used simultaneously, you \fBMUST\fP use the locking methods in the +share handle. See \fIcurl_share_setopt(3)\fP for details. .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP -- cgit v1.2.1 From 82c31256e10c99d7a56591051a4acd01778b02bf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 Feb 2004 12:34:19 +0000 Subject: better formatting of the share options --- docs/libcurl/curl_share_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index 858b41cc9..e53946534 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -37,11 +37,13 @@ that only one lick is given at any time for each kind of data. .IP CURLSHOPT_SHARE The \fIparameter\fP specifies a type of data that should be shared. This may be set to one of the values described below. +.RS .IP CURL_LOCK_DATA_COOKIE -COOKIE data will be shared across the easy handles using this shared object. +Cookie data will be shared across the easy handles using this shared object. .IP CURL_LOCK_DATA_DNS Cached DNS hosts will be shared across the easy handles using this shared object. +.RE .IP CURLSHOPT_UNSHARE This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that the specified \fIparameter\fP will no longer be shared. Valid values are -- cgit v1.2.1 From d0242da3040b46417e91b1dd378769cca186c7f4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 27 Feb 2004 09:02:06 +0000 Subject: Added a few options that were still not documented. Now I believe all options mentioned in the current curl/curl.h header file (that aren't marked as obsolete) are present. --- docs/libcurl/curl_easy_setopt.3 | 41 +++++++++++++++++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 10d4fda74..d64767ee8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "25 Feb 2004" "libcurl 7.11.1" "libcurl Manual" +.TH curl_easy_setopt 3 "27 Feb 2004" "libcurl 7.11.1" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -281,6 +281,9 @@ Pass a long specifying your prefered size for the receive buffer in libcurl. The main point of this would be that the write callback gets called more often and with smaller chunks. This is just treated as a request, not an order. You cannot be guaranteed to actually get the given size. (Added in 7.10) +.IP CURLOPT_PORT +Pass a long specifying what remote port number to connect to, instead of the +one specified in the URL or the default port for the used protocol. .SH NAMES and PASSWORDS OPTIONS (Authentication) .IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and @@ -389,6 +392,10 @@ round-trip. Set the actual name and password with the together the bits listed above for the \fICURLOPT_HTTPAUTH\fP option. As of this writing, only Basic and NTLM work. (Added in 7.10.7) .SH HTTP OPTIONS +.IP CURLOPT_AUTOREFERER +Pass a non-zero parameter to enable this. When enabled, libcurl will +automaticly set the Referer: field in requests where it follows a Location: +redirect. .IP CURLOPT_ENCODING Sets the contents of the Accept-Encoding: header sent in an HTTP request, and enables decoding of a response when a Content-Encoding: @@ -534,6 +541,13 @@ curl_easy_cleanup() is called), libcurl will not and cannot report an error for this. Using \fICURLOPT_VERBOSE\fP or \fICURLOPT_DEBUGFUNCTION\fP will get a warning to display, but that is the only visible feedback you get about this possibly lethal situation. +.IP CURLOPT_COOKIESESSION +Pass a long set to non-zero 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 without expiry date and they are meant to be alive and +existing for this "session" only. .IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. Only really usable if POST, PUT or a custom request have been used @@ -616,6 +630,19 @@ curl is waiting for a response, this value overrides \fICURLOPT_TIMEOUT\fP. It is recommended that if used in conjunction with \fICURLOPT_TIMEOUT\fP, you set \fICURLOPT_FTP_RESPONSE_TIMEOUT\fP to a value smaller than \fICURLOPT_TIMEOUT\fP. (Added in 7.10.8) +.IP CURLOPT_FTP_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) +.RS +.IP CURLFTPSSL_NONE +Don't attempt to use SSL. +.IP CURLFTPSSL_TRY +Try using SSL, proceed as normal otherwise. +.IP CURLFTPSSL_CONTROL +Require SSL for the control connection or fail with \fICURLE_FTP_SSL_FAILED\fP. +.IP CURLFTPSSL_ALL +Require SSL for all communication or fail with \fICURLE_FTP_SSL_FAILED\fP. +.RE .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A non-zero parameter tells the library to use ASCII mode for ftp transfers, @@ -808,18 +835,18 @@ the format of your private key. Supported formats are "PEM", "DER" and "ENG". \fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to -the engine. You have to set the crypto engine with \fICURLOPT_SSL_ENGINE\fP. +the engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE\fP. .IP CURLOPT_SSLKEYPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as the password required to use the \fICURLOPT_SSLKEY\fP private key. -.IP CURLOPT_SSL_ENGINE +.IP CURLOPT_SSLENGINE Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private key. \fBNOTE:\fPIf the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. -.IP CURLOPT_SSL_ENGINEDEFAULT +.IP CURLOPT_SSLENGINE_DEFAULT Sets the actual crypto engine as the default for (asymetric) crypto operations. @@ -889,6 +916,12 @@ this curl handle use the data from the shared handle instead of keeping the data to itself. This enables several curl handles to share data. If the curl handles are used simultaneously, you \fBMUST\fP use the locking methods in the share handle. See \fIcurl_share_setopt(3)\fP for details. +.SH TELNET OPTIONS +.IP CURLOPT_TELNETOPTIONS +Provide a pointer to a curl_slist with variables to pass to the telnet +negotiations. The variables should be in the format . libcurl +supports the options 'TTYPE', 'XDISPLOC' and 'NEW_ENV'. See the TELNET +standard for details. .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP -- cgit v1.2.1 From f53d6e1c39471f4b793294490e80c6321b173066 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 27 Feb 2004 14:07:22 +0000 Subject: elaborate on the URL option --- docs/libcurl/curl_easy_setopt.3 | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d64767ee8..a9f2fd3c0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -232,7 +232,14 @@ The actual URL to deal with. The parameter should be a char * to a zero terminated string. The string must remain present until curl no longer needs it, as it doesn't copy the string. -\fBNOTE:\fP this option is (the only one) required to be set before +If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will +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. + +\fBNOTE:\fP \fICURLOPT_URL\fP is the only option that must be set before \fIcurl_easy_perform(3)\fP is called. .IP CURLOPT_PROXY Set HTTP proxy to use. The parameter should be a char * to a zero terminated -- cgit v1.2.1 From 25bcd45034b2289becfb34a762d5a8c0e9a0c0ef Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 27 Feb 2004 15:34:06 +0000 Subject: formatting update to produce better links with the new roffit version --- docs/libcurl/curl_easy_cleanup.3 | 4 ++-- docs/libcurl/curl_easy_duphandle.3 | 10 ++++------ docs/libcurl/curl_easy_getinfo.3 | 12 +++++------- docs/libcurl/curl_easy_init.3 | 4 ++-- docs/libcurl/curl_easy_perform.3 | 30 ++++++++++++------------------ docs/libcurl/curl_easy_setopt.3 | 22 +++++++++++----------- docs/libcurl/curl_escape.3 | 2 +- docs/libcurl/curl_formadd.3 | 13 +++++-------- docs/libcurl/curl_formfree.3 | 11 ++--------- docs/libcurl/curl_free.3 | 7 ++++--- docs/libcurl/curl_getdate.3 | 6 +++--- docs/libcurl/curl_getenv.3 | 7 ++----- docs/libcurl/curl_global_cleanup.3 | 8 ++------ docs/libcurl/curl_global_init.3 | 14 ++++++-------- docs/libcurl/curl_slist_append.3 | 6 ++---- docs/libcurl/curl_slist_free_all.3 | 2 -- docs/libcurl/curl_unescape.3 | 2 +- docs/libcurl/curl_version_info.3 | 6 +++--- 18 files changed, 67 insertions(+), 99 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index 6c76e92b5..84c0a6d1e 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -12,8 +12,8 @@ curl_easy_cleanup - End a libcurl easy session .SH DESCRIPTION This function must be the last function to call for an easy session. It is the -opposite of the \fIcurl_easy_init\fP function and must be called with the same -\fIhandle\fP as input that the curl_easy_init call returned. +opposite of the \fIcurl_easy_init(3)\fP function and must be called with the +same \fIhandle\fP as input that the curl_easy_init call returned. This will effectively close all connections this handle has used and possibly has kept open until now. Don't call this function if you intend to transfer diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 index b8463345b..4133e3289 100644 --- a/docs/libcurl/curl_easy_duphandle.3 +++ b/docs/libcurl/curl_easy_duphandle.3 @@ -14,20 +14,18 @@ curl_easy_duphandle - Clone a libcurl session handle This function will return a new curl handle, a duplicate, using all the options previously set in the input curl \fIhandle\fP. Both handles can subsequently be used independently and they must both be freed with -\fIcurl_easy_cleanup()\fP. +\fIcurl_easy_cleanup(3)\fP. All strings that the input handle has been told to point to (as opposed to -copy) with previous calls to \fIcurl_easy_setopt\fP using char * inputs, will -be pointed to by the new handle as well. You must therefore make sure to keep -the data around until both handles have been cleaned up. +copy) with previous calls to \fIcurl_easy_setopt(3)\fP using char * inputs, +will be pointed to by the new handle as well. You must therefore make sure to +keep the data around until both handles have been cleaned up. The new handle will \fBnot\fP inherit any state information, no connections, no SSL sessions and no cookies. \fBNote\fP that even in multi-threaded programs, this function must be called in a synchronous way, the input handle may not be in use when cloned. - -This function was added in libcurl 7.9. .SH RETURN VALUE If this function returns NULL, something went wrong and no valid handle was returned. diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index f0642b86a..49c7211d1 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -85,25 +85,25 @@ than one request if FOLLOWLOCATION is true. .IP CURLINFO_SSL_VERIFYRESULT Pass a pointer to a long to receive the result of the certification verification that was requested (using the CURLOPT_SSL_VERIFYPEER option to -curl_easy_setopt). (Added in 7.4.2) +\fIcurl_easy_setopt(3)\fP). .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD Pass a pointer to a double to receive the content-length of the download. This -is the value read from the Content-Length: field. (Added in 7.6.1) +is the value read from the Content-Length: field. .IP CURLINFO_CONTENT_LENGTH_UPLOAD Pass a pointer to a double to receive the specified size of the upload. .IP CURLINFO_CONTENT_TYPE Pass a pointer to a 'char *' to receive the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get NULL, it means that the server didn't send a valid Content-Type header or that the -protocol used doesn't support this. (Added in 7.9.4) +protocol used doesn't support this. .IP CURLINFO_PRIVATE Pass a pointer to a 'char *' to receive the pointer to the private data associated with the curl handle (set with the CURLOPT_PRIVATE option to -curl_easy_setopt). (Added in 7.10.3) +\fIcurl_easy_setopt(3)\fP). (Added in 7.10.3) .IP CURLINFO_HTTPAUTH_AVAIL Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available. The meaning of the bits is explained in the -CURLOPT_HTTPAUTH option for curl_easy_setopt. (Added in 7.10.8) +CURLOPT_HTTPAUTH option for \fIcurl_easy_setopt(3)\fP. (Added in 7.10.8) .IP CURLINFO_PROXYAUTH_AVAIL Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available for your proxy athentication. (Added in 7.10.8) @@ -112,5 +112,3 @@ If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. .SH "SEE ALSO" .BR curl_easy_setopt "(3)" -.SH BUGS -Surely there are some, you tell me! diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 1c2ec2be4..890a8a85a 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -13,8 +13,8 @@ curl_easy_init - Start a libcurl easy session .SH DESCRIPTION This function must be the first function to call, and it returns a CURL easy handle that you must use as input to other easy-functions. curl_easy_init -intializes curl and this call MUST have a corresponding call to -\fIcurl_easy_cleanup\fP when the operation is complete. +intializes curl and this call \fBMUST\fP have a corresponding call to +\fIcurl_easy_cleanup(3)\fP when the operation is complete. .SH RETURN VALUE If this function returns NULL, something went wrong and you cannot use the diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3 index a073d723d..ccc18c259 100644 --- a/docs/libcurl/curl_easy_perform.3 +++ b/docs/libcurl/curl_easy_perform.3 @@ -8,31 +8,26 @@ curl_easy_perform - Perform a file transfer .SH SYNOPSIS .B #include .sp -.BI "CURLcode curl_easy_perform(CURL *" handle "); +.BI "CURLcode curl_easy_perform(CURL *" handle ");" .ad .SH DESCRIPTION -This function is called after the init and all the curl_easy_setopt() calls -are made, and will perform the transfer as described in the options. -It must be called with the same +This function is called after the init and all the \fIcurl_easy_setopt(3)\fP +calls are made, and will perform the transfer as described in the options. It +must be called with the same .I handle as input as the curl_easy_init call returned. -libcurl version 7.7 or later (for older versions see below): You can do any -amount of calls to curl_easy_perform() while using the same handle. If you -intend to transfer more than one file, you are even encouraged to do -so. libcurl will then attempt to re-use the same connection for the following -transfers, thus making the operations faster, less CPU intense and using less -network resources. Just note that you will have to use -.I curl_easy_setopt -between the invokes to set options for the following curl_easy_perform. +You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the +same handle. If you intend to transfer more than one file, you are even +encouraged to do so. libcurl will then attempt to re-use the same connection +for the following transfers, thus making the operations faster, less CPU +intense and using less network resources. Just note that you will have to use +\fIcurl_easy_setopt(3)\fP between the invokes to set options for the following +curl_easy_perform. You must never call this function simultaneously from two places using the same handle. Let the function return first before invoking it another time. If you want parallel transfers, you must use several curl handles. - -Before libcurl version 7.7: You are only allowed to call this function once -using the same handle. If you want to do repeated calls, you must call -curl_easy_cleanup and curl_easy_init again first. .SH RETURN VALUE 0 means everything was ok, non-zero means an error occurred as .I @@ -42,5 +37,4 @@ there will be a readable error message in the error buffer when non-zero is returned. .SH "SEE ALSO" .BR curl_easy_init "(3), " curl_easy_setopt "(3), " -.SH BUGS -Surely there are some, you tell me! + diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a9f2fd3c0..4bd570b6e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -46,8 +46,8 @@ you must change them between the transfers. \fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be copied by the library. Instead you should keep them available until libcurl no longer needs them. Failing to do so will cause very odd behavior or even -crashes. libcurl will need them until you call curl_easy_cleanup() or you set -the same option again to use a different pointer. +crashes. libcurl will need them until you call \fIcurl_easy_cleanup(3)\fP or +you set the same option again to use a different pointer. The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. @@ -329,8 +329,8 @@ user. .IP CURLOPT_NETRC_FILE Pass a char * as parameter, pointing to a zero terminated string containing the full path name to the file you want libcurl to use as .netrc file. If this -option is omitted, and CURLOPT_NETRC is set, libcurl will attempt to find the -a .netrc file in the current user's home directory. (Added in 7.10.9) +option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to +find the 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. @@ -544,10 +544,10 @@ cookies for this session, so if you for example follow a location it will make matching cookies get sent accordingly. \fBNOTE:\fP If the cookie jar file can't be created or written to (when the -curl_easy_cleanup() is called), libcurl will not and cannot report an error -for this. Using \fICURLOPT_VERBOSE\fP or \fICURLOPT_DEBUGFUNCTION\fP will get -a warning to display, but that is the only visible feedback you get about this -possibly lethal situation. +\fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an +error for this. Using \fICURLOPT_VERBOSE\fP or \fICURLOPT_DEBUGFUNCTION\fP +will get a warning to display, but that is the only visible feedback you get +about this possibly lethal situation. .IP CURLOPT_COOKIESESSION Pass a long set to non-zero to mark this as a new cookie "session". It will force libcurl to ignore all cookies it is about to load that are "session @@ -914,8 +914,8 @@ support only works for FTP. .IP CURLOPT_PRIVATE Pass a char * as parameter, pointing to data that should be associated with this curl handle. The pointer can subsequently be retrieved using -\fIcurl_easy_getinfo\fP with the CURLINFO_PRIVATE option. libcurl itself does -nothing with this data. (Added in 7.10.3) +\fIcurl_easy_getinfo(3)\fP with the CURLINFO_PRIVATE option. libcurl itself +does nothing with this data. (Added in 7.10.3) .IP CURLOPT_SHARE Pass a share handle as a parameter. The share handle must have been created by a previous call to \fIcurl_share_init(3)\fP. Setting this option, will make @@ -931,7 +931,7 @@ supports the options 'TTYPE', 'XDISPLOC' and 'NEW_ENV'. See the TELNET standard for details. .SH RETURN VALUE CURLE_OK (zero) means that the option was set properly, non-zero means an -error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP +error occurred as \fI\fP defines. See the \fIlibcurl-errors(3)\fP man page for the full list with descriptions. .SH "SEE ALSO" .BR curl_easy_init "(3), " curl_easy_cleanup "(3), " diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 7e40cc550..c10a87864 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -23,4 +23,4 @@ You must curl_free() the returned string when you're done with it. .SH RETURN VALUE A pointer to a zero terminated string or NULL if it failed. .SH "SEE ALSO" -.BR curl_unescape(), curl_free(), RFC 2396 +.BR curl_unescape(3), curl_free(3), RFC 2396 diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 9802351d1..3cc428019 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -92,8 +92,8 @@ name field in the content header. .B CURLFORM_BUFFERPTR followed by a pointer to a data area, tells libcurl the address of the buffer containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The -buffer containing this data must not be freed until after curl_easy_cleanup is -called. +buffer containing this data must not be freed until after +\fIcurl_easy_cleanup(3)\fP is called. .B CURLFORM_BUFFERLENGTH followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area, @@ -114,9 +114,9 @@ of headers to those libcurl automatically generates. The list must exist while the POST occurs, if you free it before the post completes you may experience problems. -When you've passed the HttpPost pointer to \fIcurl_easy_setopt\fP (using the -\fICURLOPT_HTTPPOST\fP option), you must not free the list until after you've -called \fIcurl_easy_cleanup\fP for the curl handle. +When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using +the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after +you've called \fIcurl_easy_cleanup(3)\fP for the curl handle. See example below. .SH RETURN VALUE @@ -207,6 +207,3 @@ defines. .BR curl_easy_setopt "(3), " .BR curl_formparse "(3) [deprecated], " .BR curl_formfree "(3)" -.SH BUGS -Surely there are some, you tell me! - diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 263d9aa37..31c74e2dd 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -12,16 +12,9 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain .ad .SH DESCRIPTION curl_formfree() is used to clean up data previously built/appended with -curl_formadd()/curl_formparse(). This must be called when the data has -been used, which typically means after the curl_easy_perform() has -been called. +\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. .SH RETURN VALUE None .SH "SEE ALSO" -.BR curl_formparse "(3) [deprecated], " .BR curl_formadd "(3) " -.SH BUGS -libcurl 7.7.1 and earlier versions does not allow a NULL pointer to be used as -argument. - - diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 index d07fccd4e..faa1066d8 100644 --- a/docs/libcurl/curl_free.3 +++ b/docs/libcurl/curl_free.3 @@ -11,7 +11,8 @@ curl_free - reclaim memory that has been obtained through a libcurl call .BI "void curl_free( char *" ptr " );" .ad .SH DESCRIPTION -curl_free reclaims memory that has been obtained through a libcurl call. -Use curl_free() instead of free() to avoid anomalies that can result from differences in memory management between your application and libcurl. +curl_free reclaims memory that has been obtained through a libcurl call. Use +curl_free() instead of free() to avoid anomalies that can result from +differences in memory management between your application and libcurl. .SH "SEE ALSO" -.I curl_unescape() +.I curl_unescape(3) diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 0141e8c49..dd29567b8 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -74,7 +74,7 @@ Originally written by Steven M. Bellovin while at the University of North Carolina at Chapel Hill. Later tweaked by a couple of people on Usenet. Completely overhauled by Rich $alz and Jim Berets in August, 1990. + +It has been modified extensively since imported to curl. .SH "SEE ALSO" -.BR -.SH BUGS -Surely there are some, you tell me! +.BR GNU date(1) diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index d10932197..5cfd3a496 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -8,7 +8,7 @@ curl_getenv - return value for environment name .SH SYNOPSIS .B #include .sp -.BI "char *curl_getenv(const char *" name "); +.BI "char *curl_getenv(const char *" name ");" .ad .SH DESCRIPTION curl_getenv() is a portable wrapper for the getenv() function, meant to @@ -18,7 +18,7 @@ systems libcurl builds on (including win32). If successful, curl_getenv() returns a pointer to the value of the specified environment. The memory it refers to is malloc()ed why the application must free() this when the data has completed to serve its purpose. When -.I curl_getenv() +.I curl_getenv(3) fails 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 @@ -27,6 +27,3 @@ unix implementation thus have to suffer slightly from the drawbacks of other systems. .SH "SEE ALSO" .BR getenv "(3C), " -.SH BUGS -Surely there are some, you tell me! - diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3 index 4bc12d8fd..566b110e0 100644 --- a/docs/libcurl/curl_global_cleanup.3 +++ b/docs/libcurl/curl_global_cleanup.3 @@ -4,7 +4,7 @@ .\" .TH curl_global_cleanup 3 "28 May 2001" "libcurl 7.8" "libcurl Manual" .SH NAME -curl_global_cleanup - Global libcurl cleanup +curl_global_cleanup - global libcurl cleanup .SH SYNOPSIS .B #include .sp @@ -15,13 +15,9 @@ curl_global_cleanup must be called once (no matter how many threads or libcurl sessions that'll be used) by every application that uses libcurl, after all uses of libcurl is complete. -This is the opposite of \fIcurl_global_init\fP. +This is the opposite of \fIcurl_global_init(3)\fP. Not calling this function may result in memory leaks. - -This function was added in libcurl 7.8. .SH "SEE ALSO" .BR curl_global_init "(3), " -.SH BUGS -None? diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index ea8419f49..04a0b0238 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -14,18 +14,17 @@ curl_global_init - Global libcurl initialisation This function should only be called once (no matter how many threads or libcurl sessions that'll be used) by every application that uses libcurl. -If this function hasn't been invoked when \fIcurl_easy_init\fP is called, it -will be done automatically by libcurl. +If this function hasn't been invoked when \fIcurl_easy_init(3)\fP is called, +it will be done automatically by libcurl. The flags option is a bit pattern that tells libcurl exact what features to init, as described below. Set the desired bits by ORing the values together. -You must however \fBalways\fP use the \fIcurl_global_cleanup\fP function, as -that cannot be called automatically for you by libcurl. +You must however \fBalways\fP use the \fIcurl_global_cleanup(3)\fP function, +as that cannot be called automatically for you by libcurl. Calling this function more than once will cause unpredictable results. -This function was added in libcurl 7.8. .SH FLAGS .TP 5 .B CURL_GLOBAL_ALL @@ -35,7 +34,7 @@ Initialize everything possible. This sets all known bits. Initialize SSL .TP .B CURL_GLOBAL_WIN32 -Initialize the Win32 socket libraries. (added in libcurl 7.8.1) +Initialize the Win32 socket libraries. .TP .B CURL_GLOBAL_NOTHING Initialise nothing extra. This sets no bit. @@ -44,6 +43,5 @@ If this function returns non-zero, something went wrong and you cannot use the other curl functions. .SH "SEE ALSO" .BR curl_global_cleanup "(3), " -.SH BUGS -None. + diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 index b47a38320..8a61366f1 100644 --- a/docs/libcurl/curl_slist_append.3 +++ b/docs/libcurl/curl_slist_append.3 @@ -18,7 +18,8 @@ the new list is returned from this function. The specified \fIstring\fP has been appended when this function returns. curl_slist_append() copies the string. -The list should be freed again (after usage) with \fBcurl_slist_free_all()\fP. +The list should be freed again (after usage) with +\fBcurl_slist_free_all(3)\fP. .SH RETURN VALUE A null pointer is returned if anything went wrong, otherwise the new list pointer is returned. @@ -34,6 +35,3 @@ pointer is returned. curl_slist_free_all(slist); /* free the list again */ .SH "SEE ALSO" .BR curl_slist_free_all "(3), " -.SH BUGS -None. - diff --git a/docs/libcurl/curl_slist_free_all.3 b/docs/libcurl/curl_slist_free_all.3 index f471a8922..079bdf105 100644 --- a/docs/libcurl/curl_slist_free_all.3 +++ b/docs/libcurl/curl_slist_free_all.3 @@ -17,6 +17,4 @@ linked list. Nothing. .SH "SEE ALSO" .BR curl_slist_append "(3), " -.SH BUGS -Surely there are some, you tell me! diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index 5432d5e1b..ccde26e44 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -24,4 +24,4 @@ You must curl_free() the returned string when you're done with it. .SH RETURN VALUE A pointer to a zero terminated string or NULL if it failed. .SH "SEE ALSO" -.I curl_escape(), curl_free(), RFC 2396 +.I curl_escape(3), curl_free(3), RFC 2396 diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index ed1327b21..abe082eb1 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -47,9 +47,9 @@ field). \fIversion\fP is just an ascii string for the libcurl version. -\fIversion_num\fP is a 6 digit hexadecimal number created like this: <2 digits -major number> | <2 digits minor number> | <2 digits patch number>. Version -7.9.8 is therefore returned as 0x070908. +\fIversion_num\fP is a 24 bit number created like this: <8 bits major number> +| <8 bits minor number> | <8 bits patch number>. Version 7.9.8 is therefore +returned as 0x070908. \fIhost\fP is an ascii string showing what host information that this libcurl was built for. As discovered by a configure script or set by the build -- cgit v1.2.1 From 4ae4336643b1ea716052e952f0fd7bd498fb5526 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 27 Feb 2004 15:48:13 +0000 Subject: using roffit 0.6 we can get links with the --mandir option --- docs/libcurl/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 9ef967d0a..14d1a49b4 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -122,7 +122,7 @@ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) -MAN2HTML= roffit < $< >$@ +MAN2HTML= roffit --mandir=. < $< >$@ SUFFIXES = .3 .html -- cgit v1.2.1 From 45c7f064d45d5ff084002aadb10a6fe2c879b64a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 1 Mar 2004 08:02:50 +0000 Subject: mention how to make a curl handle use the share --- docs/libcurl/curl_share_init.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index 35fd5a1c9..eb0b23e4e 100644 --- a/docs/libcurl/curl_share_init.3 +++ b/docs/libcurl/curl_share_init.3 @@ -13,6 +13,10 @@ This function returns a CURLSH handle to be used as input to all the other share-functions, sometimes refered to as a share handle on 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. + +This \fIshare handle\fP is what you pass to curl using the \fICURLOPT_SHARE\fP +option with \fIcurl_easy_setopt(3)\fP, to make that specific curl handle use +the data in this share. .SH RETURN VALUE If this function returns NULL, something went wrong (out of memory, etc.) and therefore the share object was not created. -- cgit v1.2.1 From 526c61c6574db5fcc1fc9fd7981f5192f082573e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 1 Mar 2004 15:50:15 +0000 Subject: global dns cache is not nice, we consider it obsolete starting now --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4bd570b6e..afe04b29c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -283,6 +283,10 @@ libcurl caches this info for 60 seconds. Pass a long. If the value is non-zero, it tells curl to use a global DNS cache that will survive between easy handle creations and deletions. This is not thread-safe and this will use a global varible. + +\fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over +to using the share interface instead! See \fICURLOPT_SHARE\fP and +\fIcurl_share_init(3)\fP. .IP CURLOPT_BUFFERSIZE Pass a long specifying your prefered size for the receive buffer in libcurl. The main point of this would be that the write callback gets called more often -- cgit v1.2.1 From 9d311ff2c09e8bcf46b9a1ab126f079b088c1ef6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Mar 2004 13:57:38 +0000 Subject: mention error 64 --- docs/libcurl/libcurl-errors.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 9ca61752f..850198f0c 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl-errors 3 "18 Oct 2003" "libcurl 7.10.8" "libcurl errors" +.TH libcurl-errors 3 "8 Mar 2004" "libcurl 7.11.0" "libcurl errors" .SH NAME libcurl-errors \- error codes in libcurl .SH DESCRIPTION @@ -182,6 +182,8 @@ Unrecognized transfer encoding Invalid LDAP URL .IP "CURLE_FILESIZE_EXCEEDED (63)" Maximum file size exceeded +.IP "CURLE_FTP_SSL_FAILED (64)" +Requested FTP SSL level failed .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. -- cgit v1.2.1 From 1ebda8fa0eedf04a9759bd08b904199b2c02a0bf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Mar 2004 08:55:47 +0000 Subject: Added CURLOPT_POSTFIELDSIZE_LARGE to offer a large file version of the CURLOPT_POSTFIELDSIZE option to allow really big HTTP POSTs. --- docs/libcurl/curl_easy_setopt.3 | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index afe04b29c..7feb1eb03 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "27 Feb 2004" "libcurl 7.11.1" "libcurl Manual" +.TH curl_easy_setopt 3 "12 Mar 2004" "libcurl 7.11.1" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -464,6 +464,11 @@ If you want to post data to the server without letting libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If this size is set to zero, the library will use strlen() to get the size. +.IP CURLOPT_POSTFIELDSIZE_LARGE +Pass a curl_off_t as parameter. Use this to set the size of the +\fICURLOPT_POSTFIELDS\fP data to prevent libcurl from doing strlen() on the +data to figure out the size. This is the large file version of the +\fICURLOPT_POSTFIELDSIZE\fP option. .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 -- cgit v1.2.1 From bc7122f6e2c045c4dbf2ddc374ce4fd437753f62 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Mar 2004 09:14:45 +0000 Subject: CURLOPT_POSTFIELDSIZE_LARGE is added in 7.11.1 --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7feb1eb03..0e5ab98ee 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -468,7 +468,7 @@ size is set to zero, the library will use strlen() to get the size. Pass a curl_off_t as parameter. Use this to set the size of the \fICURLOPT_POSTFIELDS\fP data to prevent libcurl from doing strlen() on the data to figure out the size. This is the large file version of the -\fICURLOPT_POSTFIELDSIZE\fP option. +\fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1) .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 -- cgit v1.2.1 From 4ebf4f6e55e62ebf039453a4b1f79aeb85662fb8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Mar 2004 10:23:14 +0000 Subject: better mentioning of other functions to create proper hrefs in the web version --- docs/libcurl/libcurl-share.3 | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-share.3 b/docs/libcurl/libcurl-share.3 index 6a8e22fb3..4745c122e 100644 --- a/docs/libcurl/libcurl-share.3 +++ b/docs/libcurl/libcurl-share.3 @@ -20,27 +20,27 @@ You can have multiple easy handles share data between them. Have them update and use the \fBsame\fP cookie database or DNS cache! This way, each single transfer will take advantage from data updates made by the other transfer(s). .SH "SHARE OBJECT" -You create a shared object with \fIcurl_share_init()\fP. It returns a handle +You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle for a newly created one. You tell the shared object what data you want it to share by using -\fIcurl_share_setopt()\fP. Currently you can only share DNS and/or COOKIE +\fIcurl_share_setopt(3)\fP. Currently you can only share DNS and/or COOKIE data. Since you can use this share from multiple threads, and libcurl has no internal thread synchronization, you must provide mutex callbacks if you're using this multi-threaded. You set lock and unlock functions with -\fIcurl_share_setopt()\fP too. +\fIcurl_share_setopt(3)\fP too. -Then, you make an easy handle to use this share, you set the CURLOPT_SHARE -option with \fIcurl_easy_setopt\fP, and pass in share handle. You can make any -number of easy handles share the same share handle. +Then, you make an easy handle to use this share, you set the +\fICURLOPT_SHARE\fP option with \fIcurl_easy_setopt(3)\fP, and pass in share +handle. You can make any number of easy handles share the same share handle. -To make an easy handle stop using that particular share, you set CURLOPT_SHARE -to NULL for that easy handle. To make a handle stop sharing a particular data, -you can CURLSHOPT_UNSHARE it. +To make an easy handle stop using that particular share, you set +\fICURLOPT_SHARE\fP to NULL for that easy handle. To make a handle stop +sharing a particular data, you can \fICURLSHOPT_UNSHARE\fP it. When you're done using the share, make sure that no easy handle is still using -it, and call \fIcurl_share_cleanup()\fP on the handle. +it, and call \fIcurl_share_cleanup(3)\fP on the handle. .SH "SEE ALSO" .BR curl_share_init "(3), " curl_share_setopt "(3), " curl_share_cleanup "(3)" -- cgit v1.2.1 From 237ec68b0eb41e97193f9fad7fe3b436b897bd52 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Mar 2004 10:26:08 +0000 Subject: better formatting of functions to get better links in the web version --- docs/libcurl/libcurl-multi.3 | 48 ++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 24 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 0fdff2e0b..aadc070ec 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -40,29 +40,29 @@ and setup the appropriate options for each easy handle, as outlined in the \fIlibcurl(3)\fP man page, using \fIcurl_easy_setopt(3)\fP. When the easy handle is setup for a transfer, then instead of using -\fIcurl_easy_perform\fP (as when using the easy interface for transfers), you -should instead add the easy handle to the multi handle using -\fIcurl_easy_add_handl\fP. The multi handle is sometimes referred to as a +\fIcurl_easy_perform(3)\fP (as when using the easy interface for transfers), +you should instead add the easy handle to the multi handle using +\fIcurl_easy_add_handle(3)\fP. The multi handle is sometimes referred to as a \'multi stack\' because of the fact that it may hold a large amount of easy handles. Should you change your mind, the easy handle is again removed from the multi -stack using \fIcurl_multi_remove_handle\fP. Once removed from the multi +stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi handle, you can again use other easy interface functions like \fIcurl_easy_perform\fP on the handle or whatever you think is necessary. Adding the easy handle to the multi handle does not start the transfer. Remember that one of the main ideas with this interface is to let your application drive. You drive the transfers by invoking -\fIcurl_multi_perform\fP. libcurl will then transfer data if there is anything -available to transfer. It'll use the callbacks and everything else you have -setup in the individual easy handles. It'll transfer data on all current -transfers in the multi stack that are ready to transfer anything. It may be -all, it may be none. +\fIcurl_multi_perform(3)\fP. libcurl will then transfer data if there is +anything available to transfer. It'll use the callbacks and everything else +you have setup in the individual easy handles. It'll transfer data on all +current transfers in the multi stack that are ready to transfer anything. It +may be all, it may be none. Your application can acquire knowledge from libcurl when it would like to get invoked to transfer data, so that you don't have to busy-loop and call that -\fIcurl_multi_perform\fP like crazy. \fIcurl_multi_fdset\fP offers an +\fIcurl_multi_perform(3)\fP like crazy. \fIcurl_multi_fdset(3)\fP offers an interface using which you can extract fd_sets from libcurl to use in select() or poll() calls in order to get to know when the transfers in the multi stack might need attention. This also makes it very easy for your program to wait @@ -70,30 +70,30 @@ for input on your own private file descriptors at the same time or perhaps timeout every now and then, should you want that. A little note here about the return codes from the multi functions, and -especially the \fIcurl_multi_perform\fP: if you receive +especially the \fIcurl_multi_perform(3)\fP: if you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basicly means that you should call \fIcurl_multi_perform\fP again, before you select() on more 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". -\fIcurl_multi_perform\fP stores the number of still running transfers in one -of its input arguments, and by reading that you can figure out when all the -transfers in the multi handles are done. 'done' does not mean successful. One -or more of the transfers may have failed. Tracking when this number changes, -you know when one or more transfers are done. +\fIcurl_multi_perform(3)\fP stores the number of still running transfers in +one of its input arguments, and by reading that you can figure out when all +the transfers in the multi handles are done. 'done' does not mean +successful. One or more of the transfers may have failed. Tracking when this +number changes, you know when one or more transfers are done. To get information about completed transfers, to figure out success or not and -similar, \fIcurl_multi_info_read\fP should be called. It can return a message -about a current or previous transfer. Repeated invokes of the function get -more messages until the message queue is empty. The information you receive -there includes an easy handle pointer which you may use to identify which easy -handle the information regards. +similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a +message about a current or previous transfer. Repeated invokes of the function +get more messages until the message queue is empty. The information you +receive there includes an easy handle pointer which you may use to identify +which easy handle the information regards. When all transfers in the multi stack are done, cleanup the multi handle with -\fIcurl_multi_cleanup\fP. Be careful and please note that you \fBMUST\fP -invoke separate \fIcurl_easy_cleanup\fP calls on every single easy handle to -clean them up properly. +\fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP +invoke separate \fIcurl_easy_cleanup(3)\fP calls on every single easy handle +to clean them up properly. If you want to re-use an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it -- cgit v1.2.1 From c79fa187b97ea6cf78e1162fdf04aedd32d51778 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Mar 2004 11:26:53 +0000 Subject: more fixes --- docs/libcurl/libcurl-multi.3 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index aadc070ec..90b627329 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -42,14 +42,14 @@ and setup the appropriate options for each easy handle, as outlined in the When the easy handle is setup for a transfer, then instead of using \fIcurl_easy_perform(3)\fP (as when using the easy interface for transfers), you should instead add the easy handle to the multi handle using -\fIcurl_easy_add_handle(3)\fP. The multi handle is sometimes referred to as a +\fIcurl_multi_add_handle(3)\fP. The multi handle is sometimes referred to as a \'multi stack\' because of the fact that it may hold a large amount of easy handles. Should you change your mind, the easy handle is again removed from the multi stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi handle, you can again use other easy interface functions like -\fIcurl_easy_perform\fP on the handle or whatever you think is necessary. +\fIcurl_easy_perform(3)\fP on the handle or whatever you think is necessary. Adding the easy handle to the multi handle does not start the transfer. Remember that one of the main ideas with this interface is to let your @@ -72,9 +72,9 @@ timeout every now and then, should you want that. A little note here about the return codes from the multi functions, and especially the \fIcurl_multi_perform(3)\fP: if you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basicly means that you should call -\fIcurl_multi_perform\fP again, before you select() on more 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 +\fIcurl_multi_perform(3)\fP again, before you select() on more 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". \fIcurl_multi_perform(3)\fP stores the number of still running transfers in -- cgit v1.2.1 From 8114f8562b2c9762e8bd164de4b2d73b8094a781 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Mar 2004 11:30:29 +0000 Subject: use .NF for the struct part to looke better in HTML format some function references properly --- docs/libcurl/curl_multi_info_read.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 4abd91e51..eb8363c0b 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -21,13 +21,14 @@ integer pointed to with \fImsgs_in_queue\fP will contain the number of remaining messages after this function was called. The data the returned pointer points to will not survive calling -curl_multi_cleanup(). +\fIcurl_multi_cleanup(3)\fP. The 'CURLMsg' struct is very simple and only contain very basic informations. If more involved information is wanted, the particular "easy handle" in present in that struct and can thus be used in subsequent regular -curl_easy_getinfo() calls (or similar): +\fIcurl_easy_getinfo(3)\fP calls (or similar): +.NF struct CURLMsg { CURLMSG msg; /* what this message means */ CURL *easy_handle; /* the handle it concerns */ -- cgit v1.2.1 From 6dc8fac1229c7cb23995dd105f3cd5184d4bd6ca Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Mar 2004 11:37:37 +0000 Subject: random formatting updates to look better in HTML version --- docs/libcurl/curl_multi_add_handle.3 | 6 +++--- docs/libcurl/curl_multi_cleanup.3 | 2 +- docs/libcurl/curl_multi_fdset.3 | 3 ++- docs/libcurl/curl_multi_init.3 | 7 +++---- docs/libcurl/curl_multi_perform.3 | 7 ++++--- docs/libcurl/libcurl-multi.3 | 2 +- 6 files changed, 14 insertions(+), 13 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index c2077a048..1f0755002 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -9,11 +9,11 @@ curl_multi_add_handle - add an easy handle to a multi session CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); .ad .SH DESCRIPTION -Adds a standard easy handle to the multi stack. This will make this multi -handle control the specified easy handle. +Adds a standard easy handle to the multi stack. This function call will make +this \fImulti_handle\fP control the specified \fIeasy_handle\fP. When an easy handle has been added to a multi stack, you can not and you must -not use curl_easy_perform() on that handle! +not use \fIcurl_easy_perform(3)\fP on that handle! .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 index d7830e7ac..cbe3f0f11 100644 --- a/docs/libcurl/curl_multi_cleanup.3 +++ b/docs/libcurl/curl_multi_cleanup.3 @@ -11,7 +11,7 @@ curl_multi_cleanup - close down a multi session .SH DESCRIPTION Cleans up and removes a whole multi stack. It does not free or touch any individual easy handles in any way - they still need to be closed -individually, using the usual curl_easy_cleanup() way. +individually, using the usual \fIcurl_easy_cleanup(3)\fP way. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 2ec821029..f2b3f9aed 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -22,6 +22,7 @@ NOTE that once this call is made, you must not remove the sets you point to, as libcurl will need to be able to read them. It needs them after select() calls, to know if certain sockets are readable or writable. .SH RETURN VALUE -CURLMcode type, general libcurl multi interface error code. +CURLMcode type, general libcurl multi interface error code. See +\fIlibcurl-errors.3\fP .SH "SEE ALSO" .BR curl_multi_cleanup "(3)," curl_multi_init "(3)" diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index e3619d5c5..40875a81e 100644 --- a/docs/libcurl/curl_multi_init.3 +++ b/docs/libcurl/curl_multi_init.3 @@ -2,7 +2,7 @@ .\" .TH curl_multi_init 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME -curl_multi_init - Start a multi session +curl_multi_init - create a multi handle .SH SYNOPSIS .B #include .sp @@ -12,11 +12,10 @@ curl_multi_init - Start a multi session This function returns a CURLM handle to be used as input to all the other multi-functions, sometimes refered to as a multi handle on some places in the documentation. This init call MUST have a corresponding call to -\fIcurl_multi_cleanup\fP when the operation is complete. +\fIcurl_multi_cleanup(3)\fP when the operation is complete. .SH RETURN VALUE If this function returns NULL, something went wrong and you cannot use the other curl functions. .SH "SEE ALSO" .BR curl_multi_cleanup "(3)," curl_global_init "(3)," curl_easy_init "(3)" -.SH BUGS -Surely there are some, you tell me! + diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 5b54fea8d..51c45aa93 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -29,8 +29,9 @@ NOTE that this only returns errors etc regarding the whole multi stack. There might still have occurred problems on invidual transfers even when this function returns OK. .SH "TYPICAL USAGE" -Most application will use \fIcurl_multi_fdset\fP to get the multi_handle's +Most application will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's file descriptors, then it'll wait for action on them using select() and as -soon as one or more of them are ready, \fIcurl_multi_perform\fP gets called. +soon as one or more of them are ready, \fIcurl_multi_perform(3)\fP gets +called. .SH "SEE ALSO" -.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)," curl_multi_fdset "(3)" diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 90b627329..13b6b84dc 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -32,7 +32,7 @@ complicated for the application. file descriptors simultaneous easily. .SH "ONE MULTI HANDLE MANY EASY HANDLES" To use the multi interface, you must first create a 'multi handle' with -\fIcurl_multi_init\fP. This handle is then used as input to all further +\fIcurl_multi_init(3)\fP. This handle is then used as input to all further curl_multi_* functions. Each single transfer is built up with an easy handle. You must create them, -- cgit v1.2.1 From 8c4e91a653de78deab7bd2a6f8a3c6197dc7730d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Mar 2004 11:56:07 +0000 Subject: refer to function names better to enhance the HTML output --- docs/libcurl/libcurl.3 | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index c121941d3..422d56f29 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -15,13 +15,13 @@ further reading on how to do programming with libcurl. There exist more than a dozen custom bindings that bring libcurl access to your favourite language. Look elsewhere for documentation on those. -All applications that use libcurl should call \fIcurl_global_init()\fP exactly -once before any libcurl function can be used. After all usage of libcurl is -complete, it \fBmust\fP call \fIcurl_global_cleanup()\fP. In between those two -calls, you can use libcurl as described below. +All applications that use libcurl should call \fIcurl_global_init(3)\fP +exactly once before any libcurl function can be used. After all usage of +libcurl is complete, it \fBmust\fP call \fIcurl_global_cleanup(3)\fP. In +between those two calls, you can use libcurl as described below. To transfer files, you always set up an "easy handle" using -\fIcurl_easy_init()\fP, but when you want the file(s) transfered you have the +\fIcurl_easy_init(3)\fP, but when you want the file(s) transfered you have the option of using the "easy" interface, or the "multi" interface. The easy interface is a synchronous interface with which you call @@ -60,7 +60,7 @@ get information about a performed transfer helps building a HTTP form POST .TP .B curl_formfree() -free a list built with curl_formparse()/curl_formadd() +free a list built with \fIcurl_formadd(3)\fP .TP .B curl_slist_append() builds a linked list @@ -107,15 +107,15 @@ Persistent connections means that libcurl can re-use the same connection for several transfers, if the conditions are right. libcurl will *always* attempt to use persistent connections. Whenever you use -\fIcurl_easy_perform()\fP or \fIcurl_multi_perform()\fP, libcurl will attempt -to use an existing connection to do the transfer, and if none exists it'll -open a new one that will be subject for re-use on a possible following call to -\fIcurl_easy_perform()\fP or \fIcurl_multi_perform()\fP. +\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP, libcurl will +attempt to use an existing connection to do the transfer, and if none exists +it'll open a new one that will be subject for re-use on a possible following +call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. To allow libcurl to take full advantage of persistent connections, you should do as many of your file transfers as possible using the same curl handle. When -you call \fIcurl_easy_cleanup()\fP, all the possibly open connections held by +you call \fIcurl_easy_cleanup(3)\fP, all the possibly open connections held by libcurl will be closed and forgotten. -Note that the options set with \fIcurl_easy_setopt()\fP will be used in on -every repeated \fIcurl_easy_perform()\fP call. +Note that the options set with \fIcurl_easy_setopt(3)\fP will be used in on +every repeated \fIcurl_easy_perform(3)\fP call. -- cgit v1.2.1 From 7de892eeb4203e5a41b8943cd108e7c4d1e02883 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Mar 2004 12:41:24 +0000 Subject: more formatting fixes --- docs/libcurl/libcurl.3 | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 422d56f29..54c7d0a54 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -8,8 +8,8 @@ libcurl \- client-side URL transfers .SH DESCRIPTION This is an overview on how to use libcurl in your C programs. There are specific man pages for each function mentioned in here. There are also the -\fIlibcurl-easy\fP man page, the \fIlibcurl-multi\fP man page, the -\fIlibcurl-share\fP man page and the \fIlibcurl-the-guide\fP document for +\fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the +\fIlibcurl-share(3)\fP man page and the \fIlibcurl-the-guide\fP document for further reading on how to do programming with libcurl. There exist more than a dozen custom bindings that bring libcurl access to @@ -25,10 +25,9 @@ To transfer files, you always set up an "easy handle" using option of using the "easy" interface, or the "multi" interface. The easy interface is a synchronous interface with which you call -\fIcurl_easy_perform\fP and let it perform the transfer. When it is completed, -the function return and you can continue. More details are found in the -.BR "libcurl-easy (3)" -man page. +\fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is +completed, the function return and you can continue. More details are found in +the \fIlibcurl-easy(3)\fP man page. The multi interface on the other hand is an asynchronous interface, that you call and that performs only a little piece of the tranfer on each invoke. It @@ -38,7 +37,7 @@ even to easily download multiple files simultaneously using a single thread. You can have multiple easy handles share certain data, even if they are used in different threads. This magic is setup using the share interface, as -described in the \fIlibcurl-share\fP man page. +described in the \fIlibcurl-share(3)\fP man page. There is also a series of other helpful functions to use. They are: @@ -102,12 +101,12 @@ Never ever call curl-functions simultaneously using the same handle from several threads. libcurl is thread-safe and can be used in any number of threads, but you must use separate curl handles if you want to use libcurl in more than one thread simultaneously. -.SH "PERSISTANT CONNECTIONS" +.SH "PERSISTENT CONNECTIONS" Persistent connections means that libcurl can re-use the same connection for several transfers, if the conditions are right. -libcurl will *always* attempt to use persistent connections. Whenever you use -\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP, libcurl will +libcurl will \fBalways\fP attempt to use persistent connections. Whenever you +use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP, libcurl will attempt to use an existing connection to do the transfer, and if none exists it'll open a new one that will be subject for re-use on a possible following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. -- cgit v1.2.1 From 03a0988ce83994a4bc311858f9bbb52ef63cd876 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Mar 2004 12:42:19 +0000 Subject: better formatting to create fine links in the web version --- docs/libcurl/libcurl-easy.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 index b3aaacea9..b5689c459 100644 --- a/docs/libcurl/libcurl-easy.3 +++ b/docs/libcurl/libcurl-easy.3 @@ -9,21 +9,21 @@ libcurl-easy \- easy interface overview When using libcurl's "easy" interface you init your session and get a handle (often referred to as an "easy handle" in various docs and sources), which you use as input to the easy interface functions you use. Use -\fIcurl_easy_init()\fP to get the handle. +\fIcurl_easy_init(3)\fP to get the handle. You continue by setting all the options you want in the upcoming transfer, the most important among them is the URL itself (you can't transfer anything without a specified URL as you may have figured out yourself). You might want to set some callbacks as well that will be called from the library when data -is available etc. \fIcurl_easy_setopt()\fP is used for all this. +is available etc. \fIcurl_easy_setopt(3)\fP is used for all this. When all is setup, you tell libcurl to perform the transfer using -\fIcurl_easy_perform()\fP. It will then do the entire operation and won't +\fIcurl_easy_perform(3)\fP. It will then do the entire operation and won't return until it is done (successfully or not). After the transfer has been made, you can set new options and make another transfer, or if you're done, cleanup the session by calling -\fIcurl_easy_cleanup()\fP. If you want persistant connections, you don't +\fIcurl_easy_cleanup(3)\fP. If you want persistant connections, you don't cleanup immediately, but instead run ahead and perform other transfers using the same easy handle. -- cgit v1.2.1 From 4b78b4124eee95c42f05e9c3df9ca798a0318db9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 24 Mar 2004 21:40:45 +0000 Subject: Tor Arntsen's major ispell patch --- docs/libcurl/curl_easy_getinfo.3 | 6 ++--- docs/libcurl/curl_easy_init.3 | 2 +- docs/libcurl/curl_easy_setopt.3 | 45 +++++++++++++++++++------------------ docs/libcurl/curl_formadd.3 | 4 ++-- docs/libcurl/curl_getdate.3 | 2 +- docs/libcurl/curl_mprintf.3 | 2 +- docs/libcurl/curl_multi_info_read.3 | 2 +- docs/libcurl/curl_multi_init.3 | 2 +- docs/libcurl/curl_multi_perform.3 | 4 ++-- docs/libcurl/curl_share_init.3 | 2 +- docs/libcurl/libcurl-easy.3 | 2 +- docs/libcurl/libcurl-errors.3 | 8 +++---- docs/libcurl/libcurl-multi.3 | 4 ++-- docs/libcurl/libcurl.3 | 8 +++---- 14 files changed, 47 insertions(+), 46 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 49c7211d1..ca1c287d4 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -20,7 +20,7 @@ filled in accordingly and can be relied upon only if the function returns CURLE_OK. This function is intended to get used *AFTER* a performed transfer, all results from this function are undefined until the transfer is completed. .SH AVAILABLE INFORMATION -These are informations that can be extracted: +The following information can be extracted: .IP CURLINFO_EFFECTIVE_URL Pass a pointer to a 'char *' to receive the last used effective URL. .IP CURLINFO_RESPONSE_CODE @@ -51,7 +51,7 @@ pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. .IP CURLINFO_STARTTRANSFER_TIME Pass a pointer to a double to receive the time, in seconds, it took from the -start until the first byte is just about to be transfered. This includes +start until the first byte is just about to be transferred. This includes CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate the result. .IP CURLINFO_REDIRECT_TIME @@ -106,7 +106,7 @@ method(s) available. The meaning of the bits is explained in the CURLOPT_HTTPAUTH option for \fIcurl_easy_setopt(3)\fP. (Added in 7.10.8) .IP CURLINFO_PROXYAUTH_AVAIL Pass a pointer to a long to receive a bitmask indicating the authentication -method(s) available for your proxy athentication. (Added in 7.10.8) +method(s) available for your proxy authentication. (Added in 7.10.8) .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 890a8a85a..13f25cd11 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -13,7 +13,7 @@ curl_easy_init - Start a libcurl easy session .SH DESCRIPTION This function must be the first function to call, and it returns a CURL easy handle that you must use as input to other easy-functions. curl_easy_init -intializes curl and this call \fBMUST\fP have a corresponding call to +initializes curl and this call \fBMUST\fP have a corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is complete. .SH RETURN VALUE diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0e5ab98ee..16bed31a9 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -85,7 +85,7 @@ lookups. It enables nice timeouts for name resolves without signals. .IP CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This -function gets called by libcurl as soon as there is data reveiced that needs +function gets called by libcurl as soon as there is data received that needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP, it will not be zero terminated. Return the number of bytes actually taken care of. If that amount differs from the amount passed @@ -165,7 +165,7 @@ Function pointer that should match the following prototype: \fIint curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP \fICURLOPT_DEBUGFUNCTION\fP replaces the standard debug function used when \fICURLOPT_VERBOSE \fP is in effect. This callback receives debug information, -as specified with the \fBcurl_infotype\fP argument. This funtion must return +as specified with the \fBcurl_infotype\fP argument. This function must return 0. The data pointed to by the char * passed to this function WILL NOT be zero terminated, but will be exactly of the size as told by the size_t argument. @@ -191,7 +191,7 @@ Function pointer that should match the following prototype: \fBCURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called by libcurl just before the initialization of an SSL connection after having processed all other SSL related options to give a last chance to an -application to modify the behaviour of openssl's ssl initilaization. The +application to modify the behaviour of openssl's ssl initialization. The \fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If an error is returned no attempt to establish a connection is made and the perform operation will return the error code from this callback function. Set @@ -249,8 +249,8 @@ be prefixed with [protocol]:// since any such prefix will be ignored. The proxy's port number may optionally be specified with the separate option \fICURLOPT_PROXYPORT\fP. -\fBNOTE:\fP when you tell the library to use a HTTP proxy, libcurl will -transparently convert operations to HTTP even if you specify a FTP URL +\fBNOTE:\fP when you tell the library to use an HTTP proxy, libcurl will +transparently convert operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as \fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you tunnel through the HTTP proxy. Such tunneling is activated with @@ -282,13 +282,13 @@ libcurl caches this info for 60 seconds. .IP CURLOPT_DNS_USE_GLOBAL_CACHE Pass a long. If the value is non-zero, it tells curl to use a global DNS cache that will survive between easy handle creations and deletions. This is not -thread-safe and this will use a global varible. +thread-safe and this will use a global variable. \fBWARNING:\fP this option is considered obsolete. Stop using it. Switch over to using the share interface instead! See \fICURLOPT_SHARE\fP and \fIcurl_share_init(3)\fP. .IP CURLOPT_BUFFERSIZE -Pass a long specifying your prefered size for the receive buffer in libcurl. +Pass a long specifying your preferred size for the receive buffer in libcurl. The main point of this would be that the write callback gets called more often and with smaller chunks. This is just treated as a request, not an order. You cannot be guaranteed to actually get the given size. (Added in 7.10) @@ -370,7 +370,7 @@ regular old-fashioned Basic method. .IP CURLAUTH_GSSNEGOTIATE HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain "Negotiate") method was designed by Microsoft and is used in their web -aplications. It is primarily meant as a support for Kerberos5 authentication +applications. It is primarily meant as a support for Kerberos5 authentication but may be also used along with another authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. @@ -379,17 +379,17 @@ this to work. .IP CURLAUTH_NTLM HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to -prevent the password from being evesdropped. +prevent the password from being eavesdropped. \fBNOTE\fP that you need to build libcurl with SSL support for this option to work. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any -it finds suitable. libcurl will automaticly select the one it finds most +it finds suitable. libcurl will automatically select the one it finds most secure. .IP CURLAUTH_ANYSAFE This is a convenience macro that sets all bits except Basic and thus makes -libcurl pick any it finds suitable. libcurl will automaticly select the one it +libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. .RE .IP CURLOPT_PROXYAUTH @@ -405,7 +405,7 @@ this writing, only Basic and NTLM work. (Added in 7.10.7) .SH HTTP OPTIONS .IP CURLOPT_AUTOREFERER Pass a non-zero parameter to enable this. When enabled, libcurl will -automaticly set the Referer: field in requests where it follows a Location: +automatically set the Referer: field in requests where it follows a Location: redirect. .IP CURLOPT_ENCODING Sets the contents of the Accept-Encoding: header sent in an HTTP @@ -422,7 +422,7 @@ encoding done by the server is ignored. See the special file lib/README.encoding for details. .IP CURLOPT_FOLLOWLOCATION A non-zero parameter tells the library to follow any Location: header that the -server sends as part of a HTTP header. +server sends as part of an HTTP header. \fBNOTE:\fP this means that the library will re-send the same request on the new location and follow new Location: headers all the way until no more such @@ -447,7 +447,7 @@ one by HTML forms. See the \fICURLOPT_POSTFIELDS\fP option for how to specify the data to post and \fICURLOPT_POSTFIELDSIZE\fP in how to set the data size. Using the \fICURLOPT_POSTFIELDS\fP option implies this option. .IP CURLOPT_POSTFIELDS -Pass a char * as parameter, which should be the full data to post in a HTTP +Pass a char * as parameter, which should be the full data to post in an HTTP post operation. You need to make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded. Take note. @@ -529,9 +529,10 @@ set a cookie in the http request. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie should contain. -If you need to set mulitple cookies, you need to set them all using a single -option and thus you need to concat them all in one single string. Set multiple -cookies in one string like this: "name1=content1; name2=content2;" etc. +If you need to set multiple cookies, you need to set them all using a single +option and thus you need to concatenate them all in one single string. Set +multiple cookies in one string like this: "name1=content1; name2=content2;" +etc. Using this option multiple times will only make the latest string override the previously ones. @@ -622,7 +623,7 @@ only files in their response to NLST; they might not include subdirectories and symbolic links. .IP CURLOPT_FTPAPPEND A non-zero parameter tells the library to append to the remote file instead of -overwrite it. This is only useful when uploading to a ftp site. +overwrite it. This is only useful when uploading to an ftp site. .IP CURLOPT_FTP_USE_EPRT Pass a long. If the value is non-zero, it tells curl to use the EPRT (and LPRT) command when doing active FTP downloads (which is enabled by @@ -684,7 +685,7 @@ Pass an curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user -instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST +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 more or less obscure HTTP requests. Don't do this at will, make sure your server supports the command first. @@ -863,7 +864,7 @@ key. \fBNOTE:\fPIf the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. .IP CURLOPT_SSLENGINE_DEFAULT -Sets the actual crypto engine as the default for (asymetric) crypto +Sets the actual crypto engine as the default for (asymmetric) crypto operations. \fBNOTE:\fPIf the crypto device cannot be set, @@ -904,8 +905,8 @@ in the SSL handshake, set 1 to check existence, 2 to ensure that it matches the provided hostname. This is by default set to 2. (default changed in 7.10) .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 syntactly correct, it -consists of one or more cipher strings separated by colons. Commas or spaces +ciphers to use for the SSL connection. The list must be syntactically correct, +it consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, \!, \- and \+ can be used as operators. Valid examples of cipher lists include 'RC4-SHA', \'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 3cc428019..95671e7f9 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -13,7 +13,7 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata -HTTP POST (sometimes refered to as rfc1867-style posts). Append one section at +HTTP POST (sometimes referred to as rfc1867-style posts). Append one section at a time until you've added all the sections you want included and then you pass the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. \fIlastitem\fP is set after each call and on repeated invokes it should be @@ -81,7 +81,7 @@ internally chosen one. .B CURLFORM_FILENAME followed by a pointer to a string to a name, will make libcurl use the given -name in the file upload part, intead of the actual file name given to +name in the file upload part, instead of the actual file name given to \fICURLFORM_FILE\fP. .B BCURLFORM_BUFFER diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index dd29567b8..6e936cf13 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -36,7 +36,7 @@ This string specifies the time on a given day. Syntax supported includes: .TP .B time zone items Specifies international time zone. There are a few acronyms supported, but in -general you should instead use the specific realtive time compared to +general you should instead use the specific relative time compared to UTC. Supported formats include: -1200, MST, +0100. .TP .B day of the week items diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index 839b22536..68621ff0b 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -42,7 +42,7 @@ See this table for notable exceptions. Normal printf() clone. .TP .B curl_mfprintf() -Normal fprinf() clone. +Normal fprintf() clone. .TP .B curl_msprintf() Normal sprintf() clone. diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index eb8363c0b..26b9e40b3 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -23,7 +23,7 @@ remaining messages after this function was called. The data the returned pointer points to will not survive calling \fIcurl_multi_cleanup(3)\fP. -The 'CURLMsg' struct is very simple and only contain very basic informations. +The 'CURLMsg' struct is very simple and only contain 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): diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index 40875a81e..59f845b15 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 refered to as a multi handle on some places in the +multi-functions, sometimes referred to as a multi handle on 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 51c45aa93..263550df2 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -19,14 +19,14 @@ integer-pointer. .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. -If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basicly means that you +If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you should call \fIcurl_multi_perform\fP again, before you select() on more 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". NOTE that this only returns errors etc regarding the whole multi stack. There -might still have occurred problems on invidual transfers even when this +might still have occurred problems on individual transfers even when this function returns OK. .SH "TYPICAL USAGE" Most application will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index eb0b23e4e..ead7f4b81 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 refered to as a share handle on some places in the +share-functions, sometimes referred to as a share handle on 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/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 index b5689c459..2fe4c82e5 100644 --- a/docs/libcurl/libcurl-easy.3 +++ b/docs/libcurl/libcurl-easy.3 @@ -23,7 +23,7 @@ return until it is done (successfully or not). After the transfer has been made, you can set new options and make another transfer, or if you're done, cleanup the session by calling -\fIcurl_easy_cleanup(3)\fP. If you want persistant connections, you don't +\fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you don't cleanup immediately, but instead run ahead and perform other transfers using the same easy handle. diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 850198f0c..7f315357a 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -36,7 +36,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 a FTP server, libcurl expects to get a certain reply back. +After connecting to an FTP server, libcurl expects to get a certain reply back. This error code implies that it god a strange or bad reply. The given remote server is probably not an OK FTP server. .IP "CURLE_FTP_ACCESS_DENIED (9)" @@ -93,7 +93,7 @@ There was a problem reading a local file or an error returned by the read callback. .IP "CURLE_OUT_OF_MEMORY (27)" Out of memory. A memory allocation request failed. This is serious badness and -things are severly screwed up if this ever occur. +things are severely screwed up if this ever occur. .IP "CURLE_OPERATION_TIMEOUTED (28)" Operation timeout. The specified time-out period was reached according to the conditions. @@ -106,14 +106,14 @@ specified a good enough address for libcurl to use. See \fICURLOPT_FTPPORT\fP. The FTP REST command returned error. This should never happen if the server is sane. .IP "CURLE_FTP_COULDNT_GET_SIZE (32)" -The FTP SIZE command returned errror. SIZE is not a kosher FTP command, it is +The FTP SIZE command returned error. SIZE is not a kosher FTP command, it is an extension and not all servers support it. This is not a surprising error. .IP "CURLE_HTTP_RANGE_ERROR (33)" The HTTP server does not support or accept range requests. .IP "CURLE_HTTP_POST_ERROR (34)" This is an odd error that mainly occurs due to internal confusion. .IP "CURLE_SSL_CONNECT_ERROR (35)" -A problem occured somewhere in the SSL/TLS handshake. You really want the +A problem occurred somewhere in the SSL/TLS handshake. You really want the error buffer and read the message there as it pinpoints the problem slightly more. Could be certificates (file formats, paths, permissions), passwords, and others. diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 13b6b84dc..b97ac9856 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -71,7 +71,7 @@ timeout every now and then, should you want that. A little note here about the return codes from the multi functions, and especially the \fIcurl_multi_perform(3)\fP: if you receive -\fICURLM_CALL_MULTI_PERFORM\fP, this basicly means that you should call +\fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you should call \fIcurl_multi_perform(3)\fP again, before you select() on more 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 @@ -97,4 +97,4 @@ to clean them up properly. If you want to re-use an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it -again (possbily after having altered some options at your own choice). +again (possibly after having altered some options at your own choice). diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 54c7d0a54..632bcdf61 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -21,8 +21,8 @@ libcurl is complete, it \fBmust\fP call \fIcurl_global_cleanup(3)\fP. In between those two calls, you can use libcurl as described below. To transfer files, you always set up an "easy handle" using -\fIcurl_easy_init(3)\fP, but when you want the file(s) transfered you have the -option of using the "easy" interface, or the "multi" interface. +\fIcurl_easy_init(3)\fP, but when you want the file(s) transferred you have +the option of using the "easy" interface, or the "multi" interface. The easy interface is a synchronous interface with which you call \fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is @@ -30,7 +30,7 @@ completed, the function return and you can continue. More details are found in the \fIlibcurl-easy(3)\fP man page. The multi interface on the other hand is an asynchronous interface, that you -call and that performs only a little piece of the tranfer on each invoke. It +call and that performs only a little piece of the transfer on each invoke. It is perfect if you want to do things while the transfer is in progress, or similar. The multi interface allows you to select() on libcurl action, and even to easily download multiple files simultaneously using a single thread. @@ -56,7 +56,7 @@ portable environment variable reader get information about a performed transfer .TP .B curl_formadd() -helps building a HTTP form POST +helps building an HTTP form POST .TP .B curl_formfree() free a list built with \fIcurl_formadd(3)\fP -- cgit v1.2.1 From bb3d6e8552f428bd0c2624854403d36ab3cf163d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 25 Mar 2004 13:37:18 +0000 Subject: tcp-nodelay patch by Joe Halpin --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 16bed31a9..eeb35d41e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -295,6 +295,22 @@ cannot be guaranteed to actually get the given size. (Added in 7.10) .IP CURLOPT_PORT Pass a long specifying what remote port number to connect to, instead of the one specified in the URL or the default port for the used protocol. +.IP CURLOPT_TCP_NODELAY +Pass a long specifying whether the TCP_NODELAY option should be set or +cleared (1 = set, 0 = clear). The option is cleared by default. This +will have no effect after the connection has been established. + +Setting this option will disable TCP's Nagle algorithm. The purpose of +this algorithm is to try to minimize the number of small packets on +the network (where "small packets" means TCP segments less than the +Maximum Segment Size (MSS) for the network). + +Maximizing the amount of data sent per TCP segment is good because it +amortizes the overhead of the send. However, in some cases (most +notably telnet or rlogin) small segments may need to be sent +without delay. This is less efficient than sending larger amounts of +data at a time, and can contribute to congestion on the network if +overdone. .SH NAMES and PASSWORDS OPTIONS (Authentication) .IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and -- cgit v1.2.1 From 7c72f8ee6ce50615c7708f02629db11cfd1c0e25 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 2 Apr 2004 11:04:34 +0000 Subject: prepend the man3 dir to the file name to work better. Robin Kay pointed this out. --- docs/libcurl/curl_strnequal.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_strnequal.3 b/docs/libcurl/curl_strnequal.3 index c7d91cca8..ce41d3e41 100644 --- a/docs/libcurl/curl_strnequal.3 +++ b/docs/libcurl/curl_strnequal.3 @@ -1 +1 @@ -.so curl_strequal.3 +.so man3/curl_strequal.3 -- cgit v1.2.1 From 1ca9ce5ef47763e2c53f8216a0450e2b72f3bc90 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 13 Apr 2004 09:08:52 +0000 Subject: removed the BUGS section since it offers nothing good --- docs/libcurl/curl_easy_duphandle.3 | 3 +-- docs/libcurl/curl_easy_init.3 | 2 -- 2 files changed, 1 insertion(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 index 4133e3289..4afb40ed5 100644 --- a/docs/libcurl/curl_easy_duphandle.3 +++ b/docs/libcurl/curl_easy_duphandle.3 @@ -31,5 +31,4 @@ If this function returns NULL, something went wrong and no valid handle was returned. .SH "SEE ALSO" .BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_global_init "(3) -.SH BUGS -Surely there are some, you tell me! + diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 13f25cd11..f7776b411 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -21,5 +21,3 @@ If this function returns NULL, something went wrong and you cannot use the other curl functions. .SH "SEE ALSO" .BR curl_easy_cleanup "(3), " curl_global_init "(3) -.SH BUGS -Surely there are some, you tell me! -- cgit v1.2.1 From c1422864b5acdfd607b2689cb5d7c0d9a855e24a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 13 Apr 2004 14:27:47 +0000 Subject: additional info --- docs/libcurl/curl_multi_add_handle.3 | 11 +++++++++++ docs/libcurl/curl_multi_cleanup.3 | 11 ++++++++++- docs/libcurl/libcurl-errors.3 | 15 +++++++++++++-- 3 files changed, 34 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index 1f0755002..11e530b98 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -14,6 +14,17 @@ this \fImulti_handle\fP control the specified \fIeasy_handle\fP. When an easy handle has been added to a multi stack, you can not and you must not use \fIcurl_easy_perform(3)\fP on that handle! + +The easy handle will remain added until you remove it again with +\fIcurl_multi_remove_handle(3)\fP. You should remove the easy handle from the +multi stack before you terminate first the easy handle and then the multi +handle: + +1 - \fIcurl_multi_remove_handle(3)\fP + +2 - \fIcurl_easy_cleanup(3)\fP + +3 - \fIcurl_multi_cleanup(3)\fP .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 index cbe3f0f11..128c03a0f 100644 --- a/docs/libcurl/curl_multi_cleanup.3 +++ b/docs/libcurl/curl_multi_cleanup.3 @@ -11,7 +11,16 @@ curl_multi_cleanup - close down a multi session .SH DESCRIPTION Cleans up and removes a whole multi stack. It does not free or touch any individual easy handles in any way - they still need to be closed -individually, using the usual \fIcurl_easy_cleanup(3)\fP way. +individually, using the usual \fIcurl_easy_cleanup(3)\fP way. The order of +cleaning up should be: + +1 - \fIcurl_multi_remove_handle(3)\fP before any easy handles are cleaned up + +2 - \fIcurl_easy_cleanup(3)\fP can now be called independently since the easy +handle is no longer connected to the multi handle + +3 - \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are +removed .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 7f315357a..241d1ff64 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -187,8 +187,19 @@ Requested FTP SSL level failed .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. - -This is left to be documented. +.IP "CURLM_CALL_MULTI_PERFORM (-1)" +This is not really an error. It means you should call +\fIcurl_multi_perform(3)\fP again without doing select() or similar in between. +.IP "CURLM_OK (0)" +Things are fine. +.IP "CURLM_BAD_HANDLE (1)" +The passed-in handle is not a valid CURLM handle. +.IP "CURLM_BAD_EASY_HANDLE (2)" +An easy handle was not good/valid. +.IP "CURLM_OUT_OF_MEMORY (3)" +You are doomed. +.IP "CURLM_INTERNAL_ERROR (4)" +This can only be returned if libcurl bugs. Please report it to us! .SH "CURLSHcode" The "share" interface will return a CURLSHcode to indicate when an error has occurred. -- cgit v1.2.1 From bba3bb75561e37930bb483d8cd53a42df30bf55f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 13 Apr 2004 14:31:49 +0000 Subject: eh, these can't be used for poll()! ;-) --- docs/libcurl/curl_multi_fdset.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index f2b3f9aed..01211b63f 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -14,9 +14,9 @@ CURLMcode curl_multi_fdset(CURLM *multi_handle, .ad .SH DESCRIPTION This function extracts file descriptor information from a given multi_handle. -libcurl returns its fd_set sets. The application can use these to select() or -poll() on. The curl_multi_perform() function should be called as soon as one -of them are ready to be read from or written to. +libcurl returns its fd_set sets. The application can use these to select() +on. The curl_multi_perform() function should be called as soon as one of them +are ready to be read from or written to. NOTE that once this call is made, you must not remove the sets you point to, as libcurl will need to be able to read them. It needs them after select() -- cgit v1.2.1 From 9c0a386246f2fc073419425a231c9a58cee77952 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 13 Apr 2004 14:34:12 +0000 Subject: minor format fix --- docs/libcurl/curl_multi_fdset.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 01211b63f..420323b99 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -4,6 +4,7 @@ .SH NAME curl_multi_fdset - extracts file descriptor information from a multi handle .SH SYNOPSIS +.nf #include CURLMcode curl_multi_fdset(CURLM *multi_handle, @@ -23,6 +24,6 @@ as libcurl will need to be able to read them. It needs them after select() calls, to know if certain sockets are readable or writable. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. See -\fIlibcurl-errors.3\fP +\fIlibcurl-errors(3)\fP .SH "SEE ALSO" .BR curl_multi_cleanup "(3)," curl_multi_init "(3)" -- cgit v1.2.1 From 220cd010bde555299fb3ad95df638e297bcc2a6f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 14 Apr 2004 12:13:21 +0000 Subject: format fix --- docs/libcurl/curl_multi_fdset.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 420323b99..2e9fd8fed 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -16,8 +16,8 @@ CURLMcode curl_multi_fdset(CURLM *multi_handle, .SH DESCRIPTION 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. The curl_multi_perform() function should be called as soon as one of them -are ready to be read from or written to. +on. The \fIcurl_multi_perform(3)\fI function should be called as soon as one +of them are ready to be read from or written to. NOTE that once this call is made, you must not remove the sets you point to, as libcurl will need to be able to read them. It needs them after select() -- cgit v1.2.1 From 5de447b0cb6736f64ca43ad441a35d605a231afc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 15 Apr 2004 15:05:12 +0000 Subject: clarified that select() timeouts should always remain rather short --- docs/libcurl/curl_multi_fdset.3 | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 2e9fd8fed..2faaad298 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_fdset 3 "3 May 2002" "libcurl 7.9.5" "libcurl Manual" +.TH curl_multi_fdset 3 "15 Apr 2004" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_fdset - extracts file descriptor information from a multi handle .SH SYNOPSIS @@ -22,6 +22,12 @@ of them are ready to be read from or written to. NOTE that once this call is made, you must not remove the sets you point to, as libcurl will need to be able to read them. It needs them after select() calls, to know if certain sockets are readable or writable. + +You should also be aware that when doing select(), you should consider using a +rather small (single-digit number of seconds) timeout and call +\fIcurl_multi_perform\fP regularly - even if no activity has been seen on the +fd_sets - as otherwise libcurl-internal retries and timeouts may not work as +you'd think. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP -- cgit v1.2.1 From 923ce98e42a2e8a338e4d626a934e7cd7678b4d5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Apr 2004 09:28:02 +0000 Subject: Kim Karlsson pointed out that error 57 was wrongly documented --- docs/libcurl/libcurl-errors.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 241d1ff64..037ef7c1f 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -168,8 +168,8 @@ Failed setting the selected SSL crypto engine as default! Failed sending network data. .IP "CURLE_RECV_ERROR (56)" Failure with receiving network data. -.IP "CURLE_RECV_ERROR (57)" -Failure with receiving network data. +.IP "CURLE_SHARE_IN_USE (57)" +Share is in use .IP "CURLE_SSL_CERTPROBLEM (58)" problem with the local certificate .IP "CURLE_SSL_CIPHER (59)" -- cgit v1.2.1 From 58f1cc0b5ff8fdf533f26898a778a747d37d8e8a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Apr 2004 07:05:40 +0000 Subject: added curl_*_strerror --- docs/libcurl/Makefile.am | 153 ++++++++++--------------------------- docs/libcurl/curl_easy_strerror.3 | 18 +++++ docs/libcurl/curl_multi_strerror.3 | 18 +++++ docs/libcurl/curl_share_strerror.3 | 18 +++++ docs/libcurl/index.html | 27 +++---- docs/libcurl/libcurl-errors.3 | 17 +++-- 6 files changed, 120 insertions(+), 131 deletions(-) create mode 100644 docs/libcurl/curl_easy_strerror.3 create mode 100644 docs/libcurl/curl_multi_strerror.3 create mode 100644 docs/libcurl/curl_share_strerror.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 14d1a49b4..0c85e82a0 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -4,119 +4,50 @@ AUTOMAKE_OPTIONS = foreign no-dependencies -man_MANS = \ - curl_easy_cleanup.3 \ - curl_easy_getinfo.3 \ - curl_easy_init.3 \ - curl_easy_perform.3 \ - curl_easy_setopt.3 \ - curl_easy_duphandle.3 \ - curl_formparse.3 \ - curl_formadd.3 \ - curl_formfree.3 \ - curl_getdate.3 \ - curl_getenv.3 \ - curl_slist_append.3 \ - curl_slist_free_all.3 \ - curl_version.3 \ - curl_version_info.3 \ - curl_escape.3 \ - curl_unescape.3 \ - curl_free.3 \ - curl_strequal.3 \ - curl_strnequal.3 \ - curl_mprintf.3 \ - curl_global_init.3 \ - curl_global_cleanup.3 \ - curl_multi_add_handle.3 \ - curl_multi_cleanup.3 \ - curl_multi_fdset.3 \ - curl_multi_info_read.3 \ - curl_multi_init.3 \ - curl_multi_perform.3 \ - curl_multi_remove_handle.3 \ - curl_share_cleanup.3 curl_share_init.3 curl_share_setopt.3 \ - libcurl.3 \ - libcurl-easy.3 \ - libcurl-multi.3 \ - libcurl-share.3 \ - libcurl-errors.3 +man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ + curl_easy_perform.3 curl_easy_setopt.3 curl_easy_duphandle.3 \ + curl_formparse.3 curl_formadd.3 curl_formfree.3 curl_getdate.3 \ + curl_getenv.3 curl_slist_append.3 curl_slist_free_all.3 \ + curl_version.3 curl_version_info.3 curl_escape.3 curl_unescape.3 \ + curl_free.3 curl_strequal.3 curl_mprintf.3 curl_global_init.3 \ + curl_global_cleanup.3 curl_multi_add_handle.3 curl_multi_cleanup.3 \ + curl_multi_fdset.3 curl_multi_info_read.3 curl_multi_init.3 \ + curl_multi_perform.3 curl_multi_remove_handle.3 curl_share_cleanup.3 \ + curl_share_init.3 curl_share_setopt.3 libcurl.3 libcurl-easy.3 \ + libcurl-multi.3 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3 \ + curl_multi_strerror.3 curl_share_strerror.3 -HTMLPAGES = \ - curl_easy_cleanup.html \ - curl_easy_getinfo.html \ - curl_easy_init.html \ - curl_easy_perform.html \ - curl_easy_setopt.html \ - curl_easy_duphandle.html \ - curl_formadd.html \ - curl_formparse.html \ - curl_formfree.html \ - curl_getdate.html \ - curl_getenv.html \ - curl_slist_append.html \ - curl_slist_free_all.html \ - curl_version.html \ - curl_version_info.html \ - curl_escape.html \ - curl_unescape.html \ - curl_free.html \ - curl_strequal.html \ - curl_strnequal.html \ - curl_mprintf.html \ - curl_global_init.html \ - curl_global_cleanup.html \ - curl_multi_add_handle.html \ - curl_multi_cleanup.html \ - curl_multi_fdset.html \ - curl_multi_info_read.html \ - curl_multi_init.html \ - curl_multi_perform.html \ - curl_multi_remove_handle.html \ - curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ - libcurl.html \ - libcurl-multi.html \ - libcurl-easy.html \ - libcurl-share.html \ - libcurl-errors.html +HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ + curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ + curl_easy_duphandle.html curl_formadd.html curl_formparse.html \ + curl_formfree.html curl_getdate.html curl_getenv.html \ + curl_slist_append.html curl_slist_free_all.html curl_version.html \ + curl_version_info.html curl_escape.html curl_unescape.html \ + curl_free.html curl_strequal.html curl_mprintf.html \ + curl_global_init.html curl_global_cleanup.html \ + curl_multi_add_handle.html curl_multi_cleanup.html \ + curl_multi_fdset.html curl_multi_info_read.html curl_multi_init.html \ + curl_multi_perform.html curl_multi_remove_handle.html \ + curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ + libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ + libcurl-errors.html curl_easy_strerror.3 curl_multi_strerror.3 \ + curl_share_strerror.3 -PDFPAGES = \ - curl_easy_cleanup.pdf \ - curl_easy_getinfo.pdf \ - curl_easy_init.pdf \ - curl_easy_perform.pdf \ - curl_easy_setopt.pdf \ - curl_easy_duphandle.pdf \ - curl_formadd.pdf \ - curl_formparse.pdf \ - curl_formfree.pdf \ - curl_getdate.pdf \ - curl_getenv.pdf \ - curl_slist_append.pdf \ - curl_slist_free_all.pdf \ - curl_version.pdf \ - curl_version_info.pdf \ - curl_escape.pdf \ - curl_unescape.pdf \ - curl_free.pdf \ - curl_strequal.pdf \ - curl_strnequal.pdf \ - curl_mprintf.pdf \ - curl_global_init.pdf \ - curl_global_cleanup.pdf \ - curl_multi_add_handle.pdf \ - curl_multi_cleanup.pdf \ - curl_multi_fdset.pdf \ - curl_multi_info_read.pdf \ - curl_multi_init.pdf \ - curl_multi_perform.pdf \ - curl_multi_remove_handle.pdf \ - curl_share_cleanup.pdf curl_share_init.pdf curl_share_setopt.pdf \ - libcurl.pdf \ - libcurl-multi.pdf \ - libcurl-easy.pdf \ - libcurl-share.pdf \ - libcurl-errors.pdf +PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ + curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ + curl_easy_duphandle.pdf curl_formadd.pdf curl_formparse.pdf \ + curl_formfree.pdf curl_getdate.pdf curl_getenv.pdf \ + curl_slist_append.pdf curl_slist_free_all.pdf curl_version.pdf \ + curl_version_info.pdf curl_escape.pdf curl_unescape.pdf curl_free.pdf \ + curl_strequal.pdf curl_mprintf.pdf curl_global_init.pdf \ + curl_global_cleanup.pdf curl_multi_add_handle.pdf \ + curl_multi_cleanup.pdf curl_multi_fdset.pdf curl_multi_info_read.pdf \ + curl_multi_init.pdf curl_multi_perform.pdf \ + curl_multi_remove_handle.pdf curl_share_cleanup.pdf \ + curl_share_init.pdf curl_share_setopt.pdf libcurl.pdf \ + libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ + libcurl-errors.pdf curl_easy_strerror.3 curl_multi_strerror.3 \ + curl_share_strerror.3 CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 new file mode 100644 index 000000000..eb7cecc4c --- /dev/null +++ b/docs/libcurl/curl_easy_strerror.3 @@ -0,0 +1,18 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_easy_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" +.SH NAME +curl_easy_strerror - return string describing error code +.SH SYNOPSIS +.nf +.B #include +.BI "const char *curl_easy_strerror(CURLcode " errornum ");" +.SH DESCRIPTION +The curl_easy_strerror() function returns a string describing the CURLcode +error code passed in the argument \fIerrornum\fP. +.SH RETURN VALUE +A pointer to a zero terminated string. +.SH "SEE ALSO" +.BR libcurl-errors "(3), " curl_multi_strerror "(3), " curl_share_strerror "(3)" diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 new file mode 100644 index 000000000..f2fea3b92 --- /dev/null +++ b/docs/libcurl/curl_multi_strerror.3 @@ -0,0 +1,18 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_multi_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" +.SH NAME +curl_multi_strerror - return string describing error code +.SH SYNOPSIS +.nf +.B #include +.BI "const char *curl_multi_strerror(CURLMcode " errornum ");" +.SH DESCRIPTION +The curl_multi_strerror() function returns a string describing the CURLMcode +error code passed in the argument \fIerrornum\fP. +.SH RETURN VALUE +A pointer to a zero terminated string. +.SH "SEE ALSO" +.BR libcurl-errors "(3), " curl_easy_strerror "(3), " curl_share_strerror "(3)" diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 new file mode 100644 index 000000000..35fa4db8c --- /dev/null +++ b/docs/libcurl/curl_share_strerror.3 @@ -0,0 +1,18 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_share_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" +.SH NAME +curl_share_strerror - return string describing error code +.SH SYNOPSIS +.nf +.B #include +.BI "const char *curl_share_strerror(CURLSHcode " errornum ");" +.SH DESCRIPTION +The curl_share_strerror() function returns a string describing the CURLSHcode +error code passed in the argument \fIerrornum\fP. +.SH RETURN VALUE +A pointer to a zero terminated string. +.SH "SEE ALSO" +.BR libcurl-errors "(3), " curl_multi_strerror "(3), " curl_easy_strerror "(3)" diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 997e6cea1..817ffe6dd 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -1,14 +1,14 @@ - - - -Index to libcurl documentation - + + + +Index to libcurl documentation + - -

Index to libcurl documentation

+ +

Index to libcurl documentation

-

Programs

-

curl and tools +

Programs

+

curl and tools

Overviews

libcurl @@ -25,6 +25,7 @@
curl_easy_init
curl_easy_perform
curl_easy_setopt +
curl_easy_strerror
curl_escape
curl_formadd
curl_formfree @@ -42,16 +43,16 @@
curl_multi_init
curl_multi_perform
curl_multi_remove_handle +
curl_multi_strerror.html
curl_share_cleanup
curl_share_init
curl_share_setopt +
curl_share_strerror.html
curl_slist_append
curl_slist_free_all -
curl_strequal -
curl_strnequal +
curl_strequal and curl_strnequal
curl_unescape
curl_version
curl_version_info - - + diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 037ef7c1f..e0699645f 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl-errors 3 "8 Mar 2004" "libcurl 7.11.0" "libcurl errors" +.TH libcurl-errors 3 "27 Apr 2004" "libcurl 7.12" "libcurl errors" .SH NAME libcurl-errors \- error codes in libcurl .SH DESCRIPTION @@ -10,9 +10,11 @@ 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. .SH "CURLcode" Almost all "easy" interface functions return a CURLcode error code. No matter -what, using \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. +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 +given CURLcode number. CURLcode is one of the following: .IP "CURLE_OK (0)" @@ -186,7 +188,8 @@ Maximum file size exceeded Requested FTP SSL level failed .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi -interface. +interface. Also consider \fIcurl_multi_strerror(3)\fI. + .IP "CURLM_CALL_MULTI_PERFORM (-1)" This is not really an error. It means you should call \fIcurl_multi_perform(3)\fP again without doing select() or similar in between. @@ -201,8 +204,8 @@ You are doomed. .IP "CURLM_INTERNAL_ERROR (4)" This can only be returned if libcurl bugs. Please report it to us! .SH "CURLSHcode" -The "share" interface will return a CURLSHcode to indicate when an -error has occurred. +The "share" interface will return a CURLSHcode to indicate when an error has +occurred. Also consider \fIcurl_share_strerror(3)\fI. CURLSHcode is one of the following: .IP "CURLSHE_OK (0)" -- cgit v1.2.1 From 38cc79a54ff11e96e527666137fc9eb77db96c60 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 30 Apr 2004 08:38:08 +0000 Subject: these functions are marked to get removed from the public API "soon" --- docs/libcurl/curl_getenv.3 | 8 +++++--- docs/libcurl/curl_mprintf.3 | 8 +++++--- docs/libcurl/curl_strequal.3 | 8 +++++--- 3 files changed, 15 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index 5cfd3a496..fab2e5e73 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -1,8 +1,6 @@ -.\" You can view this file with: -.\" nroff -man [file] .\" $Id$ .\" -.TH curl_getenv 3 "15 August 2001" "libcurl 7.8.1" "libcurl Manual" +.TH curl_getenv 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_getenv - return value for environment name .SH SYNOPSIS @@ -14,6 +12,10 @@ curl_getenv - return value for environment name curl_getenv() is a portable wrapper for the getenv() function, meant to emulate its behaviour and provide an identical interface for all operating systems libcurl builds on (including win32). +.SH AVAILABILITY +This function will be removed from the public libcurl API in a near future. It +will instead be made "available" by source code access only, and then as +curlx_getenv(). .SH RETURN VALUE If successful, curl_getenv() returns a pointer to the value of the specified environment. The memory it refers to is malloc()ed why the application must diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index 68621ff0b..c7c7d598c 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -1,8 +1,6 @@ -.\" You can view this file with: -.\" nroff -man [file] .\" $Id$ .\" -.TH curl_printf 3 "20 April 2001" "libcurl 7.7.2" "libcurl Manual" +.TH curl_printf 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf, @@ -79,6 +77,10 @@ To easily use all these cloned functions instead of the normal ones, #define _MPRINTF_REPLACE before you include the file. Then all the normal names like printf, fprintf, sprintf etc will use the curl-functions instead. +.SH AVAILABILITY +These function will be removed from the public libcurl API in a near +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. diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index a35a52dfd..2b99467f1 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -1,8 +1,6 @@ -.\" You can view this file with: -.\" nroff -man [file] .\" $Id$ .\" -.TH curl_strequal 3 "20 April 2001" "libcurl 7.7.2" "libcurl Manual" +.TH curl_strequal 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_strequal, curl_strnequal - case insensitive string comparisons .SH SYNOPSIS @@ -24,6 +22,10 @@ first \fIlen\fP characters of \fIstr1\fP. 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. +.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 +then as curlx_strequal() and curlx_strenqual(). .SH RETURN VALUE Non-zero if the strings are identical. Zero if they're not. .SH "SEE ALSO" -- cgit v1.2.1 From e3bc92ae53a765e60a39cbdf2d7bdb68c30f7a0b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 3 May 2004 14:40:22 +0000 Subject: fixed the pdf and html for the strerror functions --- docs/libcurl/Makefile.am | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 0c85e82a0..dc2f6a85d 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -30,8 +30,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_multi_perform.html curl_multi_remove_handle.html \ curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ - libcurl-errors.html curl_easy_strerror.3 curl_multi_strerror.3 \ - curl_share_strerror.3 + libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ + curl_share_strerror.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ @@ -46,8 +46,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_multi_remove_handle.pdf curl_share_cleanup.pdf \ curl_share_init.pdf curl_share_setopt.pdf libcurl.pdf \ libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ - libcurl-errors.pdf curl_easy_strerror.3 curl_multi_strerror.3 \ - curl_share_strerror.3 + libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ + curl_share_strerror.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -- cgit v1.2.1 From 2960d37d7172976dff3eb8953fb4ca5f17b4bc47 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 May 2004 08:24:13 +0000 Subject: removed curl_formparse() from the library --- docs/libcurl/Makefile.am | 38 ++++++++++++++++++-------------------- docs/libcurl/curl_formparse.3 | 18 ------------------ docs/libcurl/index.html | 1 - 3 files changed, 18 insertions(+), 39 deletions(-) delete mode 100644 docs/libcurl/curl_formparse.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index dc2f6a85d..eff5e51d9 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -6,10 +6,10 @@ AUTOMAKE_OPTIONS = foreign no-dependencies man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_easy_perform.3 curl_easy_setopt.3 curl_easy_duphandle.3 \ - curl_formparse.3 curl_formadd.3 curl_formfree.3 curl_getdate.3 \ - curl_getenv.3 curl_slist_append.3 curl_slist_free_all.3 \ - curl_version.3 curl_version_info.3 curl_escape.3 curl_unescape.3 \ - curl_free.3 curl_strequal.3 curl_mprintf.3 curl_global_init.3 \ + curl_formadd.3 curl_formfree.3 curl_getdate.3 curl_getenv.3 \ + curl_slist_append.3 curl_slist_free_all.3 curl_version.3 \ + curl_version_info.3 curl_escape.3 curl_unescape.3 curl_free.3 \ + curl_strequal.3 curl_mprintf.3 curl_global_init.3 \ curl_global_cleanup.3 curl_multi_add_handle.3 curl_multi_cleanup.3 \ curl_multi_fdset.3 curl_multi_info_read.3 curl_multi_init.3 \ curl_multi_perform.3 curl_multi_remove_handle.3 curl_share_cleanup.3 \ @@ -19,34 +19,32 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ - curl_easy_duphandle.html curl_formadd.html curl_formparse.html \ - curl_formfree.html curl_getdate.html curl_getenv.html \ - curl_slist_append.html curl_slist_free_all.html curl_version.html \ - curl_version_info.html curl_escape.html curl_unescape.html \ - curl_free.html curl_strequal.html curl_mprintf.html \ - curl_global_init.html curl_global_cleanup.html \ + curl_easy_duphandle.html curl_formadd.html curl_formfree.html \ + curl_getdate.html curl_getenv.html curl_slist_append.html \ + curl_slist_free_all.html curl_version.html curl_version_info.html \ + curl_escape.html curl_unescape.html curl_free.html curl_strequal.html \ + curl_mprintf.html curl_global_init.html curl_global_cleanup.html \ curl_multi_add_handle.html curl_multi_cleanup.html \ curl_multi_fdset.html curl_multi_info_read.html curl_multi_init.html \ curl_multi_perform.html curl_multi_remove_handle.html \ curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ - libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ + libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ curl_share_strerror.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ - curl_easy_duphandle.pdf curl_formadd.pdf curl_formparse.pdf \ - curl_formfree.pdf curl_getdate.pdf curl_getenv.pdf \ - curl_slist_append.pdf curl_slist_free_all.pdf curl_version.pdf \ - curl_version_info.pdf curl_escape.pdf curl_unescape.pdf curl_free.pdf \ - curl_strequal.pdf curl_mprintf.pdf curl_global_init.pdf \ - curl_global_cleanup.pdf curl_multi_add_handle.pdf \ - curl_multi_cleanup.pdf curl_multi_fdset.pdf curl_multi_info_read.pdf \ - curl_multi_init.pdf curl_multi_perform.pdf \ + curl_easy_duphandle.pdf curl_formadd.pdf curl_formfree.pdf \ + curl_getdate.pdf curl_getenv.pdf curl_slist_append.pdf \ + curl_slist_free_all.pdf curl_version.pdf curl_version_info.pdf \ + curl_escape.pdf curl_unescape.pdf curl_free.pdf curl_strequal.pdf \ + curl_mprintf.pdf curl_global_init.pdf curl_global_cleanup.pdf \ + curl_multi_add_handle.pdf curl_multi_cleanup.pdf curl_multi_fdset.pdf \ + curl_multi_info_read.pdf curl_multi_init.pdf curl_multi_perform.pdf \ curl_multi_remove_handle.pdf curl_share_cleanup.pdf \ curl_share_init.pdf curl_share_setopt.pdf libcurl.pdf \ libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ - libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ + libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ curl_share_strerror.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_formparse.3 b/docs/libcurl/curl_formparse.3 deleted file mode 100644 index bc7accba3..000000000 --- a/docs/libcurl/curl_formparse.3 +++ /dev/null @@ -1,18 +0,0 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ -.\" -.TH curl_formparse 3 "17 Dec 2001" "libcurl 7.9.2" "libcurl Manual" -.SH NAME -curl_formparse - add a section to a multipart/formdata HTTP POST: -deprecated (use curl_formadd instead) -.SH SYNOPSIS -.B #include -.sp -.BI "CURLcode curl_formparse(char * " string, " struct HttpPost ** " firstitem, -.BI "struct HttpPost ** " lastitem ");" -.ad -.SH DESCRIPTION -This has been removed deliberately. The \fBcurl_formadd\fP has been introduced -to replace this function. Do not use this. Convert to the new function -now. curl_formparse() will be removed from a future version of libcurl. diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 817ffe6dd..6d4f133c2 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -29,7 +29,6 @@
curl_escape
curl_formadd
curl_formfree -
curl_formparse
curl_free
curl_getdate
curl_getenv -- cgit v1.2.1 From 7332350e852f9b4334711e858b71b6697490e3ec Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 5 May 2004 06:11:57 +0000 Subject: minor update edits --- docs/libcurl/libcurl-easy.3 | 5 ++--- docs/libcurl/libcurl.3 | 47 ++++++++++++++++----------------------------- 2 files changed, 19 insertions(+), 33 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 index 2fe4c82e5..5280bf6ff 100644 --- a/docs/libcurl/libcurl-easy.3 +++ b/docs/libcurl/libcurl-easy.3 @@ -7,9 +7,8 @@ libcurl-easy \- easy interface overview .SH DESCRIPTION When using libcurl's "easy" interface you init your session and get a handle -(often referred to as an "easy handle" in various docs and sources), which you -use as input to the easy interface functions you use. Use -\fIcurl_easy_init(3)\fP to get the handle. +(often referred to as an "easy handle"), which you use as input to the easy +interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle. You continue by setting all the options you want in the upcoming transfer, the most important among them is the URL itself (you can't transfer anything diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 632bcdf61..742511e18 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -33,45 +33,28 @@ The multi interface on the other hand is an asynchronous interface, that you call and that performs only a little piece of the transfer on each invoke. It is perfect if you want to do things while the transfer is in progress, or similar. The multi interface allows you to select() on libcurl action, and -even to easily download multiple files simultaneously using a single thread. +even to easily download multiple files simultaneously using a single thread. See further deails in the \fIlibcurl-multi(3)\fP man page. You can have multiple easy handles share certain data, even if they are used in different threads. This magic is setup using the share interface, as described in the \fIlibcurl-share(3)\fP man page. -There is also a series of other helpful functions to use. They are: - +There is also a series of other helpful functions to use, including these: .RS -.TP 10 -.B curl_version() -displays the libcurl version -.TP -.B curl_getdate() +.IP curl_version_info() +gets detailed libcurl (and other used libraries) version info +.IP curl_getdate() converts a date string to time_t -.TP -.B curl_getenv() -portable environment variable reader -.TP -.B curl_easy_getinfo() +.IP curl_easy_getinfo() get information about a performed transfer -.TP -.B curl_formadd() +.IP curl_formadd() helps building an HTTP form POST -.TP -.B curl_formfree() +.IP curl_formfree() free a list built with \fIcurl_formadd(3)\fP -.TP -.B curl_slist_append() +.IP curl_slist_append() builds a linked list -.TP -.B curl_slist_free_all() +.IP curl_slist_free_all() frees a whole curl_slist -.TP -.B curl_mprintf() -portable printf() functions -.TP -.B curl_strequal() -portable case insensitive string comparisons .RE .SH "LINKING WITH LIBCURL" @@ -82,13 +65,17 @@ curl-config is added to make it easier for applications to link with libcurl and developers to learn about libcurl and how to use it. Run 'curl-config --libs' to get the (additional) linker options you need to -link with the particular version of libcurl you've installed. +link with the particular version of libcurl you've installed. See the +\fIcurl-config(1)\fP man page for further details. + +Unix-like operating system that ship libcurl as part of their distributions +often don't provide the curl-config tool, but simply install the library and +headers in the common path for this purpose. -For details, see the curl-config.1 man page. .SH "LIBCURL SYMBOL NAMES" All public functions in the libcurl interface are prefixed with 'curl_' (with a lowercase c). You can find other functions in the library source code, but -other prefixes indicate the functions are private and may change without +other prefixes indicate that the functions are private and may change without further notice in the next release. Only use documented functions and functionality! -- cgit v1.2.1 From bbafb2eb27954c34967f91c705e74cc0c186970d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 11 May 2004 11:30:23 +0000 Subject: curl_global_init_mem() allows the memory functions to be replaced. memory.h is included everywhere for this. --- docs/libcurl/Makefile.am | 6 +++--- docs/libcurl/curl_global_init.3 | 5 ++--- 2 files changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index eff5e51d9..81ef28f86 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -15,7 +15,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_multi_perform.3 curl_multi_remove_handle.3 curl_share_cleanup.3 \ curl_share_init.3 curl_share_setopt.3 libcurl.3 libcurl-easy.3 \ libcurl-multi.3 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3 \ - curl_multi_strerror.3 curl_share_strerror.3 + curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -30,7 +30,7 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ - curl_share_strerror.html + curl_share_strerror.html curl_global_init_mem.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ @@ -45,7 +45,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_share_init.pdf curl_share_setopt.pdf libcurl.pdf \ libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ - curl_share_strerror.pdf + curl_share_strerror.pdf curl_global_init_mem.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index 04a0b0238..b408850ad 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_global_init 3 "13 Nov 2001" "libcurl 7.9.1" "libcurl Manual" +.TH curl_global_init 3 "11 May 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_global_init - Global libcurl initialisation .SH SYNOPSIS @@ -42,6 +42,5 @@ Initialise nothing extra. This sets no bit. If this function returns non-zero, something went wrong and you cannot use the other curl functions. .SH "SEE ALSO" +.BR curl_global_init_mem "(3), " .BR curl_global_cleanup "(3), " - - -- cgit v1.2.1 From c8807438cef0f2cd17cb5a176c41773239842421 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 11 May 2004 14:15:49 +0000 Subject: updated to reflect reality! --- docs/libcurl/curl_version_info.3 | 61 ++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 27 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index abe082eb1..95b99af2e 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_version_info 3 "19 Sep 2003" "libcurl 7.10.8" "libcurl Manual" +.TH curl_version_info 3 "11 May 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -28,22 +28,32 @@ The curl_version_info_data struct looks like this .nf typedef struct { - CURLversion age; /* 0 - this kind of struct */ + CURLversion age; /* see description below */ + + /* when 'age' is 0 or higher, the members below also exist: */ const char *version; /* human readable string */ unsigned int version_num; /* numeric representation */ const char *host; /* human readable string */ int features; /* bitmask, see below */ char *ssl_version; /* human readable string */ long ssl_version_num; /* number */ - char *libz_version; /* human readable string */ - const char *protocols[]; /* list of protocols */ + const char *libz_version; /* human readable string */ + const char **protocols; /* list of protocols */ + + /* when 'age' is 1 or higher, the members below also exist: */ + const char *ares; /* human readable string */ + int ares_num; /* number */ + + /* when 'age' is 2 or higher, the member below also exists: */ + const char *libidn; /* human readable string */ + } curl_version_info_data; .fi -\fIage\fP describes what kind of struct this is. It is always 0 now. In a -future libcurl, if this struct changes, this age counter may be increased, and -then the struct for number 1 will look different (except for this first struct -field). +\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 +have a matching struct for in the header, as you tell libcurl your "age" with +the input argument. \fIversion\fP is just an ascii string for the libcurl version. @@ -57,38 +67,35 @@ environment. \fIfeatures\fP can have none, one or more bits set, and the currently defined bits are: -.TP 5.5 -.B CURL_VERSION_IPV6 +.RS +.IP CURL_VERSION_IPV6 supports IPv6 -.TP -.B CURL_VERSION_KERBEROS4 +.IP CURL_VERSION_KERBEROS4 supports kerberos4 (when using FTP) -.TP -.B CURL_VERSION_SSL +.IP CURL_VERSION_SSL supports SSL (HTTPS/FTPS) -.TP -.B CURL_VERSION_LIBZ +.IP CURL_VERSION_LIBZ supports HTTP deflate using libz -.TP -.B CURL_VERSION_NTLM +.IP CURL_VERSION_NTLM supports HTTP NTLM (added in 7.10.6) -.TP -.B CURL_VERSION_GSSNEGOTIATE +.IP CURL_VERSION_GSSNEGOTIATE supports HTTP GSS-Negotiate (added in 7.10.6) -.TP -.B CURL_VERSION_DEBUG +.IP CURL_VERSION_DEBUG libcurl was built with extra debug capabilities built-in. This is mainly of interest for libcurl hackers. (added in 7.10.6) -.TP -.B CURL_VERSION_ASYNCHDNS +.IP CURL_VERSION_ASYNCHDNS libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi interface. (added in 7.10.7) -.TP -.B CURL_VERSION_SPNEGO +.IP CURL_VERSION_SPNEGO libcurl was built with support for SPNEGO authentication (Simple and Protected GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) -.PP +.IP CURL_VERSION_LARGEFILE +libcurl was built with support for large files. +.IP CURL_VERSION_IDN +libcurl was built with support for IDNA, domain names with international +letters. +.RE \fIssl_version\fP is an ascii string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. -- cgit v1.2.1 From 91025d1dd65dc4037dfd75accf20116d3a84c7bd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 12 May 2004 08:10:25 +0000 Subject: new man page --- docs/libcurl/curl_global_init_mem.3 | 42 +++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/libcurl/curl_global_init_mem.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_global_init_mem.3 b/docs/libcurl/curl_global_init_mem.3 new file mode 100644 index 000000000..57ae6aeea --- /dev/null +++ b/docs/libcurl/curl_global_init_mem.3 @@ -0,0 +1,42 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" +.TH curl_global_init_mem 3 "10 May 2004" "libcurl 7.12.0" "libcurl Manual" +.SH NAME +curl_global_init_mem - Global libcurl initialisation with memory callbacks +.SH SYNOPSIS +.B #include +.nf +.B "CURLcode curl_global_init_mem(long " flags, +.B " curl_malloc_callback "m, +.B " curl_free_callback "f, +.B " curl_realloc_callback "r, +.B " curl_strdup_callback "s, +.B " curl_calloc_callback "c ");" +.SH DESCRIPTION +This function works exactly as \fIcurl_global_init(3)\fP with one addition: it +allows the application to set callbacks to replace the otherwise used internal +memory functions. + +This man page only adds documentation for the callbacks, see the +\fIcurl_global_init(3)\fP man page for all the rest. When you use this +function, all callback arguments must be set to valid function pointers. + +The prototypes for the given callbacks should match these: +.IP "void *malloc_callback(size_t size);" +To replace malloc() +.IP "void free_callback(void *ptr);" +To replace free() +.IP "void *realloc_callback(void *ptr, size_t size);" +To replace realloc() +.IP "char *strdup_callback(const char *str);" +To replace strdup() +.IP "void *calloc_callback(size_t nmemb, size_t size);" +To replace calloc() +.SH "CAUTION" +Manipulating these gives considerable powers to the application to severly +screw things up for libcurl. Take care! +.SH "SEE ALSO" +.BR curl_global_init "(3), " +.BR curl_global_cleanup "(3), " + -- cgit v1.2.1 From 23a43c6e0fdd9c5ff8634e788bc502108fb535aa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 17 May 2004 07:12:32 +0000 Subject: Seshubabu Pasam's format fixes and added notes about DER not working for some (SSL-)options. --- docs/libcurl/curl_easy_setopt.3 | 43 +++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 21 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index eeb35d41e..8816a2ddd 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -310,7 +310,7 @@ amortizes the overhead of the send. However, in some cases (most notably telnet or rlogin) small segments may need to be sent without delay. This is less efficient than sending larger amounts of data at a time, and can contribute to congestion on the network if -overdone. +overdone. .SH NAMES and PASSWORDS OPTIONS (Authentication) .IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and @@ -340,7 +340,7 @@ 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. .RE -Only machine name, user name and password are taken into account +Only machine name, user name and password are taken into account (init macros and similar things aren't supported). \fBNote:\fP libcurl does not verify that the file has the correct properties @@ -522,7 +522,7 @@ The first line in a request (usually containing a GET or POST) is not a header and cannot be replaced using this option. Only the lines following the request-line are headers. -\fBNOTE:\fPThe most commonly replaced headers have "shortcuts" in the options +\fBNOTE:\fP The most commonly replaced headers have "shortcuts" in the options \fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP. .IP CURLOPT_HTTP200ALIASES Pass a pointer to a linked list of aliases to be treated as valid HTTP 200 @@ -535,7 +535,7 @@ The linked list should be a fully valid list of struct curl_slist structs, and be 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. -\fBNOTE:\fPThe alias itself is not parsed for any version strings. So if your +\fBNOTE:\fP The alias itself is not parsed for any version strings. So if your alias is "MYHTTP/9.9", Libcurl will not treat the server as responding with HTTP version 9.9. Instead Libcurl will use the value set by option \fICURLOPT_HTTP_VERSION\fP. @@ -706,11 +706,11 @@ when doing an 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. -NOTE: many people have wrongly used this option to replace the entire request -with their own, including multiple headers and POST contents. While that might -work in many cases, it will cause libcurl to send invalid requests and it -could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and -\fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to +\fBNOTE:\fP Many people have wrongly used this option to replace the entire +request with their own, including multiple headers and POST contents. While +that might work in many cases, it will cause libcurl to send invalid requests +and it could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP +and \fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to replace or extend the set of headers sent by libcurl. Use \fICURLOPT_HTTP_VERSION\fP to change HTTP version. .IP CURLOPT_FILETIME @@ -740,29 +740,29 @@ Pass a long as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. -NOTE: The file size is not always known prior to download, and for such files -this option has no effect even if the file transfer ends up being larger than -this given limit. This concerns both FTP and HTTP transfers. +\fBNOTE:\fP The file size is not always known prior to download, and for such +files this option has no effect even if the file transfer ends up being larger +than this given limit. This concerns both FTP and HTTP transfers. .IP CURLOPT_MAXFILESIZE_LARGE Pass a curl_off_t as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will be returned. (Added in 7.11.0) -NOTE: The file size is not always known prior to download, and for such files -this option has no effect even if the file transfer ends up being larger than -this given limit. This concerns both FTP and HTTP transfers. +\fBNOTE:\fP The file size is not always known prior to download, and for such +files this option has no effect even if the file transfer ends up being larger +than this given limit. This concerns both FTP and HTTP transfers. .IP CURLOPT_TIMECONDITION Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time 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. -NOTE: The last modification time of a file is not always known and in such +\fBNOTE:\fP 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. .IP CURLOPT_TIMEVALUE 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 +and the time will be used in a condition as specified with \fICURLOPT_TIMECONDITION\fP. .SH CONNECTION OPTIONS .IP CURLOPT_TIMEOUT @@ -866,9 +866,10 @@ changed with \fICURLOPT_SSLKEYTYPE\fP. Pass a pointer to a zero terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG". -\fBNOTE:\fPThe format "ENG" enables you to load the private key from a crypto -engine. in this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to +\fBNOTE:\fP The format "ENG" enables you to load the private key from a crypto +engine. In this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to the engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE\fP. +\&"DER" format key file currently does not work because of a bug in OpenSSL. .IP CURLOPT_SSLKEYPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as the password required to use the \fICURLOPT_SSLKEY\fP private key. @@ -877,13 +878,13 @@ Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private key. -\fBNOTE:\fPIf the crypto device cannot be loaded, +\fBNOTE:\fP If the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. .IP CURLOPT_SSLENGINE_DEFAULT Sets the actual crypto engine as the default for (asymmetric) crypto operations. -\fBNOTE:\fPIf the crypto device cannot be set, +\fBNOTE:\fP If the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is returned. .IP CURLOPT_SSLVERSION Pass a long as parameter. Set what version of SSL to attempt to use, 2 or -- cgit v1.2.1 From 8bbf9b13af9825fcb7b73b48e6e26088833a1105 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 1 Jun 2004 08:33:15 +0000 Subject: Renaud Duhaut corrected the unescaping procedure --- docs/libcurl/curl_unescape.3 | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index ccde26e44..1d2b059fc 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -13,9 +13,8 @@ curl_unescape - URL decodes the given string .SH DESCRIPTION This function will convert the given URL encoded input string to a "plain string" and return that as a new allocated string. All input characters that -are URL encoded (%XX where XX is a two-digit hexadecimal number, or +) will be -converted to their plain text versions (up to a ? letter, no + letters to the -right of a ? letter will be converted). +are URL encoded (%XX where XX is a two-digit hexadecimal number) will be +converted to their plain text versions. If the 'length' argument is set to 0, curl_unescape() will use strlen() on the input 'url' string to find out the size. -- cgit v1.2.1 From 0078944486c5caa86e348168eebc8614c510d84d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 2 Jun 2004 14:06:49 +0000 Subject: CURLOPT_PUT is deprecated --- docs/libcurl/curl_easy_setopt.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8816a2ddd..e486a0032 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -456,6 +456,9 @@ redirections have been followed, the next redirect will cause an error .IP CURLOPT_PUT A non-zero parameter tells the library to use HTTP PUT to transfer data. The data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP. + +This option is deprecated and starting with version 7.12.1 you should instead +use \fICURLOPT_UPLOAD\fP. .IP CURLOPT_POST A non-zero parameter tells the library to do a regular HTTP post. This is a normal application/x-www-form-urlencoded kind, which is the most commonly used @@ -734,7 +737,8 @@ as a curl_off_t. (Added in 7.11.0) .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE_LARGE\fP are also interesting -for uploads. +for uploads. If the protocol is HTTP, uploading means using the PUT request +unless you tell libcurl otherwise. .IP CURLOPT_MAXFILESIZE Pass a long as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, -- cgit v1.2.1 From aa0e32060e59f8df3241cf8ab9a78c6994dc9175 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 3 Jun 2004 11:19:35 +0000 Subject: CURLE_FAILED_INIT is returend when an unknown option is set --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e486a0032..095c1d7b5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -964,5 +964,9 @@ standard for details. CURLE_OK (zero) means that the option was set properly, non-zero means an error occurred as \fI\fP defines. See the \fIlibcurl-errors(3)\fP man page for the full list with descriptions. + +If you try to set an option that libcurl doesn't know about, perhaps because +the library is too old to support it or the option was removed in a recent +version, this function will return \fICURLE_FAILED_INIT\fP. .SH "SEE ALSO" .BR curl_easy_init "(3), " curl_easy_cleanup "(3), " -- cgit v1.2.1 From b3caf7bfa85462b8b3653fc70e732f6b16cc2a38 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 9 Jun 2004 08:05:23 +0000 Subject: Setting CURLOPT_RANGE to NULL disables it. Setting CURLOPT_RESUME_FROM to 0 prevents a resumed transfer. --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 095c1d7b5..94b5626d0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -695,10 +695,11 @@ want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in \fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation -techniques). +techniques). Pass a NULL to this option to disable the use of ranges. .IP CURLOPT_RESUME_FROM Pass a long as parameter. It contains the offset in number of bytes that you -want the transfer to start from. +want the transfer to start from. Set this option to 0 to make the transfer +start from the beginning (effectively disabling resume). .IP CURLOPT_RESUME_FROM_LARGE Pass an curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) -- cgit v1.2.1 From 9733cd59bb41a2022d54aa14be4a40c1dc290018 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 9 Jun 2004 08:18:17 +0000 Subject: removed reference to the removed curl_formparse --- docs/libcurl/curl_formadd.3 | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 95671e7f9..961bfbf26 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -205,5 +205,4 @@ defines. .SH "SEE ALSO" .BR curl_easy_setopt "(3), " -.BR curl_formparse "(3) [deprecated], " .BR curl_formfree "(3)" -- cgit v1.2.1 From 1e99f1ee41cbad7c300e655ba72dc918035ffbfd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 21 Jun 2004 08:17:08 +0000 Subject: libcurl-tutorial.3 is the former libcurl-the-guide converted to man page format --- docs/libcurl/Makefile.am | 8 +- docs/libcurl/libcurl-tutorial.3 | 1171 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 1176 insertions(+), 3 deletions(-) create mode 100644 docs/libcurl/libcurl-tutorial.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 81ef28f86..27f8d7816 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -15,7 +15,8 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_multi_perform.3 curl_multi_remove_handle.3 curl_share_cleanup.3 \ curl_share_init.3 curl_share_setopt.3 libcurl.3 libcurl-easy.3 \ libcurl-multi.3 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3 \ - curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 + curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ + libcurl-tutorial.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -30,7 +31,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ - curl_share_strerror.html curl_global_init_mem.html + curl_share_strerror.html curl_global_init_mem.html \ + libcurl-tutorial.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ @@ -45,7 +47,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_share_init.pdf curl_share_setopt.pdf libcurl.pdf \ libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ - curl_share_strerror.pdf curl_global_init_mem.pdf + curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 new file mode 100644 index 000000000..f1716b692 --- /dev/null +++ b/docs/libcurl/libcurl-tutorial.3 @@ -0,0 +1,1171 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2004, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** +.\" +.TH libcurl-tutorial 3 "18 Jun 2004" "libcurl" "libcurl programming" +.SH NAME +libcurl-tutorial \- libcurl programming tutorial +.SH "Objective" +This document attempts to describe the general principles and some basic +approaches to consider when programming with libcurl. The text will focus +mainly on the C interface but might apply fairly well on other interfaces as +well as they usually follow the C one pretty closely. + +This document will refer to 'the user' as the person writing the source code +that uses libcurl. That would probably be you or someone in your position. +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 +refer to their respective man pages. + +.SH "Building" +There are many different ways to build C programs. This chapter will assume a +unix-style build process. If you use a different build system, you can still +read this to get general information that may apply to your environment as +well. +.IP "Compiling the Program" +Your compiler needs to know where the libcurl headers are located. Therefore +you must set your compiler's include path to point to the directory where you +installed them. The 'curl-config'[3] tool can be used to get this information: + +$ curl-config --cflags + +.IP "Linking the Program with libcurl" +When having compiled the program, you need to link your object files to create +a single executable. For that to succeed, you need to link with libcurl and +possibly also with other libraries that libcurl itself depends on. Like the +OpenSSL libraries, but even some standard OS libraries may be needed on the +command line. To figure out which flags to use, once again the 'curl-config' +tool comes to the rescue: + +$ curl-config --libs + +.IP "SSL or Not" +libcurl can be built and customized in many ways. One of the things that +varies from different libraries and builds is the support for SSL-based +transfers, like HTTPS and FTPS. If OpenSSL was detected properly at +build-time, libcurl will be built with SSL support. To figure out if an +installed libcurl has been built with SSL support enabled, use 'curl-config' +like this: + +$ 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. + +See also the "Features libcurl Provides" further down. + +.SH "Portable Code in a Portable World" +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 +write your code portable enough, you may very well create yourself a very +portable program. libcurl shouldn't stop you from that. + +.SH "Global Preparation" +The program must initialize some of the libcurl functionality globally. That +means it should be done exactly once, no matter how many times you intend to +use the library. Once for your program's entire life time. This is done using + + curl_global_init() + +and it takes one parameter which is a bit pattern that tells libcurl what to +initialize. Using CURL_GLOBAL_ALL will make it initialize all known internal +sub modules, and might be a good default option. The current two bits that +are specified are: +.RS +.IP "CURL_GLOBAL_WIN32" +which only does anything on Windows machines. When used on +a Windows machine, it'll make libcurl initialize the win32 socket +stuff. Without having that initialized properly, your program cannot use +sockets properly. You should only do this once for each application, so if +your program already does this or of another library in use does it, you +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 OpenSSL +properly for this application. This is only needed to do once for each +application so if your program or another library already does this, this +bit should not be needed. +.RE + +libcurl has a default protection mechanism that detects if curl_global_init() +hasn't been called by the time curl_easy_perform() is called and if that is +the case, libcurl runs the function itself with a guessed bit pattern. Please +note that depending solely on this is not considered nice nor very good. + +When the program no longer uses libcurl, it should call curl_global_cleanup(), +which is the opposite of the init call. It will then do the reversed +operations to cleanup the resources the curl_global_init() call initialized. + +Repeated calls to curl_global_init() and curl_global_cleanup() should be +avoided. They should only be called once each. + +.SH "Features libcurl Provides" +It is considered best-practice to determine libcurl features run-time rather +than build-time (if possible of course). By calling curl_version_info() and +checking tout he details of the returned struct, your program can figure out +exactly what the currently running libcurl supports. + +.SH "Handle the Easy libcurl" +libcurl first introduced the so called easy interface. All operations in the +easy interface are prefixed with 'curl_easy'. + +Recent libcurl versions also offer the multi interface. More about that +interface, what it is targeted for and how to use it is detailed in a separate +chapter further down. You still need to understand the easy interface first, +so please continue reading for better understanding. + +To use the easy interface, you must first create yourself an easy handle. You +need one handle for each easy session you want to perform. Basically, you +should use one handle for every thread you plan to use for transferring. You +must never share the same handle in multiple threads. + +Get an easy handle with + + easyhandle = curl_easy_init(); + +It returns an easy handle. Using that you proceed to the next step: setting +up your preferred actions. A handle is just a logic entity for the upcoming +transfer or series of transfers. + +You set properties and options for this handle using curl_easy_setopt(). They +control how the subsequent transfer or transfers will be made. Options remain +set in the handle until set again to something different. Alas, multiple +requests using the same handle will use the same options. + +Many of the options you set in libcurl are "strings", pointers to data +terminated with a zero byte. Keep in mind that when you set strings with +curl_easy_setopt(), libcurl will not copy the data. It will merely point to +the data. You MUST make sure that the data remains available for libcurl to +use until finished or until you use the same option again to point to +something else. + +One of the most basic properties to set in the handle is the URL. You set +your preferred URL to transfer with CURLOPT_URL in a manner similar to: + +.nf + curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/"); +.fi + +Let's assume for a while that you want to receive data as the URL identifies a +remote resource you want to get here. Since you write a sort of application +that needs this transfer, I assume that you would like to get the data passed +to you directly instead of simply getting it passed to stdout. So, you write +your own function that matches this prototype: + + size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp); + +You tell libcurl to pass all data to this function by issuing a function +similar to this: + + curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data); + +You can control what data your function get in the forth argument by setting +another property: + + curl_easy_setopt(easyhandle, CURLOPT_FILE, &internal_struct); + +Using that property, you can easily pass local data between your application +and the function that gets invoked by libcurl. libcurl itself won't touch the +data you pass with CURLOPT_FILE. + +libcurl offers its own default internal callback that'll take care of the data +if you don't set the callback with CURLOPT_WRITEFUNCTION. It will then simply +output the received data to stdout. You can have the default callback write +the data to a different file handle by passing a 'FILE *' to a file opened for +writing with the CURLOPT_FILE option. + +Now, we need to take a step back and have a deep breath. Here's one of those +rare platform-dependent nitpicks. Did you spot it? On some platforms[2], +libcurl won't be able to operate on files opened by the program. Thus, if you +use the default callback and pass in a an open file with CURLOPT_FILE, it will +crash. You should therefore avoid this to make your program run fine virtually +everywhere. + +There are of course many more options you can set, and we'll get back to a few +of them later. Let's instead continue to the actual transfer: + + success = curl_easy_perform(easyhandle); + +The \fIcurl_easy_perform(3)\fP will connect to the remote site, do the +necessary commands and receive the transfer. Whenever it receives data, it +calls the callback function we previously set. The function may get one byte +at a time, or it may get many kilobytes at once. libcurl delivers as much as +possible as often as possible. Your callback function should return the number +of bytes it "took care of". If that is not the exact same amount of bytes that +was passed to it, libcurl will abort the operation and return with an error +code. + +When the transfer is complete, the function returns a return code that informs +you if it succeeded in its mission or not. If a return code isn't enough for +you, you can use the CURLOPT_ERRORBUFFER to point libcurl to a buffer of yours +where it'll store a human readable error message as well. + +If you then want to transfer another file, the handle is ready to be used +again. Mind you, it is even preferred that you re-use an existing handle if +you intend to make another transfer. libcurl will then attempt to re-use the +previous + +.SH "Multi-threading Issues" +libcurl is completely thread safe, except for two issues: signals and alarm +handlers. Signals are needed for a SIGPIPE handler, and the alarm() Bacall +is used to catch timeouts (mostly during ENS lookup). + +If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are +then of course using OpenSSL multi-threaded and it has itself a few +requirements on this. Basilio, you need to provide one or two functions to +allow it to function properly. For all details, see this: + + http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION + +When using multiple threads you should set the CURLOPT_NOSIGNAL option to +TRUE for all handles. Everything will work fine except that timeouts are not +honored during the DNS lookup - which you can work around by building libcurl +with c-ares support. c-ares is a library that provides asynchronous name +resolves. Unfortunately, c-ares does not yet support IPv6. + +Also, note that CURLOPT_DNS_USE_GLOBAL_CACHE is not thread-safe. + +.SH "When It Doesn't Work" +There will always be times when the transfer fails for some reason. You might +have set the wrong libcurl option or misunderstood what the libcurl option +actually does, or the remote server might return non-standard replies that +confuse the library which then confuses your program. + +There's one golden rule when these things occur: set the CURLOPT_VERBOSE +option to TRUE. It'll cause the library to spew out the entire protocol +details it sends, some internal info and some received protocol data as well +(especially when using FTP). If you're using HTTP, adding the headers in the +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 TRUE. + +Of course there are bugs left. We need to get 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 +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. + +If CURLOPT_VERBOSE is not enough, you increase the level of debug data your +application receive by using the CURLOPT_DEBUGFUNCTION. + +Getting some in-depth knowledge about the protocols involved is never wrong, +and if you're trying to do funny things, you might very well understand +libcurl and how to use it better if you study the appropriate RFC documents +at least briefly. + +.SH "Upload Data to a Remote Site" +libcurl tries to keep a protocol independent approach to most transfers, thus +uploading to a remote FTP site is very similar to uploading data to a HTTP +server with a PUT request. + +Of course, first you either create an easy handle or you re-use one existing +one. Then you set the URL to operate on just like before. This is the remote +URL, that we now will upload. + +Since we write an application, we most likely want libcurl to get the upload +data by asking us for it. To make it do that, we set the read callback and +the custom pointer libcurl will pass to our read callback. The read callback +should have a prototype similar to: + + size_t function(char *bufptr, size_t size, size_t nitems, void *userp); + +Where bufptr is the pointer to a buffer we fill in with data to upload and +size*nitems is the size of the buffer and therefore also the maximum amount +of data we can return to libcurl in this call. The 'userp' pointer is the +custom pointer we set to point to a struct of ours to pass private data +between the application and the callback. + + curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, read_function); + + curl_easy_setopt(easyhandle, CURLOPT_INFILE, &filedata); + +Tell libcurl that we want to upload: + + curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, TRUE); + +A few protocols won't behave properly when uploads are done without any prior +knowledge of the expected file size. So, set the upload file size using the +CURLOPT_INFILESIZE_LARGE for all known file sizes like this[1]: + +.nf + /* in this example, file_size must be an off_t variable */ + curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size); +.fi + +When you call curl_easy_perform() this time, it'll perform all the necessary +operations and when it has invoked the upload it'll call your supplied +callback to get the data to upload. The program should return as much data as +possible in every invoke, as that is likely to make the upload perform as +fast as possible. The callback should return the number of bytes it wrote in +the buffer. Returning 0 will signal the end of the upload. + +.SH "Passwords" +Many protocols use or even require that user name and password are provided +to be able to download or upload the data of your choice. libcurl offers +several ways to specify them. + +Most protocols support that you specify the name and password in the URL +itself. libcurl will detect this and use them accordingly. This is written +like this: + + protocol://user:password@example.com/path/ + +If you need any odd letters in your user name or password, you should enter +them URL encoded, as %XX where XX is a two-digit hexadecimal number. + +libcurl also provides options to set various passwords. The user name and +password as shown embedded in the URL can instead get set with the +CURLOPT_USERPWD option. The argument passed to libcurl should be a char * to +a string in the format "user:password:". In a manner like this: + + curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret"); + +Another case where name and password might be needed at times, is for those +users who need to authenticate themselves to a proxy they use. libcurl offers +another option for this, the CURLOPT_PROXYUSERPWD. It is used quite similar +to the CURLOPT_USERPWD option like this: + + curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); + +There's a long time unix "standard" way of storing ftp user names and +passwords, namely in the $HOME/.netrc file. The file should be made private +so that only the user may read it (see also the "Security Considerations" +chapter), as it might contain the password in plain text. libcurl has the +ability to use this file to figure out what set of user name and password to +use for a particular host. As an extension to the normal functionality, +libcurl also supports this file for non-FTP protocols such as HTTP. To make +curl use this file, use the CURLOPT_NETRC option: + + curl_easy_setopt(easyhandle, CURLOPT_NETRC, TRUE); + +And a very basic example of how such a .netrc file may look like: + +.nf + machine myhost.mydomain.com + login userlogin + password secretword +.fi + +All these examples have been cases where the password has been optional, or +at least you could leave it out and have libcurl attempt to do its job +without it. There are times when the password isn't optional, like when +you're using an SSL private key for secure transfers. + +To pass the known private key password to libcurl: + + curl_easy_setopt(easyhandle, CURLOPT_SSLKEYPASSWD, "keypassword"); + +.SH "HTTP Authentication" +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 +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, +Negotiate, GSS-Negotiate and SPNEGO. You can tell libcurl which one to use +with CURLOPT_HTTPAUTH as in: + + curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); + +And when you send authentication to a proxy, you can also set authentication +type the same way but instead with CURLOPT_PROXYAUTH: + + curl_easy_setopt(easyhandle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); + +Both these options allow you to set multiple types (by ORing them together), +to make libcurl pick the most secure one out of the types the server/proxy +claims to support. This method does however add a round-trip since libcurl +must first ask the server what it supports: + + curl_easy_setopt(easyhandle, CURLOPT_HTTPAUTH, + CURLAUTH_DIGEST|CURLAUTH_BASIC); + +For convenience, you can use the 'CURLAUTH_ANY' define (instead of a list +with specific types) which allows libcurl to use whatever method it wants. + +When asking for multiple types, libcurl will pick the available one it +considers "best" in its own internal order of preference. + +.SH "HTTP POSTing" +We get many questions regarding how to issue HTTP POSTs with libcurl the +proper way. This chapter will thus include examples using both different +versions of HTTP POST that libcurl supports. + +The first version is the simple POST, the most common version, that most HTML +pages using the
tag uses. We provide a pointer to the data and tell +libcurl to post it all to the remote site: + +.nf + char *data="name=daniel&project=curl"; + curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, data); + curl_easy_setopt(easyhandle, CURLOPT_URL, "http://posthere.com/"); + + curl_easy_perform(easyhandle); /* post away! */ +.fi + +Simple enough, huh? Since you set the POST options with the +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 +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 +then passing that list to libcurl. + +.nf + struct curl_slist *headers=NULL; + headers = curl_slist_append(headers, "Content-Type: text/xml"); + + /* post binary data */ + curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr); + + /* set the size of the postfields data */ + curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23); + + /* pass our list of custom made headers */ + curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers); + + curl_easy_perform(easyhandle); /* post away! */ + + curl_slist_free_all(headers); /* free the header list */ +.fi + +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 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 that you build a formpost yourself and provide to +libcurl. To make that easier, libcurl provides curl_formadd(). 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. + +.nf + struct curl_httppost *post=NULL; + struct curl_httppost *last=NULL; + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "name", + CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END); + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "project", + CURLFORM_COPYCONTENTS, "curl", CURLFORM_END); + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "logotype-image", + CURLFORM_FILECONTENT, "curl.png", CURLFORM_END); + + /* Set the form info */ + curl_easy_setopt(easyhandle, CURLOPT_HTTPPOST, post); + + curl_easy_perform(easyhandle); /* post away! */ + + /* free the post data again */ + curl_formfree(post); +.fi + +Multipart formposts are chains of parts using MIME-style separators and +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 +will show how you set headers to one specific part when you add that to the +post handle: + +.nf + struct curl_slist *headers=NULL; + headers = curl_slist_append(headers, "Content-Type: text/xml"); + + curl_formadd(&post, &last, + CURLFORM_COPYNAME, "logotype-image", + CURLFORM_FILECONTENT, "curl.xml", + CURLFORM_CONTENTHEADER, headers, + CURLFORM_END); + + curl_easy_perform(easyhandle); /* post away! */ + + curl_formfree(post); /* free post */ + curl_slist_free_all(post); /* free custom header list */ +.fi + +Since all options on an easyhandle are "sticky", they remain the same until +changed even if you do call curl_easy_perform(), 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 CURLOPT_HTTPGET +option: + + curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, TRUE); + +Just setting CURLOPT_POSTFIELDS to "" or NULL will *not* stop libcurl from +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 +terminal. + +Switch on the progress meter by, oddly enough, set CURLOPT_NOPROGRESS to +FALSE. This option is set to TRUE by default. + +For most applications however, the built-in progress meter is useless and +what instead is interesting is the ability to specify a progress +callback. The function pointer you pass to libcurl will then be called on +irregular intervals with information about the current transfer. + +Set the progress callback by using CURLOPT_PROGRESSFUNCTION. And pass a +pointer to a function that matches this prototype: + +.nf + int progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow); +.fi + +If any of the input arguments is unknown, a 0 will be passed. The first +argument, the 'clientp' is the pointer you pass to libcurl with +CURLOPT_PROGRESSDATA. libcurl won't touch it. + +.SH "libcurl with C++" + +There's basically only one thing to keep in mind when using C++ instead of C +when interfacing libcurl: + + "The Callbacks Must Be Plain C" + +So if you want a write callback set in libcurl, you should put it within +\&'extern'. Similar to this: + +.nf + extern "C" { + size_t write_data(void *ptr, size_t size, size_t nmemb, + void *ourpointer) + { + /* do what you want with the data */ + } + } +.fi + +This will of course effectively turn the callback code into C. There won't be +any "this" pointer available etc. + +.SH "Proxies" + +What "proxy" means according to Merriam-Webster: "a person authorized to act +for another" but also "the agency, function, or office of a deputy who acts as +a substitute for another". + +Proxies are exceedingly common these days. Companies often only offer +Internet access to employees through their HTTP proxies. Network clients or +user-agents ask the proxy for documents, the proxy does the actual request +and then it returns them. + +libcurl has full support for HTTP proxies, so when a given URL is wanted, +libcurl will ask the proxy for it instead of trying to connect to the actual +host identified in the URL. + +The fact that the proxy is a HTTP proxy puts certain 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 can't invoke your own +custom FTP commands or even proper FTP directory listings. + +.IP "Proxy Options" + +To tell libcurl to use a proxy at a given port number: + + curl_easy_setopt(easyhandle, CURLOPT_PROXY, "proxy-host.com:8080"); + +Some proxies require user authentication before allowing a request, and you +pass that information similar to this: + + curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "user:password"); + +If you want to, you can specify the host name only in the CURLOPT_PROXY +option, and set the port number separately with CURLOPT_PROXYPORT. + +.IP "Environment Variables" + +libcurl automatically checks and uses a set of environment variables to +know what proxies to use for certain protocols. The names of the variables +are following an ancient de facto standard and are built up as +"[protocol]_proxy" (note the lower casing). Which makes the variable +'http_proxy' checked for a name of a proxy to use when the input URL is +HTTP. Following the same rule, the variable named 'ftp_proxy' is checked +for FTP URLs. Again, the proxies are always HTTP proxies, the different +names of the variables simply allows different HTTP proxies to be used. + +The proxy environment variable contents should be in the format +\&"[protocol://][user:password@]machine[:port]". Where the protocol:// part is +simply ignored if present (so http://proxy and bluerk://proxy will do the +same) and the optional port number specifies on which port the proxy operates +on the host. If not specified, the internal default port number will be used +and that is most likely *not* the one you would like it to be. + +There are two special environment variables. 'all_proxy' is what sets proxy +for any URL in case the protocol specific variable wasn't set, and +\&'no_proxy' defines a list of hosts that should not use a proxy even though a +variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all +hosts. + +.IP "SSL and Proxies" + +SSL is for secure point-to-point connections. This involves strong encryption +and similar things, which effectively makes it impossible for a proxy to +operate as a "man in between" which the proxy's task is, as previously +discussed. Instead, the only way to have SSL work over a HTTP proxy is to ask +the proxy to tunnel trough everything without being able to check or fiddle +with the traffic. + +Opening an SSL connection over a HTTP proxy is therefor a matter of asking the +proxy for a straight connection to the target host on a specified port. This +is made with the HTTP request CONNECT. ("please mr proxy, connect me to that +remote host"). + +Because of the nature of this operation, where the proxy has no idea what kind +of data that is passed in and out through this tunnel, this breaks some of the +very few advantages that come from using a proxy, such as caching. Many +organizations prevent this kind of tunneling to other destination port numbers +than 443 (which is the default HTTPS port number). + +.IP "Tunneling Through Proxy" +As explained above, tunneling is required for SSL to work and often even +restricted to the operation intended for SSL; HTTPS. + +This is however not the only time proxy-tunneling might offer benefits to +you or your application. + +As tunneling opens a direct connection from your application to the remote +machine, it suddenly also re-introduces the ability to do non-HTTP +operations over a HTTP proxy. You can in fact use things such as FTP +upload or FTP custom commands this way. + +Again, this is often prevented by the administrators of proxies and is +rarely allowed. + +Tell libcurl to use proxy tunneling like this: + + curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, TRUE); + +In fact, there might even be times when you want to do plain HTTP +operations using a tunnel like this, as it then enables you to operate on +the remote server instead of asking the proxy to do so. libcurl will not +stand in the way for such innovative actions either! + +.IP "Proxy Auto-Config" + +Netscape first came up with this. It is basically a web page (usually using a +\&.pac extension) with a javascript that when executed by the browser with the +requested URL as input, returns information to the browser on how to connect +to the URL. The returned information might be "DIRECT" (which means no proxy +should be used), "PROXY host:port" (to tell the browser where the proxy for +this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS +proxy). + +libcurl has no means to interpret or evaluate javascript and thus it doesn't +support this. If you get yourself in a position where you face this nasty +invention, the following advice have been mentioned and used in the past: + +- Depending on the javascript complexity, write up a script that translates it +to another language and execute that. + +- Read the javascript code and rewrite the same logic in another language. + +- Implement a javascript interpreted, people have successfully used the +Mozilla javascript engine in the past. + +- Ask your admins to stop this, for a static proxy setup or similar. + +.SH "Persistence Is The Way to Happiness" + +Re-cycling the same easy handle several times when doing multiple requests is +the way to go. + +After each single curl_easy_perform() operation, libcurl will keep the +connection alive and open. A subsequent request using the same easy handle to +the same host might just be able to use the already open connection! This +reduces network impact a lot. + +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- +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. + +libcurl caches DNS name resolving results, to make lookups of a previously +looked up name a lot faster. + +Other interesting details that improve performance for subsequent requests +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 +point in changing this value, and if you think of changing this it is often +just a matter of thinking again. + +When the connection cache gets filled, libcurl must close an existing +connection in order to get room for the new one. To know which connection to +close, libcurl uses a "close policy" that you can affect with the +CURLOPT_CLOSEPOLICY option. There's only two polices implemented as of this +writing (libcurl 7.9.4) and they are: + +.RS +.IP CURLCLOSEPOLICY_LEAST_RECENTLY_USED +simply close the one that hasn't been used for the longest time. This is the +default behavior. +.IP CURLCLOSEPOLICY_OLDEST +closes the oldest connection, the one that was created the longest time ago. +.RE + +There are, or at least were, plans to support a close policy that would call +a user-specified callback to let the user be able to decide which connection +to dump when this is necessary and therefor is the CURLOPT_CLOSEFUNCTION an +existing option still today. Nothing ever uses this though and this will not +be used within the foreseeable future either. + +To force your upcoming request to not use an already existing connection (it +will even close one first if there happens to be one alive to the same host +you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT +to TRUE. In a similar spirit, you can also forbid the upcoming request to be +"lying" around and possibly get re-used after the request by setting +CURLOPT_FORBID_REUSE to TRUE. + +.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. + +.IP "Host" +This header is required by HTTP 1.1 and even many 1.0 servers and should be +the name of the server we want to talk to. This includes the port number if +anything but default. + +.IP "Pragma" +\&"no-cache". Tells a possible proxy to not grab a copy from the cache but to +fetch a fresh one. + +.IP "Accept" +\&"*/*". + +.IP "Expect:" +When doing multi-part formposts, libcurl will set this header to +\&"100-continue" to ask the server for an "OK" message before it proceeds with +sending the data part of the post. + +.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. + +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...) +manners. You may need to change words, headers or various data. + +libcurl is your friend here too. + +.IP CUSTOMREQUEST +If just changing the actual HTTP request keyword is what you want, like when +GET, HEAD or POST is not good enough for you, CURLOPT_CUSTOMREQUEST is there +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 +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: + +.nf + struct curl_slist *headers=NULL; /* init to NULL is important */ + + headers = curl_slist_append(headers, "Hey-server-hey: how are you?"); + headers = curl_slist_append(headers, "X-silly-content: yes"); + + /* pass our list of custom made headers */ + curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers); + + curl_easy_perform(easyhandle); /* transfer http */ + + curl_slist_free_all(headers); /* free the header list */ +.fi + +\&... and if you think some of the internally generated headers, such as +Accept: or Host: don't contain the data you want them to contain, you can +replace them by simply setting them too: + +.nf + headers = curl_slist_append(headers, "Accept: Agent-007"); + headers = curl_slist_append(headers, "Host: munged.host.line"); +.fi + +.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: + + headers = curl_slist_append(headers, "Accept:"); + +Both replacing and canceling internal headers should be done with careful +consideration and you should be aware that you may violate the HTTP protocol +when doing so. + +.IP "Enforcing chunked transfer-encoding" + +By making sure a request uses the custom header "Transfer-Encoding: chunked" +when doing a non-GET HTTP operation, libcurl will switch over to "chunked" +upload, even though the size of the data to upload might be known. By default, +libcurl usually switches over to chunked upload automatically if the upload +data size is unknown. + +.IP "HTTP Version" + +There's only one aspect left in the HTTP requests that we haven't yet +mentioned how to modify: the version field. 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 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: + + curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURLHTTP_VERSION_1_0); + +.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. + +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 +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 +or similar) you might confuse libcurl and then it might not attempt to +transfer the file in the correct remote directory. + +A little example that deletes a given file before an operation: + +.nf + headers = curl_slist_append(headers, "DELE file-to-remove"); + + /* pass the list of custom commands to the handle */ + curl_easy_setopt(easyhandle, CURLOPT_QUOTE, headers); + + curl_easy_perform(easyhandle); /* transfer ftp data! */ + + curl_slist_free_all(headers); /* free the header list */ +.fi + +If you would instead want this operation (or chain of operations) to happen +_after_ the data transfer took place the option to curl_easy_setopt() would +instead be called CURLOPT_POSTQUOTE and used the exact same way. + +The custom FTP command will be issued to the server in the same order they are +added to the list, and if a command gets an error code returned back from the +server, no more commands will be issued and libcurl will bail out with an +error code (CURLE_FTP_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE to send +commands before a transfer, no transfer will actually take place when a quote +command has failed. + +If you set the CURLOPT_HEADER to true, you will tell libcurl to get +information about the target file and output "headers" about it. The headers +will be in "HTTP-style", looking like they do in HTTP. + +The option to enable headers or to run custom FTP commands may be useful to +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 +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. + +.SH "Cookies Without Chocolate Chips" +In the HTTP sense, a cookie is a name with an associated value. A server sends +the name and value to the client, and expects it to get sent back on every +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 +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 +they're sent from clients to servers with the Cookie: header. + +To just send whatever cookie you want to a server, you can use CURLOPT_COOKIE +to set a cookie string like this: + + curl_easy_setopt(easyhandle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); + +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. + +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 +figure out which cookies to use. Set header file to read cookies from with +CURLOPT_COOKIEFILE. + +The CURLOPT_COOKIEFILE option also automatically enables the cookie parser in +libcurl. Until the cookie parser is enabled, libcurl will not parse or +understand incoming cookies and they will just be ignored. However, when the +parser is enabled the cookies will be understood and the cookies will be kept +in memory and used properly in subsequent requests when the same handle is +used. Many times this is enough, and you may not have to save the cookies to +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 able might be to use a file name you know doesn't exist. + +If you 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 +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 curl_easy_cleanup() is called. This enabled cookies +to get passed on properly between multiple handles without any information +getting lost. + +.SH "FTP Peculiarities We Need" + +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 +second connection is being made. + +libcurl can either connect to the server a second time or tell the server to +connect back to it. The first option is the default and it is also what works +best for all the people behind firewalls, NATs or IP-masquerading setups. +libcurl then tells the server to open up a new port and wait for a second +connection. This is by default attempted with EPSV first, and if that doesn't +work it tries PASV instead. (EPSV is an extension to the original FTP spec +and does not exist nor work on all FTP servers.) + +You can prevent libcurl from first trying the EPSV command by setting +CURLOPT_FTP_USE_EPSV to FALSE. + +In some cases, you will prefer to have the server connect back to you for the +second connection. This might be when the server is perhaps behind a firewall +or something and only allows connections on a single port. libcurl then +informs the remote server which IP address and port number to connect to. +This is made with the CURLOPT_FTPPORT option. If you set it to "-", libcurl +will use your system's "default IP address". If you want to use a particular +IP, you can set the full IP address, a host name to resolve to an IP address +or even a local network interface name that libcurl will get the IP address +from. + +When doing the "PORT" approach, libcurl will attempt to use the EPRT and the +LPRT before trying PORT, as they work with more protocols. You can disable +this behavior by setting CURLOPT_FTP_USE_EPRT to FALSE. + +.SH "Headers Equal Fun" + +Some protocols provide "headers", meta-data separated from the normal +data. These headers are by default not included in the normal data stream, +but you can make them appear in the data stream by setting CURLOPT_HEADER to +TRUE. + +What might be even more useful, is libcurl's ability to separate the headers +from the data and thus make the callbacks differ. You can for example set a +different pointer to pass to the ordinary write callback by setting +CURLOPT_WRITEHEADER. + +Or, you can set an entirely separate function to receive the headers, by +using CURLOPT_HEADERFUNCTION. + +The headers are passed to the callback function one by one, and you can +depend on that fact. It makes it easier for you to add custom header parsers +etc. + +"Headers" for FTP transfers equal all the FTP server responses. They aren't +actually true headers, but in this case we pretend they are! ;-) + +.SH "Post Transfer Information" + + [ curl_easy_getinfo ] + +.SH "Security Considerations" + +libcurl is in itself not insecure. If used the right way, you can use libcurl +to transfer data pretty safely. + +There are of course many things to consider that may loosen up this +situation: + +.IP "Command Lines" +If you use a command line tool (such as curl) that uses libcurl, and you give +option to the tool on the command line those options can very likely get read +by other users of your system when they use 'ps' or other tools to list +currently running processes. + +To avoid this problem, never feed sensitive things to programs using command +line options. + +.IP ".netrc" +\&.netrc is a pretty handy file/feature that allows you to login quickly and +automatically to frequently visited sites. The file contains passwords in +clear text and is a real security risk. In some cases, your .netrc is also +stored in a home directory that is NFS mounted or used on another network +based file system, so the clear text password will fly through your network +every time anyone reads that file! + +To avoid this problem, don't use .netrc files and never store passwords in +plain text anywhere. + +.IP "Clear Text Passwords" +Many of the protocols libcurl supports send name and password unencrypted as +clear text (HTTP Basic authentication, FTP, TELNET etc). It is very easy for +anyone on your network or a network nearby yours, to just fire up a network +analyzer tool and eavesdrop on your passwords. Don't let the fact that HTTP +uses base64 encoded passwords fool you. They may not look readable at a first +glance, but they very easily "deciphered" by anyone within seconds. + +To avoid this problem, use protocols that don't let snoopers see your +password: HTTPS, FTPS and FTP-kerberos are a few examples. HTTP Digest +authentication allows this too, but isn't supported by libcurl as of this +writing. + +.IP "Showing What You Do" +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 +mention passwords of course) may in fact be used by intruders to gain +additional information of a potential target. + +To avoid this problem, you must of course use your common sense. Often, you +can just edit out the sensitive data or just search/replace your true +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 +done. + +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. + +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 +a "multi stack". + +You create the easy handles you want and you set all the options just like +you have been told above, and then you create a multi handle with +curl_multi_init() and add all those easy handles to that multi handle with +curl_multi_add_handle(). + +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 curl_multi_perform(). + +curl_multi_perform() is asynchronous. It will only execute as little as +possible and then return back control to your program. It is designed to +never block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again +soon, as that is a signal that it still has local data to send or remote data +to receive. + +The best usage of this interface is when you do a select() on all possible +file descriptors or sockets to know when to call libcurl again. This also +makes it easy for you to wait and respond to actions on your own +application's sockets/handles. You figure out what to select() for by using +curl_multi_fdset(), that fills in a set of fd_set variables for you 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 curl_multi_perform() 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 call +curl_multi_perform(), 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 curl_multi_fdset() immediately before +the select() call since the current set of file descriptors may change when +calling a curl function. + +If you want to stop the transfer of one of the easy handles in the stack, you +can use curl_multi_remove_handle() to remove individual easy +handles. Remember that easy handles should be curl_easy_cleanup()ed. + +When a transfer within the multi stack has finished, the counter of running +transfers (as filled in by curl_multi_perform()) will decrease. When the +number reaches zero, all transfers are done. + +curl_multi_info_read() can be used to get information about completed +transfers. It then returns the CURLcode for each easy transfer, to allow you +to figure out success on each individual transfer. + +.SH "SSL, Certificates and Other Tricks" + + [ seeding, passwords, keys, certificates, ENGINE, ca certs ] + +.SH "Sharing Data Between Easy Handles" + + [ fill in ] + +.SH "Footnotes" + +.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 +size. +.IP "[2]" +This happens on Windows machines when libcurl is built and used as a +DLL. However, you can still do this on Windows if you link with a static +library. +.IP "[3]" +The curl-config tool is generated at build-time (on unix-like systems) and +should be installed with the 'make install' or similar instruction that +installs the library, header files, man pages etc. -- cgit v1.2.1 From c136b80af59914fb11c78936e9cab7a3dd2e3955 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 21 Jun 2004 08:28:10 +0000 Subject: refer to the new tutorial man page --- docs/libcurl/libcurl.3 | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 742511e18..c9eee4e30 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -1,19 +1,17 @@ -.\" You can view this file with: -.\" nroff -man [file] .\" $Id$ .\" .TH libcurl 3 "19 March 2002" "libcurl 7.9.6" "libcurl overview" .SH NAME libcurl \- client-side URL transfers .SH DESCRIPTION -This is an overview on how to use libcurl in your C programs. There are +This is an short overview on how to use libcurl in your C programs. There are specific man pages for each function mentioned in here. There are also the \fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the -\fIlibcurl-share(3)\fP man page and the \fIlibcurl-the-guide\fP document for -further reading on how to do programming with libcurl. +\fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for +in-depth understanding on how to program with libcurl. -There exist more than a dozen custom bindings that bring libcurl access to -your favourite language. Look elsewhere for documentation on those. +There are more than a twenty custom bindings available that bring libcurl +access to your favourite language. Look elsewhere for documentation on those. All applications that use libcurl should call \fIcurl_global_init(3)\fP exactly once before any libcurl function can be used. After all usage of -- cgit v1.2.1 From 0d259b898bf6cc09de17115e4c696c48c97b1bd4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 21 Jun 2004 08:28:18 +0000 Subject: updates --- docs/libcurl/index.html | 3 ++- docs/libcurl/libcurl-multi.3 | 6 +++--- 2 files changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 6d4f133c2..526569126 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -16,7 +16,7 @@
libcurl-multi
libcurl-share
libcurl-errors -
libcurl-the-guide (plain text) +
libcurl-tutorial

Library Functions (A-Z)

curl_easy_cleanup @@ -34,6 +34,7 @@
curl_getenv
curl_global_cleanup
curl_global_init +
curl_global_init_mem
curl_mprintf
curl_multi_add_handle
curl_multi_cleanup diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index b97ac9856..05e720359 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -8,9 +8,9 @@ libcurl-multi \- how to use the multi interface .SH DESCRIPTION This is an overview on how to use the libcurl multi interface in your C programs. There are specific man pages for each function mentioned in -here. There's also the libcurl-the-guide document for a complete tutorial to -programming with libcurl and the \fIlibcurl(3)\fP man page for an overview of -the libcurl easy interface. +here. There's also the \fIlibcurl-tutorial(3)f\P man page for a complete +tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page +for an overview of the libcurl easy interface. All functions in the multi interface are prefixed with curl_multi. .SH "PLEASE NOTICE" -- cgit v1.2.1 From 1886893d66356634a7d13b466a1ced38265f68e2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 21 Jun 2004 14:09:23 +0000 Subject: Added blurb for the READFUNCTION, including the new CURL_READFUNC_ABORT return code. --- docs/libcurl/curl_easy_setopt.3 | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 94b5626d0..67b44496d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -119,6 +119,15 @@ filled with at most \fIsize\fP multiplied with \fInmemb\fP number of bytes. Your function must return the actual number of bytes that you stored in that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer. + +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 +upload less than N bytes), you may experience that the server "hangs" waiting +for the rest of the data that won't come. + +In libcurl 7.12.1 and later, the read callback may return +\fICURL_READFUNC_ABORT\fP to stop the current operation at once, with a +\fICURLE_ABORTED_BY_CALLBACK\fP error code from the transfer. .IP CURLOPT_READDATA Data pointer to pass to the file read function. Note that if you specify the \fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you -- cgit v1.2.1 From a20eb6df1b4affbec9cec60a9df4f97fe7c77dbe Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 22 Jun 2004 17:22:30 +0000 Subject: reset CURLOPT_HTTPHEADER with NULL --- docs/libcurl/curl_easy_setopt.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 67b44496d..95d699a11 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -534,6 +534,8 @@ The first line in a request (usually containing a GET or POST) is not a header and cannot be replaced using this option. Only the lines following the request-line are headers. +Pass a NULL to this to reset back to no custom headers. + \fBNOTE:\fP The most commonly replaced headers have "shortcuts" in the options \fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP. .IP CURLOPT_HTTP200ALIASES -- cgit v1.2.1 From 6f252f470470698ff08cffc23daa7276bbc8d327 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 27 Jun 2004 21:19:54 +0000 Subject: reset CURLOPT_CUSTOMREQUEST with NULL --- docs/libcurl/curl_easy_setopt.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 95d699a11..670eacd91 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -721,6 +721,8 @@ when doing an 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. +Restore to the internal default by setting this to NULL. + \fBNOTE:\fP Many people have wrongly used this option to replace the entire request with their own, including multiple headers and POST contents. While that might work in many cases, it will cause libcurl to send invalid requests -- cgit v1.2.1 From 5a70e42428209416848f7fcda5a856dd6c4966a0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 2 Jul 2004 14:00:49 +0000 Subject: I prefer CURLOPT_WRITEDATA before CURLOPT_FILE --- docs/libcurl/libcurl-tutorial.3 | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index f1716b692..1c2215de5 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -188,24 +188,27 @@ similar to this: You can control what data your function get in the forth argument by setting another property: - curl_easy_setopt(easyhandle, CURLOPT_FILE, &internal_struct); + curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct); Using that property, you can easily pass local data between your application and the function that gets invoked by libcurl. libcurl itself won't touch the -data you pass with CURLOPT_FILE. +data you pass with CURLOPT_WRITEDATA. libcurl offers its own default internal callback that'll take care of the data if you don't set the callback with CURLOPT_WRITEFUNCTION. It will then simply output the received data to stdout. You can have the default callback write the data to a different file handle by passing a 'FILE *' to a file opened for -writing with the CURLOPT_FILE option. +writing with the CURLOPT_WRITEDATA option. Now, we need to take a step back and have a deep breath. Here's one of those rare platform-dependent nitpicks. Did you spot it? On some platforms[2], libcurl won't be able to operate on files opened by the program. Thus, if you -use the default callback and pass in a an open file with CURLOPT_FILE, it will -crash. You should therefore avoid this to make your program run fine virtually -everywhere. +use the default callback and pass in a an open file with CURLOPT_WRITEDATA, it +will crash. You should therefore avoid this to make your program run fine +virtually everywhere. + +(CURLOPT_WRITEDATA was formerly known as CURLOPT_FILE. Both names still work +and do the same thing). There are of course many more options you can set, and we'll get back to a few of them later. Let's instead continue to the actual transfer: -- cgit v1.2.1 From a92b7c1b16ace4bd238b1208f4baeb82482be42f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 14 Jul 2004 15:32:09 +0000 Subject: Jason Nye pointed out that callbacks don't need to use the "C namespace" --- docs/libcurl/libcurl-tutorial.3 | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 1c2215de5..14c8988c4 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -571,24 +571,20 @@ CURLOPT_PROGRESSDATA. libcurl won't touch it. There's basically only one thing to keep in mind when using C++ instead of C when interfacing libcurl: - "The Callbacks Must Be Plain C" +The callbacks CANNOT be non-static class member functions -So if you want a write callback set in libcurl, you should put it within -\&'extern'. Similar to this: +Example C++ code: .nf - extern "C" { - size_t write_data(void *ptr, size_t size, size_t nmemb, - void *ourpointer) +class AClass { + static size_t write_data(void *ptr, size_t size, size_t nmemb, + void *ourpointer) { /* do what you want with the data */ } } .fi -This will of course effectively turn the callback code into C. There won't be -any "this" pointer available etc. - .SH "Proxies" What "proxy" means according to Merriam-Webster: "a person authorized to act -- cgit v1.2.1 From 35618b4712ed45553020f5d509602d9faee5b3d1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 17 Jul 2004 08:22:50 +0000 Subject: minor format fix --- docs/libcurl/libcurl-multi.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 05e720359..7d08b1e23 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -8,7 +8,7 @@ libcurl-multi \- how to use the multi interface .SH DESCRIPTION This is an overview on how to use the libcurl multi interface in your C programs. There are specific man pages for each function mentioned in -here. There's also the \fIlibcurl-tutorial(3)f\P man page for a complete +here. There's also the \fIlibcurl-tutorial(3)\fP man page for a complete tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page for an overview of the libcurl easy interface. -- cgit v1.2.1 From 060b6ce1481d523d93532e07b4b924597d838c5c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 17 Jul 2004 08:24:22 +0000 Subject: the multi interface is not so new anymore! --- docs/libcurl/libcurl-multi.3 | 5 ----- 1 file changed, 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 7d08b1e23..955063a34 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -13,11 +13,6 @@ tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page for an overview of the libcurl easy interface. All functions in the multi interface are prefixed with curl_multi. -.SH "PLEASE NOTICE" -The multi interface is a rather new member of the libcurl family. It has not -yet been very widely used. It may still be a few more bugs lurking in there -than we are used to. That said, it might also just work in every aspect you -try it. Please report all bugs and oddities you see. .SH "OBJECTIVES" The multi interface introduces several new abilities that the easy interface refuses to offer. They are mainly: -- cgit v1.2.1 From 6577b15d08d0ed151c7819b8f25b9ff0385e2ece Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 31 Jul 2004 19:46:01 +0000 Subject: curl_easy_reset() documented --- docs/libcurl/Makefile.am | 7 ++++--- docs/libcurl/curl_easy_reset.3 | 22 ++++++++++++++++++++++ 2 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 docs/libcurl/curl_easy_reset.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 27f8d7816..d4f8a1008 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -16,7 +16,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_share_init.3 curl_share_setopt.3 libcurl.3 libcurl-easy.3 \ libcurl-multi.3 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3 \ curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ - libcurl-tutorial.3 + libcurl-tutorial.3 curl_easy_reset.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -32,7 +32,7 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ curl_share_strerror.html curl_global_init_mem.html \ - libcurl-tutorial.html + libcurl-tutorial.html curl_easy_reset.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ @@ -47,7 +47,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_share_init.pdf curl_share_setopt.pdf libcurl.pdf \ libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ - curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf + curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ + curl_easy_reset.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_easy_reset.3 b/docs/libcurl/curl_easy_reset.3 new file mode 100644 index 000000000..6cf5ddbea --- /dev/null +++ b/docs/libcurl/curl_easy_reset.3 @@ -0,0 +1,22 @@ +.\" $Id$ +.\" +.TH curl_easy_reset 3 "31 July 2004" "libcurl 7.12.1" "libcurl Manual" +.SH NAME +curl_easy_reset - reset all options of a libcurl session handle +.SH SYNOPSIS +.B #include + +.BI "void curl_easy_reset(CURL *"handle ");" + +.SH DESCRIPTION +Re-initializes all options previously set on a specified CURL handle to the +default values. This puts back the handle to the same state as it was in when +it was just created with \fIcurl_easy_init(3)\fP. + +It does not change the following information kept in the handle: live +connections, the Session ID cache, the DNS cache, the cookies and shares. +.SH RETURN VALUE +Nothing +.SH "SEE ALSO" +.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_setopt "(3) + -- cgit v1.2.1 From 496ea65f39c745ffc240660adc8f67907f6b7c9f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 31 Jul 2004 19:46:25 +0000 Subject: link to reset as well --- docs/libcurl/index.html | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 526569126..6b4f10550 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -24,6 +24,7 @@
curl_easy_getinfo
curl_easy_init
curl_easy_perform +
curl_easy_reset
curl_easy_setopt
curl_easy_strerror
curl_escape -- cgit v1.2.1 From d892a4dc23a628d60b39801ebad43e7a0d54dad3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 31 Jul 2004 19:47:00 +0000 Subject: mention this is new --- docs/libcurl/curl_easy_reset.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_reset.3 b/docs/libcurl/curl_easy_reset.3 index 6cf5ddbea..812be4c8b 100644 --- a/docs/libcurl/curl_easy_reset.3 +++ b/docs/libcurl/curl_easy_reset.3 @@ -15,6 +15,8 @@ it was just created with \fIcurl_easy_init(3)\fP. It does not change the following information kept in the handle: live connections, the Session ID cache, the DNS cache, the cookies and shares. + +This function was added in libcurl 7.12.1. .SH RETURN VALUE Nothing .SH "SEE ALSO" -- cgit v1.2.1 From 355b3d305793b386ec2b029b3d5f06426bb57f37 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Aug 2004 13:22:08 +0000 Subject: updated the CURLOPT_POST description after input from Alan Pinstein --- docs/libcurl/curl_easy_setopt.3 | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 670eacd91..4a1338c0b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -469,16 +469,27 @@ data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP. This option is deprecated and starting with version 7.12.1 you should instead use \fICURLOPT_UPLOAD\fP. .IP CURLOPT_POST -A non-zero parameter tells the library to do a regular HTTP post. This is a -normal application/x-www-form-urlencoded kind, which is the most commonly used -one by HTML forms. See the \fICURLOPT_POSTFIELDS\fP option for how to specify -the data to post and \fICURLOPT_POSTFIELDSIZE\fP in how to set the data -size. Using the \fICURLOPT_POSTFIELDS\fP option implies this option. +A non-zero parameter tells the library to do a regular HTTP post. This will +also make the library use the a "Content-Type: +application/x-www-form-urlencoded" header. (This is by far the most commonly +used POST method). + +Use the \fICURLOPT_POSTFIELDS\fP option to specify what data to post and +\fICURLOPT_POSTFIELDSIZE\fP to set the data size. Optionally, you can provide +data to POST using the \fICURLOPT_READFUNCTION\FP and \fICURLOPT_READDATA\fP +options. + +You can override the default POST Content-Type: header by setting your own +with \fICURLOPT_HTTPHEADER\fP. + +NOTE: if you have issued a POST request and want to make a HEAD or GET +instead, you must explictly pick the new request type using +\fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. .IP CURLOPT_POSTFIELDS Pass a char * as parameter, which should be the full data to post in an HTTP -post operation. You need to make sure that the data is formatted the way you -want the server to receive it. libcurl will not convert or encode it for -you. Most web servers will assume this data to be url-encoded. Take note. +POST operation. You must make sure that the data is formatted the way you want +the server to receive it. libcurl will not convert or encode it for you. Most +web servers will assume this data to be url-encoded. Take note. This POST is a normal application/x-www-form-urlencoded kind (and libcurl will set that Content-Type by default when this option is used), which is the most -- cgit v1.2.1 From d3c9f3d6f8beb8a24e99c2d74080909d59221110 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 11 Aug 2004 08:44:36 +0000 Subject: clarify that CURLE_FTP_USER_PASSWORD_INCORRECT might in fact get returned even if user and password are correct --- docs/libcurl/libcurl-errors.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index e0699645f..0c37c3d76 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -45,8 +45,9 @@ server is probably not an OK FTP server. We were denied access when trying to login to an FTP server or when trying to change working directory to the one given in the URL. .IP "CURLE_FTP_USER_PASSWORD_INCORRECT (10)" -The username and/or the password were incorrect when trying to login to an FTP -server. +The FTP server rejected access to the server after the password was sent to +it. It might be because the username and/or the password were incorrect or +just that the server is not allowing you access for the moment etc. .IP "CURLE_FTP_WEIRD_PASS_REPLY (11)" After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. -- cgit v1.2.1 From 8b6e87abee9097a366216f2bfb39d1aad2ec2282 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 16 Aug 2004 10:49:57 +0000 Subject: summary edit: mention that some options take a curl_off_t --- docs/libcurl/curl_easy_setopt.3 | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4a1338c0b..29b798584 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -32,11 +32,11 @@ CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter); curl_easy_setopt() is used to tell libcurl how to behave. By using the appropriate options to \fIcurl_easy_setopt\fP, you can change libcurl's behavior. All options are set with the \fIoption\fP followed by a -\fIparameter\fP. That parameter can be a long, a function pointer or an object -pointer, all depending on what the specific option expects. Read this manual -carefully as bad input values may cause libcurl to behave badly! You can only -set one option in each function call. A typical application uses many -curl_easy_setopt() calls in the setup phase. +\fIparameter\fP. That parameter can be a \fBlong\fP, a \fBfunction pointer\fP, +an \fBobject pointer\fP or a \fBcurl_off_t\fP, depending on what the specific +option expects. Read this manual carefully as bad input values may cause +libcurl to behave badly! You can only set one option in each function call. A +typical application uses many curl_easy_setopt() calls in the setup phase. Options set with this function call are valid for all forthcoming transfers performed using this \fIhandle\fP. The options are not in any way reset @@ -723,8 +723,8 @@ Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. Set this option to 0 to make the transfer start from the beginning (effectively disabling resume). .IP CURLOPT_RESUME_FROM_LARGE -Pass an curl_off_t as parameter. It contains the offset in number of bytes -that you want the transfer to start from. (Added in 7.11.0) +Pass a curl_off_t as parameter. It contains the offset in number of bytes that +you want the transfer to start from. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be user instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST -- cgit v1.2.1 From 3838745fdbe6444ca0290fd63b48f2992f1662a0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 17 Aug 2004 12:37:35 +0000 Subject: mention the reset function --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 29b798584..06833a050 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -41,7 +41,8 @@ typical application uses many curl_easy_setopt() calls in the setup phase. Options set with this function call are valid for all forthcoming transfers performed using this \fIhandle\fP. The options are not in any way reset between transfers, so if you want subsequent transfers with different options, -you must change them between the transfers. +you must change them between the transfers. You can optionally reset all +options back to internal default with \fIcurl_easy_reset(3)\fP. \fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be copied by the library. Instead you should keep them available until libcurl no @@ -994,4 +995,4 @@ If you try to set an option that libcurl doesn't know about, perhaps because the library is too old to support it or the option was removed in a recent version, this function will return \fICURLE_FAILED_INIT\fP. .SH "SEE ALSO" -.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " +.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), " -- cgit v1.2.1 From e139e49826a00819e7897b40e851a4c5d2b62d67 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 17 Aug 2004 12:39:10 +0000 Subject: see also the reset function --- docs/libcurl/curl_easy_init.3 | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index f7776b411..62a6fbc50 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -1,5 +1,3 @@ -.\" You can view this file with: -.\" nroff -man [file] .\" $Id$ .\" .TH curl_easy_init 3 "4 March 2002" "libcurl 7.8.1" "libcurl Manual" @@ -20,4 +18,4 @@ initializes curl and this call \fBMUST\fP have a corresponding call to If this function returns NULL, something went wrong and you cannot use the other curl functions. .SH "SEE ALSO" -.BR curl_easy_cleanup "(3), " curl_global_init "(3) +.BR curl_easy_cleanup "(3), " curl_global_init "(3), " curl_easy_reset "(3)" -- cgit v1.2.1 From 46313be2f5bf8bfeda5122fb756d2cdd050329d1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Aug 2004 14:04:38 +0000 Subject: added more header info for PUT and POST requests --- docs/libcurl/curl_easy_setopt.3 | 31 ++++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 06833a050..6c1eea2f1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -483,6 +483,15 @@ options. You can override the default POST Content-Type: header by setting your own with \fICURLOPT_HTTPHEADER\fP. +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. + +If you use POST to a HTTP 1.1 server, you can send data without knowing the +size before starting the POST if you use chunked encoding. You enable this by +adding a header like "Transfer-Encoding: chunked" with +\fICURLOPT_HTTPHEADER\fP. With HTTP 1.0 or without chunked transfer, you must +specify the size in the request. + NOTE: if you have issued a POST request and want to make a HEAD or GET instead, you must explictly pick the new request type using \fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. @@ -497,6 +506,9 @@ set that Content-Type by default when this option is used), which is the most commonly used one by HTML forms. See also the \fICURLOPT_POST\fP. Using \fICURLOPT_POSTFIELDS\fP implies \fICURLOPT_POST\fP. +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. + \fBNote:\fP to make multipart/formdata posts (aka rfc1867-posts), check out the \fICURLOPT_HTTPPOST\fP option. .IP CURLOPT_POSTFIELDSIZE @@ -517,6 +529,9 @@ list of 'struct HttpPost' structs properly filled in. The best and most elegant way to do this, 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. + +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. .IP CURLOPT_REFERER Pass a pointer to a zero terminated string as parameter. It will be used to set the Referer: header in the http request sent to the remote server. This @@ -762,9 +777,19 @@ libcurl what the expected size of the infile is. This value should be passed as a curl_off_t. (Added in 7.11.0) .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The -\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE_LARGE\fP are also interesting -for uploads. If the protocol is HTTP, uploading means using the PUT request -unless you tell libcurl otherwise. +\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZEE\fP or +\fICURLOPT_INFILESIZE_LARGE\fP are also interesting for uploads. If the +protocol is HTTP, uploading means using the PUT request unless you tell +libcurl otherwise. + +Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. + +If you use PUT to a HTTP 1.1 server, you can upload data without knowing the +size before starting the transfer if you use chunked encoding. You enable this +by adding a header like "Transfer-Encoding: chunked" with +\fICURLOPT_HTTPHEADER\fP. With HTTP 1.0 or without chunked transfer, you must +specify the size. .IP CURLOPT_MAXFILESIZE Pass a long as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, -- cgit v1.2.1 From dbacc81af747f68e07b30b77b2c30161cefef08d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Aug 2004 14:41:54 +0000 Subject: added note about WRITEFUNCTION now being called with zero bytes if the file to be transfered is empty --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6c1eea2f1..165397641 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -93,6 +93,9 @@ of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library and it will abort the transfer and return \fICURLE_WRITE_ERROR\fP. +This function may be called with zero bytes data if the transfered file is +empty. + Set the \fIstream\fP argument with the \fICURLOPT_WRITEDATA\fP option. \fBNOTE:\fP you will be passed as much data as possible in all invokes, but -- cgit v1.2.1 From d869b51a57c39cbc25df0df7cee375f608ec2e82 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Aug 2004 14:46:43 +0000 Subject: Expect: 100-continue info added --- docs/libcurl/curl_formadd.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 961bfbf26..366e6b07f 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -26,6 +26,9 @@ NULL in the first call to this function. All list-data will be allocated by the function itself. You must call \fIcurl_formfree\fP after the form post has been done to free the resources again. +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. + First, there are some basics you need to understand about multipart/formdata posts. Each part consists of at least a NAME and a CONTENTS part. If the part is made for file upload, there are also a stored CONTENT-TYPE and a -- cgit v1.2.1 From 49746d1dceb286a2852018501d0f45168ccd969f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 24 Aug 2004 20:36:38 +0000 Subject: returned memory should not be freed --- docs/libcurl/curl_easy_getinfo.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index ca1c287d4..dcf993f04 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -19,6 +19,9 @@ this documentation describes further down). The data pointed-to will be filled in accordingly and can be relied upon only if the function returns CURLE_OK. This function is intended to get used *AFTER* a performed transfer, all results from this function are undefined until the transfer is completed. + +You should not free the memory returned by this function unless it is +explictly mentioned below. .SH AVAILABLE INFORMATION The following information can be extracted: .IP CURLINFO_EFFECTIVE_URL -- cgit v1.2.1 From 811dfd710ba2ad43a82019a0aa33d8b1eb4179a4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 31 Aug 2004 06:03:16 +0000 Subject: mention when the function was added to the lib --- docs/libcurl/curl_easy_strerror.3 | 2 ++ docs/libcurl/curl_multi_strerror.3 | 2 ++ docs/libcurl/curl_share_strerror.3 | 2 ++ 3 files changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 index eb7cecc4c..e733da62d 100644 --- a/docs/libcurl/curl_easy_strerror.3 +++ b/docs/libcurl/curl_easy_strerror.3 @@ -12,6 +12,8 @@ curl_easy_strerror - return string describing error code .SH DESCRIPTION The curl_easy_strerror() function returns a string describing the CURLcode error code passed in the argument \fIerrornum\fP. + +This function was added in libcurl 7.12.0 .SH RETURN VALUE A pointer to a zero terminated string. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 index f2fea3b92..8145c63f9 100644 --- a/docs/libcurl/curl_multi_strerror.3 +++ b/docs/libcurl/curl_multi_strerror.3 @@ -12,6 +12,8 @@ curl_multi_strerror - return string describing error code .SH DESCRIPTION The curl_multi_strerror() function returns a string describing the CURLMcode error code passed in the argument \fIerrornum\fP. + +This function was added in libcurl 7.12.0 .SH RETURN VALUE A pointer to a zero terminated string. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 index 35fa4db8c..20c008d21 100644 --- a/docs/libcurl/curl_share_strerror.3 +++ b/docs/libcurl/curl_share_strerror.3 @@ -12,6 +12,8 @@ curl_share_strerror - return string describing error code .SH DESCRIPTION The curl_share_strerror() function returns a string describing the CURLSHcode error code passed in the argument \fIerrornum\fP. + +This function was added in libcurl 7.12.0 .SH RETURN VALUE A pointer to a zero terminated string. .SH "SEE ALSO" -- cgit v1.2.1 From 66077ae48b163cb717dd1093708c79c0f21fc6aa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 1 Sep 2004 09:24:01 +0000 Subject: fix formatting flaw --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 165397641..5159953ed 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -480,7 +480,7 @@ used POST method). Use the \fICURLOPT_POSTFIELDS\fP option to specify what data to post and \fICURLOPT_POSTFIELDSIZE\fP to set the data size. Optionally, you can provide -data to POST using the \fICURLOPT_READFUNCTION\FP and \fICURLOPT_READDATA\fP +data to POST using the \fICURLOPT_READFUNCTION\fP and \fICURLOPT_READDATA\fP options. You can override the default POST Content-Type: header by setting your own -- cgit v1.2.1 From 5f3fa92062a0c41611ae28e761049d0b2fe6d777 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 1 Sep 2004 09:25:19 +0000 Subject: minor edit of HTTPGET --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5159953ed..ef45be1ed 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -627,7 +627,7 @@ cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only. .IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back -to GET. Only really usable if POST, PUT or a custom request have been used +to GET. usable if a POST, HEAD, PUT or a custom request have been used previously using the same curl handle. .IP CURLOPT_HTTP_VERSION Pass a long, set to one of the values described below. They force libcurl to -- cgit v1.2.1 From 75a6fdeb584d59df364a98f5fcadebe9bbd27307 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 1 Sep 2004 12:05:59 +0000 Subject: added more info on the nobody --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ef45be1ed..23e66d0b8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -770,6 +770,10 @@ can be used after a transfer to extract the received time (if any). A non-zero parameter tells the library to not include the body-part in the output. This is only relevant for protocols that have separate header and body parts. On HTTP(S) servers, this will make libcurl do a HEAD request. + +To change back to GET, you should use \fICURLOPT_HTTPGET\fP. To change back to +POST, you should use \fICURLOPT_POST\fP. Setting \fICURLOPT_NOBODY\fP to zero +has no effect. .IP CURLOPT_INFILESIZE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed -- cgit v1.2.1 From 5f60188b8adbe5055b0780df36caf3e209d06531 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 2 Sep 2004 20:42:44 +0000 Subject: use the correct struct name in the example --- docs/libcurl/curl_formadd.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 366e6b07f..c8055afb9 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -129,8 +129,8 @@ defines. .SH EXAMPLE .nf - struct HttpPost* post = NULL; - struct HttpPost* last = NULL; + struct curl_httppost* post = NULL; + struct curl_httppost* last = NULL; char namebuffer[] = "name buffer"; long namelength = strlen(namebuffer); char buffer[] = "test buffer"; -- cgit v1.2.1 From 428741d7cfe2ca4bed0d8dc5872ccef6af0da19c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 2 Sep 2004 21:05:56 +0000 Subject: clarify CURLE_SSL_CERTPROBLEM somewhat --- docs/libcurl/libcurl-errors.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 0c37c3d76..de28c2d41 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -174,7 +174,7 @@ Failure with receiving network data. .IP "CURLE_SHARE_IN_USE (57)" Share is in use .IP "CURLE_SSL_CERTPROBLEM (58)" -problem with the local certificate +problem with the local client certificate .IP "CURLE_SSL_CIPHER (59)" couldn't use specified cipher .IP "CURLE_SSL_CACERT (60)" -- cgit v1.2.1 From f71b3f48a16e5d62079ad013adb2b96560a1c1fe Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 15 Sep 2004 07:28:04 +0000 Subject: Replaced the former date parser with a rewrite. No more yacc/bison needed. --- docs/libcurl/curl_getdate.3 | 116 ++++++++++++++++++++++++-------------------- 1 file changed, 64 insertions(+), 52 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 6e936cf13..65a0e738b 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -4,35 +4,36 @@ .\" .TH curl_getdate 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" .SH NAME -curl_getdate - Convert an date in a ASCII string to number of seconds since -January 1, 1970 +curl_getdate - Convert an date string to number of seconds since January 1, +1970 .SH SYNOPSIS .B #include .sp -.BI "time_t curl_getdate(char *" datestring ", time_t *"now" ); +.BI "time_t curl_getdate(char *" datestring ", time_t *"now" );" .ad .SH DESCRIPTION -This function returns the number of seconds since January 1st 1970, for the -date and time that the -.I datestring -parameter specifies. The -.I now -parameter is there and should hold the current time to allow the datestring to -specify relative dates/times. Read further in the date string parser section -below. +This function returns the number of seconds since January 1st 1970 in the UTC +time zone, for the date and time that the \fIdatestring\fP parameter +specifies. The \fInow\fP parameter is not used, pass a NULL there. + +\fBNOTE:\fP This function was rewritten for the 7.12.2 release and this +documentation covers the functionality of the new one. The new one is not +feature-complete with the old one, but most of the formats supported by the +new one was supported by the old too. .SH PARSING DATES AND TIMES -A "date" is a string, possibly empty, containing many items separated by -whitespace. The whitespace may be omitted when no ambiguity arises. The -empty string means the beginning of today (i.e., midnight). Order of the -items is immaterial. A date string may contain many flavors of items: +A "date" is a string containing several items separated by whitespace. The +order of the items is immaterial. A date string may contain many flavors of +items: .TP 0.8i .B calendar date items -This can be specified in a number of different ways. Including 1970-09-17, 70-9-17, 70-09-17, 9/17/72, 24 September 1972, 24 Sept 72, 24 Sep 72, Sep 24, 1972, 24-sep-72, 24sep72. -The year can also be omitted, for example: 9/17 or "sep 17". +Can be specified several ways. Month names can only be three-letter +abbrivations, 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 -This string specifies the time on a given day. Syntax supported includes: -18:19:0, 18:19, 6:19pm, 18:19-0500 (for specifying the time zone as well). +This string specifies the time on a given day. You must specify it with 6 +digits with two colons: HH:MM:SS. To not include the time in a date string, +will make the function assume 00:00:00. Example: 18:19:21. .TP .B time zone items Specifies international time zone. There are a few acronyms supported, but in @@ -40,41 +41,52 @@ general you should instead use the specific relative time compared to UTC. Supported formats include: -1200, MST, +0100. .TP .B day of the week items -Specifies a day of the week. If this is mentioned alone it means that day of -the week in the future. - -Days of the week may be spelled out in full: `Sunday', `Monday', etc or they -may be abbreviated to their first three letters, optionally followed by a -period. The special abbreviations `Tues' for `Tuesday', `Wednes' for -`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed. - -A number may precede a day of the week item to move forward supplementary -weeks. It is best used in expression like `third monday'. In this context, -`last DAY' or `next DAY' is also acceptable; they move one week before or -after the day that DAY by itself would represent. -.TP -.B relative items -A relative item adjusts a date (or the current date if none) forward or -backward. Example syntax includes: "1 year", "1 year ago", "2 days", "4 -weeks". - -The string `tomorrow' is worth one day in the future (equivalent to `day'), -the string `yesterday' is worth one day in the past (equivalent to `day ago'). +Specifies a day of the week. Days of the week may be spelled out in full: +`Sunday', `Monday', etc or they may be abbreviated to their first three +letters. This is usually not info that adds anything. .TP .B pure numbers -If the decimal number is of the form YYYYMMDD and no other calendar date item -appears before it in the date string, then YYYY is read as the year, MM as the -month number and DD as the day of the month, for the specified calendar date. +If a decimal number of the form YYYYMMDD appears, then YYYY is read as the +year, MM as the month number and DD as the day of the month, for the specified +calendar date. .PP +.SH EXAMPLES +.nf +Sun, 06 Nov 1994 08:49:37 GMT +Sunday, 06-Nov-94 08:49:37 GMT +Sun Nov 6 08:49:37 1994 +06 Nov 1994 08:49:37 GMT +06-Nov-94 08:49:37 GMT +Nov 6 08:49:37 1994 +06 Nov 1994 08:49:37 +06-Nov-94 08:49:37 +1994 Nov 6 08:49:37 +GMT 08:49:37 06-Nov-94 Sunday +94 6 Nov 08:49:37 +1994 Nov 6 +06-Nov-94 +Sun Nov 6 94 +1994.Nov.6 +Sun/Nov/6/94/GMT +Sun, 06 Nov 1994 08:49:37 CET +06 Nov 1994 08:49:37 EST +Sun, 12 Sep 2004 15:05:58 -0700 +Sat, 11 Sep 2004 21:32:11 +0200 +20040912 15:05:58 -0700 +20040911 +0200 +.fi +.SH STANDARDS +This parser was written to handle date formats specified in RFC 822 (including +the update in RFC 1123) using time zone name or time zone delta and RFC 850 +(obsoleted by RFC 1036) and ANSI C's asctime() format. These formats are the +only ones RFC2616 says HTTP applications may use. .SH RETURN VALUE -This function returns zero when it fails to parse the date string. Otherwise -it returns the number of seconds as described. -.SH AUTHORS -Originally written by Steven M. Bellovin while at the -University of North Carolina at Chapel Hill. Later tweaked by a couple of -people on Usenet. Completely overhauled by Rich $alz and Jim -Berets in August, 1990. +This function returns -1 when it fails to parse the date string. Otherwise it +returns the number of seconds as described. +.SH REWRITE +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 Bison could make it thread-safe! -It has been modified extensively since imported to curl. -.SH "SEE ALSO" -.BR GNU date(1) +The rewrite was done for 7.12.2. The new one is much smaller and use simpler +code. -- cgit v1.2.1 From 2544c7808309b1cd998688c3b845d9cc1269a327 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 16 Sep 2004 14:26:04 +0000 Subject: Bertrand Demiddelaer's correction --- docs/libcurl/curl_share_cleanup.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 index b668d072f..d45e0bbcc 100644 --- a/docs/libcurl/curl_share_cleanup.3 +++ b/docs/libcurl/curl_share_cleanup.3 @@ -6,7 +6,7 @@ curl_share_cleanup - Clean up a shared object .SH SYNOPSIS .B #include .sp -.BI "CURLSHcode curl_share_cleanup( );" +.BI "CURLSHcode curl_share_cleanup(CURLSH *" share_handle ");" .ad .SH DESCRIPTION This function deletes a shared object. The share handle cannot be used anymore -- cgit v1.2.1 From 6a06667cc0a6915510a7f3d789a0bcf470a9b7d8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 16 Sep 2004 21:45:16 +0000 Subject: Added CURLOPT_FTPSSLAUTH --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 23e66d0b8..3e0bfcf13 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -720,6 +720,18 @@ Require SSL for the control connection or fail with \fICURLE_FTP_SSL_FAILED\fP. .IP CURLFTPSSL_ALL Require SSL for all communication or fail with \fICURLE_FTP_SSL_FAILED\fP. .RE +.IP CURLOPT_FTPSSLAUTH +Pass a long using one of the values from below, to alter how libcurl issues +\&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see +\fICURLOPT_FTP_SSL\fP). +.RS +.IP CURLFTPAUTH_DEFAULT +Allow libcurl to decide +.IP CURLFTPAUTH_SSL +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" +.RE .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A non-zero parameter tells the library to use ASCII mode for ftp transfers, -- cgit v1.2.1 From be1cece69b2bc7b73c07166ec5e164fabdac1c95 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 30 Sep 2004 21:01:23 +0000 Subject: - Larry Campbell added CURLINFO_OS_ERRNO to curl_easy_getinfo() that allows an app to retrieve the errno variable after a (connect) failure. It will make sense to provide this for more failures in a more generic way, but let's start like this. --- docs/libcurl/curl_easy_getinfo.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index dcf993f04..fba414a7f 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -110,6 +110,8 @@ CURLOPT_HTTPAUTH option for \fIcurl_easy_setopt(3)\fP. (Added in 7.10.8) .IP CURLINFO_PROXYAUTH_AVAIL Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available for your proxy authentication. (Added in 7.10.8) +.IP CURLINFO_OS_ERRNO +Pass a pointer to a long to receive the errno variable from a connect failure. .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. -- cgit v1.2.1 From bb48ccedd7c8eb9eeab1d4d900f011ebdda1eb4b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 1 Oct 2004 06:43:48 +0000 Subject: mention when this option was added --- docs/libcurl/curl_easy_getinfo.3 | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index fba414a7f..4176e49ab 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -112,6 +112,7 @@ Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available for your proxy authentication. (Added in 7.10.8) .IP CURLINFO_OS_ERRNO Pass a pointer to a long to receive the errno variable from a connect failure. +(Added in 7.12.2) .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. -- cgit v1.2.1 From f4f961c4eacdb3036bf8c4f7ba8cb959ee3d61ab Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 3 Oct 2004 17:38:57 +0000 Subject: added info about how users get info (like the CURLcode return code) from individual transfers --- docs/libcurl/curl_multi_perform.3 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 263550df2..75f72c5d8 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -16,6 +16,13 @@ function does not require that there actually is any data available for reading or that data can be written, it can be called just in case. It will write the number of handles that still transfer data in the second argument's integer-pointer. + +When you call curl_multi_perform() and the amount of \fIrunning_handles\fP is +changed from the previous call (or is less than the amount of easy handles +you've added to the multi handle), you know that there is one or more +transfers less "running". You can then call \fIcurl_multi_info_read(3)\fP to +get information about each individual completed transfer, and that returned +info includes CURLcode and more. .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. @@ -34,4 +41,5 @@ file descriptors, then it'll wait for action on them using select() and as soon as one or more of them are ready, \fIcurl_multi_perform(3)\fP gets called. .SH "SEE ALSO" -.BR curl_multi_cleanup "(3)," curl_multi_init "(3)," curl_multi_fdset "(3)" +.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " +.BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" -- cgit v1.2.1 From f4bef25b5eede9ea17f237ebae52c2f89cc211cd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Oct 2004 15:30:08 +0000 Subject: CURLINFO_NUM_CONNECTS and more --- docs/libcurl/curl_easy_getinfo.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 4176e49ab..ce6bab9b2 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -113,6 +113,13 @@ method(s) available for your proxy authentication. (Added in 7.10.8) .IP CURLINFO_OS_ERRNO Pass a pointer to a long to receive the errno variable from a connect failure. (Added in 7.12.2) +.IP CURLINFO_NUM_CONNECTS +Pass a pointer to a long to receive how many new connections libcurl had to +create to achieve the previous transfer (only the successful connects are +counted). Combined with \fICURLINFO_REDIRECT_COUNT\fP you are able to know +how many times libcurl successfully reused existing connection(s) or not. See +the Connection Options of \fIcurl_easy_setopt(3)\fP to see how libcurl tries +to make persistent connections to save time. (Added in 7.12.3) .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. -- cgit v1.2.1 From 34089c93bb83362e395dbca441c3b49e06e7c4af Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 25 Oct 2004 11:05:37 +0000 Subject: format update --- docs/libcurl/curl_formadd.3 | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index c8055afb9..693ca0f2e 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -35,28 +35,28 @@ is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. Below here, we'll discuss on what options you use to set these properties in the parts you want to add to your post. .SH OPTIONS -.B CURLFORM_COPYNAME +.IP CURLFORM_COPYNAME followed by string is used to set the name of this part. libcurl copies the given data, so your application doesn't need to keep it around after this function call. If the name isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_NAMELENGTH\fP. -.B CURLFORM_PTRNAME +.IP CURLFORM_PTRNAME followed by a string is used for the name of this part. libcurl will use the pointer and refer to the data in your application, you must make sure it remains until curl no longer needs it. If the name isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_NAMELENGTH\fP. -.B CURLFORM_COPYCONTENTS +.IP CURLFORM_COPYCONTENTS followed by a string is used for the contents of this part, the actual data to send away. libcurl copies the given data, so your application doesn't need to keep it around after this function call. If the data isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. -.B CURLFORM_PTRCONTENTS +.IP CURLFORM_PTRCONTENTS followed by a string is used for the contents of this part, the actual data to send away. libcurl will use the pointer and refer to the data in your application, you must make sure it remains until curl no longer needs it. If @@ -64,11 +64,14 @@ the data isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. -.B CURLFORM_FILECONTENT +.IP CURLFORM_CONTENTSLENGTH +followed by a long setting the length of the contents. + +.IP CURLFORM_FILECONTENT followed by a file name, makes that file read and the contents will be used in as data in this part. -.B CURLFORM_FILE +.IP CURLFORM_FILE followed by a file name, makes this part a file upload part. It sets the file name field to the actual file name used here, it gets the contents of the file and passes as data and sets the content-type if the given file match one of @@ -77,32 +80,33 @@ send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename (and each CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE). -.B CURLFORM_CONTENTTYPE +.IP CURLFORM_CONTENTTYPE followed by a pointer to a string with a content-type will make curl use this given content-type for this file upload part, possibly instead of an internally chosen one. -.B CURLFORM_FILENAME +.IP CURLFORM_FILENAME followed by a pointer to a string to a name, will make libcurl use the given name in the file upload part, instead of the actual file name given to \fICURLFORM_FILE\fP. -.B BCURLFORM_BUFFER +.IP BCURLFORM_BUFFER followed by a string, tells libcurl that a buffer is to be used to upload data instead of using a file. The given string is used as the value of the file name field in the content header. -.B CURLFORM_BUFFERPTR +.IP CURLFORM_BUFFERPTR followed by a pointer to a data area, tells libcurl the address of the buffer containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The buffer containing this data must not be freed until after -\fIcurl_easy_cleanup(3)\fP is called. +\fIcurl_easy_cleanup(3)\fP is called. You must also use +\fICURLFORM_BUFFERLENGTH\fP to set the length of the given buffer area. -.B CURLFORM_BUFFERLENGTH +.IP CURLFORM_BUFFERLENGTH followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area, tells libcurl the length of the buffer to upload. -.B CURLFORM_ARRAY +.IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as its value. Each curl_forms structure element has a CURLformoption and a char @@ -110,7 +114,7 @@ pointer. The final element in the array must be a CURLFORM_END. All available options can be used in an array, except the CURLFORM_ARRAY option itself! The last argument in such an array must always be \fBCURLFORM_END\fP. -.B CURLFORM_CONTENTHEADER +.IP CURLFORM_CONTENTHEADER specifies extra headers for the form POST section. This takes a curl_slist prepared in the usual way using \fBcurl_slist_append\fP and appends the list of headers to those libcurl automatically generates. The list must exist while -- cgit v1.2.1 From cd73a733c78b7ab7b4e3ccaca9350bbcce124142 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 11 Nov 2004 09:26:09 +0000 Subject: dates from 2038 or later now return 0x7fffffff when 32 bit time_t is used --- docs/libcurl/curl_getdate.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 65a0e738b..9d13433a3 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -83,6 +83,9 @@ only ones RFC2616 says HTTP applications may use. .SH RETURN VALUE This function returns -1 when it fails to parse the date string. Otherwise it returns the number of seconds as described. + +If the year is larger than 2037 on systems with 32 bit time_t, this function +will return 0x7fffffff (since that is the largest possible 31 bit number). .SH REWRITE 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 -- cgit v1.2.1 From c3323b1902ad1885fe9863e6c2e9aaf62579a5be Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 11 Nov 2004 23:11:32 +0000 Subject: clarify and update according to commit made just now --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3e0bfcf13..71d1464a9 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -479,9 +479,13 @@ application/x-www-form-urlencoded" header. (This is by far the most commonly used POST method). Use the \fICURLOPT_POSTFIELDS\fP option to specify what data to post and -\fICURLOPT_POSTFIELDSIZE\fP to set the data size. Optionally, you can provide -data to POST using the \fICURLOPT_READFUNCTION\fP and \fICURLOPT_READDATA\fP -options. +\fICURLOPT_POSTFIELDSIZE\fP to set the data size. + +Optionally, you can provide data to POST using the \fICURLOPT_READFUNCTION\fP +and \fICURLOPT_READDATA\fP options but then you must make sure to not set +\fICURLOPT_POSTFIELDS\fP to anything but NULL. When providing data with a +callback, you must transmit it using chunked transfer-encoding or you must set +the size of the data with the \fICURLOPT_POSTFIELDSIZE\f option. You can override the default POST Content-Type: header by setting your own with \fICURLOPT_HTTPHEADER\fP. @@ -518,7 +522,7 @@ the \fICURLOPT_HTTPPOST\fP option. If you want to post data to the server without letting libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If this -size is set to zero, the library will use strlen() to get the size. +size is set to -1, the library will use strlen() to get the size. .IP CURLOPT_POSTFIELDSIZE_LARGE Pass a curl_off_t as parameter. Use this to set the size of the \fICURLOPT_POSTFIELDS\fP data to prevent libcurl from doing strlen() on the -- cgit v1.2.1 From 1b02ad5e8a35ccd682429e387ccb63022ca2339a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Nov 2004 06:42:30 +0000 Subject: format mistake fixed --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 71d1464a9..423858017 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -485,7 +485,7 @@ Optionally, you can provide data to POST using the \fICURLOPT_READFUNCTION\fP and \fICURLOPT_READDATA\fP options but then you must make sure to not set \fICURLOPT_POSTFIELDS\fP to anything but NULL. When providing data with a callback, you must transmit it using chunked transfer-encoding or you must set -the size of the data with the \fICURLOPT_POSTFIELDSIZE\f option. +the size of the data with the \fICURLOPT_POSTFIELDSIZE\fP option. You can override the default POST Content-Type: header by setting your own with \fICURLOPT_HTTPHEADER\fP. -- cgit v1.2.1 From 86f059dcfbb32ee7ee25c7232457c558ea9f8c4f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Nov 2004 21:41:21 +0000 Subject: tiny format fix for nicer man output --- docs/libcurl/curl_getdate.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 9d13433a3..9af2f8509 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -9,7 +9,7 @@ curl_getdate - Convert an date string to number of seconds since January 1, .SH SYNOPSIS .B #include .sp -.BI "time_t curl_getdate(char *" datestring ", time_t *"now" );" +.BI "time_t curl_getdate(char *" datestring ", time_t *"now " );" .ad .SH DESCRIPTION This function returns the number of seconds since January 1st 1970 in the UTC -- cgit v1.2.1 From 3e1caa61859a6057a65eb7c1585d47e05026c4f2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 24 Nov 2004 16:11:35 +0000 Subject: HTTP "auth done right". See lib/README.httpauth --- docs/libcurl/curl_easy_setopt.3 | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 423858017..e75ae4a2c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "12 Mar 2004" "libcurl 7.11.1" "libcurl Manual" +.TH curl_easy_setopt 3 "21 Nov 2004" "libcurl 7.12.3" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -142,6 +142,18 @@ don't specify a read callback, this must be a valid FILE *. This option is also known with the older name \fICURLOPT_INFILE\fP, the name \fICURLOPT_READDATA\fP was introduced in 7.9.7. +.IP CURLOPT_IOCTLFUNCTION +Function pointer that should match the \fIcurl_ioctl_callback\fP prototype +found in \fI\fP. This function gets called by libcurl when +something special I/O-related needs to be done that the library can't do by +itself. For now, rewinding the read data stream is the only action it can +request. The rewinding of the read data stream may be necessary when doing a +HTTP PUT or POST with a multi-pass authentication method. (Opion added in +7.12.3) +.IP CURLOPT_IOCTLDATA +Pass a pointer that will be untouched by libcurl and passed as the 3rd +argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP. (Option +added in 7.12.3) .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of -- cgit v1.2.1 From 0966ddafaa7f044c2a4d972ba416dc4ec96f1ab4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 29 Nov 2004 21:25:07 +0000 Subject: As reported in Mandrake's bug tracker bug 12285 (http://qa.mandrakesoft.com/show_bug.cgi?id=12285), when connecting to an IPv6 host with FTP, --disable-epsv (or --disable-eprt) effectively disables the ability to transfer a file. Now, when connected to an FTP server with IPv6, these FTP commands can't be disabled even if asked to with the available libcurl options. --- docs/libcurl/curl_easy_setopt.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e75ae4a2c..0290d5b2c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "21 Nov 2004" "libcurl 7.12.3" "libcurl Manual" +.TH curl_easy_setopt 3 "29 Nov 2004" "libcurl 7.12.3" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -706,11 +706,15 @@ LPRT) command when doing active FTP downloads (which is enabled by \fICURLOPT_FTPPORT\fP). Using EPRT means that it will first attempt to use EPRT and then LPRT before using PORT, but if you pass FALSE (zero) to this option, it will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5) + +If the server is an IPv6 host, this option will have no effect as of 7.12.3. .IP CURLOPT_FTP_USE_EPSV Pass a long. If the value is non-zero, it tells curl to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. + +If the server is an IPv6 host, this option will have no effect as of 7.12.3. .IP CURLOPT_FTP_CREATE_MISSING_DIRS Pass a long. If the value is non-zero, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working -- cgit v1.2.1 From 4b1c0bd1e7aefeee2a2116a9e56fbfb4eb11b2e4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 3 Dec 2004 11:25:06 +0000 Subject: CURLOPT_FTPSSLAUTH was added in 7.12.2 --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0290d5b2c..35a2a87d0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -743,7 +743,7 @@ Require SSL for all communication or fail with \fICURLE_FTP_SSL_FAILED\fP. .IP CURLOPT_FTPSSLAUTH Pass a long using one of the values from below, to alter how libcurl issues \&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see -\fICURLOPT_FTP_SSL\fP). +\fICURLOPT_FTP_SSL\fP). (Added in 7.12.2) .RS .IP CURLFTPAUTH_DEFAULT Allow libcurl to decide -- cgit v1.2.1 From 5c14b3be6dc7fe44ee33642c4e32541e01a6a260 Mon Sep 17 00:00:00 2001 From: Gisle Vanem Date: Mon, 13 Dec 2004 20:14:04 +0000 Subject: Document CURLINFO_SSL_ENGINES and "--engine". --- docs/libcurl/curl_easy_getinfo.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index ce6bab9b2..89c4895c9 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -89,6 +89,11 @@ than one request if FOLLOWLOCATION is true. Pass a pointer to a long to receive the result of the certification verification that was requested (using the CURLOPT_SSL_VERIFYPEER option to \fIcurl_easy_setopt(3)\fP). +.IP CURLINFO_SSL_ENGINES +Pass the address of a 'struct curl_slist *' to receive a linked-list of +OpenSSL crypto-engines supported. Note that engines are normally implemented +in separate dynamic libraries. Hence not all the returned engines may be +available at run-time. .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD Pass a pointer to a double to receive the content-length of the download. This is the value read from the Content-Length: field. -- cgit v1.2.1 From 9359498b065a98361c25a9635aac1284ea261903 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 14 Dec 2004 22:47:13 +0000 Subject: clarify that the app must free the engine list --- docs/libcurl/curl_easy_getinfo.3 | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 89c4895c9..488e5cfc8 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_getinfo 3 "20 Aug 2003" "libcurl 7.10.8" "libcurl Manual" +.TH curl_easy_getinfo 3 "14 Dec 2004" "libcurl 7.12.3" "libcurl Manual" .SH NAME curl_easy_getinfo - extract information from a curl handle .SH SYNOPSIS @@ -12,13 +12,12 @@ curl_easy_getinfo - extract information from a curl handle .SH DESCRIPTION Request internal information from the curl session with this function. The -third argument -.B MUST -be a pointer to a long, a pointer to a char * or a pointer to a double (as -this documentation describes further down). The data pointed-to will be -filled in accordingly and can be relied upon only if the function returns -CURLE_OK. This function is intended to get used *AFTER* a performed transfer, -all results from this function are undefined until the transfer is completed. +third argument \fBMUST\fP be a pointer to a long, a pointer to a char *, a +pointer to a struct curl_slist * or a pointer to a double (as this +documentation describes further down). The data pointed-to will be filled in +accordingly and can be relied upon only if the function returns CURLE_OK. +This function is intended to get used AFTER a performed transfer, all results +from this function are undefined until the transfer is completed. You should not free the memory returned by this function unless it is explictly mentioned below. @@ -93,7 +92,9 @@ verification that was requested (using the CURLOPT_SSL_VERIFYPEER option to Pass the address of a 'struct curl_slist *' to receive a linked-list of OpenSSL crypto-engines supported. Note that engines are normally implemented in separate dynamic libraries. Hence not all the returned engines may be -available at run-time. +available at run-time. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP +on the list pointer once you're done with it, as libcurl will not free the +data for you. (Added in 7.12.3) .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD Pass a pointer to a double to receive the content-length of the download. This is the value read from the Content-Length: field. -- cgit v1.2.1 From 6e43a4ccce73e7d58e62e8097eded7b63ddf4c19 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 18 Dec 2004 10:24:49 +0000 Subject: Jean-Marc Ranger pointed out that the returned data doesn't survive a call to curl_multi_remove_handle() either. --- docs/libcurl/curl_multi_info_read.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 26b9e40b3..304be87b5 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_info_read 3 "27 Feb 2002" "libcurl 7.10.3" "libcurl Manual" +.TH curl_multi_info_read 3 "18 Dec 2004" "libcurl 7.10.3" "libcurl Manual" .SH NAME curl_multi_info_read - read multi stack informationals .SH SYNOPSIS @@ -21,7 +21,7 @@ integer pointed to with \fImsgs_in_queue\fP will contain the number of remaining messages after this function was called. The data the returned pointer points to will not survive calling -\fIcurl_multi_cleanup(3)\fP. +\fIcurl_multi_cleanup(3)\fP or \fIcurl_multi_remove_handle(3)\fP. The 'CURLMsg' struct is very simple and only contain very basic information. If more involved information is wanted, the particular "easy handle" in -- cgit v1.2.1 From 3acda85c2b11f24c594e81c340509bda8db5eed1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 22 Dec 2004 12:31:55 +0000 Subject: added CURLINFO_HTTP_CONNECTCODE --- docs/libcurl/curl_easy_getinfo.3 | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 488e5cfc8..8325aafde 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_getinfo 3 "14 Dec 2004" "libcurl 7.12.3" "libcurl Manual" +.TH curl_easy_getinfo 3 "22 Dec 2004" "libcurl 7.12.3" "libcurl Manual" .SH NAME curl_easy_getinfo - extract information from a curl handle .SH SYNOPSIS @@ -27,7 +27,13 @@ The following information can be extracted: Pass a pointer to a 'char *' to receive the last used effective URL. .IP CURLINFO_RESPONSE_CODE Pass a pointer to a long to receive the last received HTTP or FTP code. This -option was known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. +option was known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. This +will be zero if no server response code has been received. Note that a proxy's +CONNECT response should be read with \fICURLINFO_HTTP_CONNECTCODE\fP and not +this. +.IP CURLINFO_HTTP_CONNECTCODE +Pass a pointer to a long to receive the last received proxy response code to a +CONNECT request. .IP CURLINFO_FILETIME Pass a pointer to a long to receive the remote time of the retrieved document. If you get -1, it can be because of many reasons (unknown, the -- cgit v1.2.1 From c5b2e85b473f09ad25b1b3df78e50da1532a9ef8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 11 Jan 2005 20:22:44 +0000 Subject: Dan Torop cleaned up a few no longer used variables from David Phillips' select() overhaul fix. --- docs/libcurl/curl_multi_fdset.3 | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 2faaad298..e7e84fc3c 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -16,13 +16,9 @@ CURLMcode curl_multi_fdset(CURLM *multi_handle, .SH DESCRIPTION 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. The \fIcurl_multi_perform(3)\fI function should be called as soon as one +on. 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. -NOTE that once this call is made, you must not remove the sets you point to, -as libcurl will need to be able to read them. It needs them after select() -calls, to know if certain sockets are readable or writable. - You should also be aware that when doing select(), you should consider using a rather small (single-digit number of seconds) timeout and call \fIcurl_multi_perform\fP regularly - even if no activity has been seen on the -- cgit v1.2.1 From 6c038680f9a0de30f2a0b60c1e02bfb74006c851 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 21 Jan 2005 08:56:04 +0000 Subject: clarify the struct name for CURLOPT_HTTPPOST --- docs/libcurl/curl_easy_setopt.3 | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 35a2a87d0..7beecfd1e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -543,11 +543,10 @@ data to figure out the size. This is the large file version of the .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 HTTP post structs as parameter. The linked list should be a fully valid -list of 'struct HttpPost' structs properly filled in. The best and most -elegant way to do this, 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. +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. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. -- cgit v1.2.1 From 7e42cb61f75890832792c082510ec610f4c32cbe Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 21 Jan 2005 09:32:32 +0000 Subject: FTP third transfer support overhaul. See CHANGES for details. --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7beecfd1e..776e3da90 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2004, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2005, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "29 Nov 2004" "libcurl 7.12.3" "libcurl Manual" +.TH curl_easy_setopt 3 "20 Jan 2005" "libcurl 7.12.4" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -751,6 +751,18 @@ 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" .RE +.IP CURLOPT_SOURCE_URL +When set, it enables a FTP third party transfer, using the set URL as source, +while \fICURLOPT_URL\fP is the target. +.IP CURLOPT_SOURCE_USERPWD +Set "username:password" to use for the source connection when doing FTP third +party transfers. +.IP CURLOPT_SOURCE_QUOTE +Exactly like \fICURLOPT_QUOTE\fP, but for the source host. +.IP CURLOPT_SOURCE_PREQUOTE +Exactly like \fICURLOPT_PREQUOTE\fP, but for the source host. +.IP CURLOPT_SOURCE_POSTQUOTE +Exactly like \fICURLOPT_POSTQUOTE\fP, but for the source host. .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A non-zero parameter tells the library to use ASCII mode for ftp transfers, -- cgit v1.2.1 From 95656cd7f37f78e2010d422d53e00115728bafcd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 22 Jan 2005 22:24:17 +0000 Subject: If you're using libcurl as a win32 DLL, you MUST use the CURLOPT_WRITEFUNCTION if you set CURLOPT_WRITEDATA - or you will experience crashes. --- docs/libcurl/libcurl-tutorial.3 | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 14c8988c4..00ca9dfc0 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -195,20 +195,24 @@ and the function that gets invoked by libcurl. libcurl itself won't touch the data you pass with CURLOPT_WRITEDATA. libcurl offers its own default internal callback that'll take care of the data -if you don't set the callback with CURLOPT_WRITEFUNCTION. It will then simply -output the received data to stdout. You can have the default callback write -the data to a different file handle by passing a 'FILE *' to a file opened for -writing with the CURLOPT_WRITEDATA option. +if you don't set the callback with \fICURLOPT_WRITEFUNCTION\fP. It will then +simply output the received data to stdout. You can have the default callback +write the data to a different file handle by passing a 'FILE *' to a file +opened for writing with the \fICURLOPT_WRITEDATA\fP option. Now, we need to take a step back and have a deep breath. Here's one of those rare platform-dependent nitpicks. Did you spot it? On some platforms[2], libcurl won't be able to operate on files opened by the program. Thus, if you -use the default callback and pass in a an open file with CURLOPT_WRITEDATA, it -will crash. You should therefore avoid this to make your program run fine -virtually everywhere. +use the default callback and pass in a an open file with +\fICURLOPT_WRITEDATA\fP, it will crash. You should therefore avoid this to +make your program run fine virtually everywhere. -(CURLOPT_WRITEDATA was formerly known as CURLOPT_FILE. Both names still work -and do the same thing). +(\fICURLOPT_WRITEDATA\fP was formerly known as \fICURLOPT_FILE\fP. Both names +still work and do the same thing). + +If you're using libcurl as a win32 DLL, you MUST use the +\fICURLOPT_WRITEFUNCTION\fP if you set \fICURLOPT_WRITEDATA\fP - or you will +experience crashes. There are of course many more options you can set, and we'll get back to a few of them later. Let's instead continue to the actual transfer: -- cgit v1.2.1 From 53143910a1c2088a7a1fc71756ca84417cbe0d50 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 22 Jan 2005 22:43:04 +0000 Subject: \fI marked \fP more function calls etc. --- docs/libcurl/libcurl-tutorial.3 | 176 ++++++++++++++++++++-------------------- 1 file changed, 89 insertions(+), 87 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 00ca9dfc0..32766fc3c 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2004, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2005, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-tutorial 3 "18 Jun 2004" "libcurl" "libcurl programming" +.TH libcurl-tutorial 3 "22 Jan 2005" "libcurl" "libcurl programming" .SH NAME libcurl-tutorial \- libcurl programming tutorial .SH "Objective" @@ -94,9 +94,9 @@ use the library. Once for your program's entire life time. This is done using curl_global_init() and it takes one parameter which is a bit pattern that tells libcurl what to -initialize. Using CURL_GLOBAL_ALL will make it initialize all known internal -sub modules, and might be a good default option. The current two bits that -are specified are: +initialize. Using \fICURL_GLOBAL_ALL\fP will make it initialize all known +internal sub modules, and might be a good default option. The current two bits +that are specified are: .RS .IP "CURL_GLOBAL_WIN32" which only does anything on Windows machines. When used on @@ -113,17 +113,19 @@ application so if your program or another library already does this, this bit should not be needed. .RE -libcurl has a default protection mechanism that detects if curl_global_init() -hasn't been called by the time curl_easy_perform() is called and if that is -the case, libcurl runs the function itself with a guessed bit pattern. Please -note that depending solely on this is not considered nice nor very good. +libcurl has a default protection mechanism that detects if +\fIcurl_global_init(3)\fP hasn't been called by the time +\fIcurl_easy_perform(3)\fP is called and if that is the case, libcurl runs the +function itself with a guessed bit pattern. Please note that depending solely +on this is not considered nice nor very good. -When the program no longer uses libcurl, it should call curl_global_cleanup(), -which is the opposite of the init call. It will then do the reversed -operations to cleanup the resources the curl_global_init() call initialized. +When the program no longer uses libcurl, it should call +\fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It will +then do the reversed operations to cleanup the resources the +\fIcurl_global_init(3)\fP call initialized. -Repeated calls to curl_global_init() and curl_global_cleanup() should be -avoided. They should only be called once each. +Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP +should be avoided. They should only be called once each. .SH "Features libcurl Provides" It is considered best-practice to determine libcurl features run-time rather @@ -153,17 +155,18 @@ It returns an easy handle. Using that you proceed to the next step: setting up your preferred actions. A handle is just a logic entity for the upcoming transfer or series of transfers. -You set properties and options for this handle using curl_easy_setopt(). They -control how the subsequent transfer or transfers will be made. Options remain -set in the handle until set again to something different. Alas, multiple -requests using the same handle will use the same options. +You set properties and options for this handle using +\fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or +transfers will be made. Options remain set in the handle until set again to +something different. Alas, multiple requests using the same handle will use +the same options. Many of the options you set in libcurl are "strings", pointers to data terminated with a zero byte. Keep in mind that when you set strings with -curl_easy_setopt(), libcurl will not copy the data. It will merely point to -the data. You MUST make sure that the data remains available for libcurl to -use until finished or until you use the same option again to point to -something else. +\fIcurl_easy_setopt(3)\fP, libcurl will not copy the data. It will merely +point to the data. You MUST make sure that the data remains available for +libcurl to use until finished or until you use the same option again to point +to something else. One of the most basic properties to set in the handle is the URL. You set your preferred URL to transfer with CURLOPT_URL in a manner similar to: @@ -188,11 +191,11 @@ similar to this: You can control what data your function get in the forth argument by setting another property: - curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct); + curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct); Using that property, you can easily pass local data between your application and the function that gets invoked by libcurl. libcurl itself won't touch the -data you pass with CURLOPT_WRITEDATA. +data you pass with \fICURLOPT_WRITEDATA\fP. libcurl offers its own default internal callback that'll take care of the data if you don't set the callback with \fICURLOPT_WRITEFUNCTION\fP. It will then @@ -219,14 +222,13 @@ of them later. Let's instead continue to the actual transfer: success = curl_easy_perform(easyhandle); -The \fIcurl_easy_perform(3)\fP will connect to the remote site, do the -necessary commands and receive the transfer. Whenever it receives data, it -calls the callback function we previously set. The function may get one byte -at a time, or it may get many kilobytes at once. libcurl delivers as much as -possible as often as possible. Your callback function should return the number -of bytes it "took care of". If that is not the exact same amount of bytes that -was passed to it, libcurl will abort the operation and return with an error -code. +\fIcurl_easy_perform(3)\fP will connect to the remote site, do the necessary +commands and receive the transfer. Whenever it receives data, it calls the +callback function we previously set. The function may get one byte at a time, +or it may get many kilobytes at once. libcurl delivers as much as possible as +often as possible. Your callback function should return the number of bytes it +\&"took care of". If that is not the exact same amount of bytes that was +passed to it, libcurl will abort the operation and return with an error code. When the transfer is complete, the function returns a return code that informs you if it succeeded in its mission or not. If a return code isn't enough for @@ -240,12 +242,12 @@ previous .SH "Multi-threading Issues" libcurl is completely thread safe, except for two issues: signals and alarm -handlers. Signals are needed for a SIGPIPE handler, and the alarm() Bacall -is used to catch timeouts (mostly during ENS lookup). +handlers. Signals are needed for a SIGPIPE handler, and the alarm() call is +used to deal with timeouts (during DNS lookup). If you are accessing HTTPS or FTPS URLs in a multi-threaded manner, you are then of course using OpenSSL multi-threaded and it has itself a few -requirements on this. Basilio, you need to provide one or two functions to +requirements on this. Basically, you need to provide one or two functions to allow it to function properly. For all details, see this: http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION @@ -326,12 +328,12 @@ CURLOPT_INFILESIZE_LARGE for all known file sizes like this[1]: curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size); .fi -When you call curl_easy_perform() this time, it'll perform all the necessary -operations and when it has invoked the upload it'll call your supplied -callback to get the data to upload. The program should return as much data as -possible in every invoke, as that is likely to make the upload perform as -fast as possible. The callback should return the number of bytes it wrote in -the buffer. Returning 0 will signal the end of the upload. +When you call \fIcurl_easy_perform(3)\fP this time, it'll perform all the +necessary operations and when it has invoked the upload it'll call your +supplied callback to get the data to upload. The program should return as much +data as possible in every invoke, as that is likely to make the upload perform +as fast as possible. The callback should return the number of bytes it wrote +in the buffer. Returning 0 will signal the end of the upload. .SH "Passwords" Many protocols use or even require that user name and password are provided @@ -470,15 +472,14 @@ 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 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 that you build a formpost yourself and provide to -libcurl. To make that easier, libcurl provides curl_formadd(). Using this -function, you add parts to the form. When you're done adding parts, you post -the whole form. +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 +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 +that you build a formpost yourself and provide to libcurl. To make that +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. @@ -531,10 +532,10 @@ post handle: .fi Since all options on an easyhandle are "sticky", they remain the same until -changed even if you do call curl_easy_perform(), 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 CURLOPT_HTTPGET -option: +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 +CURLOPT_HTTPGET option: curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, TRUE); @@ -723,7 +724,7 @@ Mozilla javascript engine in the past. Re-cycling the same easy handle several times when doing multiple requests is the way to go. -After each single curl_easy_perform() operation, libcurl will keep the +After each single \fIcurl_easy_perform(3)\fP operation, libcurl will keep the connection alive and open. A subsequent request using the same easy handle to the same host might just be able to use the already open connection! This reduces network impact a lot. @@ -907,8 +908,8 @@ A little example that deletes a given file before an operation: .fi If you would instead want this operation (or chain of operations) to happen -_after_ the data transfer took place the option to curl_easy_setopt() would -instead be called CURLOPT_POSTQUOTE and used the exact same way. +_after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP +would instead be called CURLOPT_POSTQUOTE and used the exact same way. The custom FTP command will be issued to the server in the same order they are added to the list, and if a command gets an error code returned back from the @@ -977,9 +978,9 @@ The perhaps 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 curl_easy_cleanup() is called. This enabled cookies -to get passed on properly between multiple handles without any information -getting lost. +will be stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enabled +cookies to get passed on properly between multiple handles without any +information getting lost. .SH "FTP Peculiarities We Need" @@ -1107,46 +1108,47 @@ 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 a "multi stack". -You create the easy handles you want and you set all the options just like -you have been told above, and then you create a multi handle with -curl_multi_init() and add all those easy handles to that multi handle with -curl_multi_add_handle(). +You create the easy handles you want and you set all the options just like you +have been told above, and then you create a multi handle with +\fIcurl_multi_init(3)\fP and add all those easy handles to that multi handle +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 curl_multi_perform(). +ones at any time), you start the transfers by call +\fIcurl_multi_perform(3)\fP. -curl_multi_perform() is asynchronous. It will only execute as little as -possible and then return back control to your program. It is designed to -never block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again -soon, as that is a signal that it still has local data to send or remote data -to receive. +\fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as +possible and then return back control to your program. It is designed to never +block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again soon, +as that is a signal that it still has local data to send or remote data to +receive. The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also -makes it easy for you to wait and respond to actions on your own -application's sockets/handles. You figure out what to select() for by using -curl_multi_fdset(), that fills in a set of fd_set variables for you with the -particular file descriptors libcurl uses for the moment. +makes it easy for you to wait and respond to actions on your own application's +sockets/handles. You figure out what to select() for by using +\fIcurl_multi_fdset(3)\fP, that fills in a set of fd_set variables for you +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 curl_multi_perform() 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 call -curl_multi_perform(), 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 curl_multi_fdset() immediately before -the select() call since the current set of file descriptors may change when -calling a curl function. +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 +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 +\fIcurl_multi_fdset(3)\fP immediately before the select() call since the +current set of file descriptors may change when calling a curl function. If you want to stop the transfer of one of the easy handles in the stack, you -can use curl_multi_remove_handle() to remove individual easy -handles. Remember that easy handles should be curl_easy_cleanup()ed. +can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy +handles. Remember that easy handles should be \fIcurl_easy_cleanup(3)\fPed. When a transfer within the multi stack has finished, the counter of running -transfers (as filled in by curl_multi_perform()) will decrease. When the -number reaches zero, all transfers are done. +transfers (as filled in by \fIcurl_multi_perform(3)\fP) will decrease. When +the number reaches zero, all transfers are done. -curl_multi_info_read() can be used to get information about completed +\fIcurl_multi_info_read(3)\fP can be used to get information about completed transfers. It then returns the CURLcode for each easy transfer, to allow you to figure out success on each individual transfer. -- cgit v1.2.1 From 80a8be63192b3ba3339f3b5d742d0926c2d6ef7c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 25 Jan 2005 09:29:05 +0000 Subject: David Shaw contributed a fairly complete and detailed autoconf macro you can use to detect libcurl and setup variables for the protocols the installed libcurl supports: docs/libcurl/libcurl.m4 --- docs/libcurl/Makefile.am | 2 +- docs/libcurl/libcurl-tutorial.3 | 7 +- docs/libcurl/libcurl.m4 | 209 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 216 insertions(+), 2 deletions(-) create mode 100644 docs/libcurl/libcurl.m4 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index d4f8a1008..caea9b9aa 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -52,7 +52,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 MAN2HTML= roffit --mandir=. < $< >$@ diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 32766fc3c..80034a62b 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-tutorial 3 "22 Jan 2005" "libcurl" "libcurl programming" +.TH libcurl-tutorial 3 "25 Jan 2005" "libcurl" "libcurl programming" .SH NAME libcurl-tutorial \- libcurl programming tutorial .SH "Objective" @@ -76,6 +76,11 @@ possibly together with a few other features that can be on and off on different libcurls. See also the "Features libcurl Provides" further down. +.IP "autoconf macro" +When you write your configure script to detect libcurl and setup variables +accordingly, we offer a prewritten macro that probably does everything you +need in this area. See docs/libcurl/libcurl.m4 file - it includes docs on how +to use it. .SH "Portable Code in a Portable World" The people behind libcurl have put a considerable effort to make libcurl work diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 new file mode 100644 index 000000000..e80c2066b --- /dev/null +++ b/docs/libcurl/libcurl.m4 @@ -0,0 +1,209 @@ +# LIBCURL_CHECK_CONFIG ([DEFAULT-ACTION], [MINIMUM-VERSION], +# [ACTION-IF-YES], [ACTION-IF-NO]) +# ---------------------------------------------------------- +# David Shaw Jan-23-2005 +# +# Checks for libcurl. DEFAULT-ACTION is the string yes or no to +# specify whether to default to --with-libcurl or --without-libcurl. +# If not supplied, DEFAULT-ACTION is yes. MINIMUM-VERSION is the +# minimum version of libcurl to accept. Pass the version as a regular +# version number like 7.10.1. If not supplied, any version is +# accepted. ACTION-IF-YES is a list of shell commands to run if +# libcurl was successfully found and passed the various tests. +# ACTION-IF-NO is a list of shell commands that are run otherwise. +# Note that using --without-libcurl does run ACTION-IF-NO. +# +# This macro defines HAVE_LIBCURL if a working libcurl setup is found, +# and sets @LIBCURL@ and @LIBCURL_CPPFLAGS@ to the necessary values. +# Other useful defines are LIBCURL_FEATURE_xxx where xxx are the +# various features supported by libcurl, and LIBCURL_PROTOCOL_yyy +# where yyy are the various protocols supported by libcurl. Both xxx +# and yyy are capitalized. See the list of AH_TEMPLATEs at the top of +# the macro for the complete list of possible defines. Shell +# variables $libcurl_feature_xxx and $libcurl_protocol_yyy are also +# defined to 'yes' for those features and protocols that were found. +# Note that xxx and yyy keep the same capitalization as in the +# curl-config list (e.g. it's "HTTP" and not "http"). +# +# Users may override the detected values by doing something like: +# LIBCURL="-lcurl" LIBCURL_CPPFLAGS="-I/usr/myinclude" ./configure +# +# For the sake of sanity, this macro assumes that any libcurl that is +# found is after version 7.7.2, the first version that included the +# curl-config script. Note that it is very important for people +# packaging binary versions of libcurl to include this script! +# Without curl-config, we can only make educated guesses as to what +# protocols are available. Specifically, we assume that all of HTTP, +# FTP, GOPHER, FILE, TELNET, LDAP, and DICT exist, and (if SSL exists) +# HTTPS is present. All of these protocols existed when libcurl was +# first created in version 7, so this is a safe assumption. If the +# version is 7.11.0 or later, FTPS is assumed to be present as well. +# FTPS existed before then, but was not yet fully standards compliant. + +AC_DEFUN([LIBCURL_CHECK_CONFIG], +[ + AH_TEMPLATE([LIBCURL_FEATURE_SSL],[Defined if libcurl supports SSL]) + AH_TEMPLATE([LIBCURL_FEATURE_KRB4],[Defined if libcurl supports KRB4]) + AH_TEMPLATE([LIBCURL_FEATURE_IPV6],[Defined if libcurl supports IPv6]) + AH_TEMPLATE([LIBCURL_FEATURE_LIBZ],[Defined if libcurl supports libz]) + AH_TEMPLATE([LIBCURL_FEATURE_ASYNCHDNS],[Defined if libcurl supports AsynchDNS]) + + AH_TEMPLATE([LIBCURL_PROTOCOL_HTTP],[Defined if libcurl supports HTTP]) + AH_TEMPLATE([LIBCURL_PROTOCOL_HTTPS],[Defined if libcurl supports HTTPS]) + AH_TEMPLATE([LIBCURL_PROTOCOL_FTP],[Defined if libcurl supports FTP]) + AH_TEMPLATE([LIBCURL_PROTOCOL_FTPS],[Defined if libcurl supports FTPS]) + AH_TEMPLATE([LIBCURL_PROTOCOL_GOPHER],[Defined if libcurl supports GOPHER]) + AH_TEMPLATE([LIBCURL_PROTOCOL_FILE],[Defined if libcurl supports FILE]) + AH_TEMPLATE([LIBCURL_PROTOCOL_TELNET],[Defined if libcurl supports TELNET]) + AH_TEMPLATE([LIBCURL_PROTOCOL_LDAP],[Defined if libcurl supports LDAP]) + AH_TEMPLATE([LIBCURL_PROTOCOL_DICT],[Defined if libcurl supports DICT]) + + AC_ARG_WITH(libcurl, + AC_HELP_STRING([--with-libcurl=DIR],[look for the curl library in DIR]), + [_libcurl_with=$withval],[_libcurl_with=ifelse([$1],,[yes],[$1])]) + + if test "$_libcurl_with" != "no" ; then + + AC_PROG_AWK + + _libcurl_version_parse="eval $AWK '{split(\$NF,A,\".\"); X=256*256*A[[1]]+256*A[[2]]+A[[3]]; print X;}'" + + _libcurl_try_link=yes + + if test -d "$_libcurl_with" ; then + CPPFLAGS="${CPPFLAGS} -I$withval/include" + LDFLAGS="${LDFLAGS} -L$withval/lib" + fi + + AC_PATH_PROG([_libcurl_config],[curl-config]) + + if test x$_libcurl_config != "x" ; then + AC_CACHE_CHECK([for the version of libcurl], + [libcurl_cv_lib_curl_version], + [libcurl_cv_lib_curl_version=`$_libcurl_config --version | $AWK '{print $[]2}'`]) + + _libcurl_version=`echo $libcurl_cv_lib_curl_version | $_libcurl_version_parse` + _libcurl_wanted=`echo ifelse([$2],,[0],[$2]) | $_libcurl_version_parse` + + if test $_libcurl_wanted -gt 0 ; then + AC_CACHE_CHECK([for libcurl >= version $2], + [libcurl_cv_lib_version_ok], + [ + if test $_libcurl_version -ge $_libcurl_wanted ; then + libcurl_cv_lib_version_ok=yes + else + libcurl_cv_lib_version_ok=no + fi + ]) + fi + + if test $_libcurl_wanted -eq 0 || test x$libcurl_cv_lib_version_ok = xyes ; then + if test x"$LIBCURL_CPPFLAGS" = "x" ; then + LIBCURL_CPPFLAGS=`$_libcurl_config --cflags` + fi + if test x"$LIBCURL" = "x" ; then + LIBCURL=`$_libcurl_config --libs` + fi + + # All curl-config scripts support --feature + _libcurl_features=`$_libcurl_config --feature` + + # Is it modern enough to have --protocols? (7.12.4) + if test $_libcurl_version -ge 461828 ; then + _libcurl_protocols=`$_libcurl_config --protocols` + fi + else + _libcurl_try_link=no + fi + + unset _libcurl_wanted + fi + + if test $_libcurl_try_link = yes ; then + + # we didn't find curl-config, so let's see if the user-supplied + # link line (or failing that, "-lcurl") is enough. + LIBCURL=${LIBCURL-"-lcurl"} + + AC_CACHE_CHECK([whether libcurl is usable], + [libcurl_cv_lib_curl_usable], + [ + _libcurl_save_cppflags=$CPPFLAGS + CPPFLAGS="$CPPFLAGS $LIBCURL_CPPFLAGS" + _libcurl_save_ldflags=$LDFLAGS + LDFLAGS="$LDFLAGS $LIBCURL" + + AC_LINK_IFELSE(AC_LANG_PROGRAM([#include ],[ +/* Try and use a few common options to force a failure if we are + missing symbols or can't link. */ +int x; +curl_easy_setopt(NULL,CURLOPT_URL,NULL); +x=CURL_ERROR_SIZE; +x=CURLOPT_WRITEFUNCTION; +x=CURLOPT_FILE; +x=CURLOPT_ERRORBUFFER; +x=CURLOPT_STDERR; +x=CURLOPT_VERBOSE; +]),libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) + + CPPFLAGS=$_libcurl_save_cppflags + LDFLAGS=$_libcurl_save_ldflags + unset _libcurl_save_cppflags + unset _libcurl_save_ldflags + ]) + + if test $libcurl_cv_lib_curl_usable = yes ; then + AC_DEFINE(HAVE_LIBCURL,1, + [Define to 1 if you have a functional curl library.]) + AC_SUBST(LIBCURL_CPPFLAGS) + AC_SUBST(LIBCURL) + + for _libcurl_feature in $_libcurl_features ; do + AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_feature_$_libcurl_feature),[1]) + eval AS_TR_SH(libcurl_feature_$_libcurl_feature)=yes + done + + if test "x$_libcurl_protocols" = "x" ; then + + # We don't have --protocols, so just assume that all + # protocols are available + _libcurl_protocols="HTTP FTP GOPHER FILE TELNET LDAP DICT" + + if test x$libcurl_feature_SSL = xyes ; then + _libcurl_protocols="$_libcurl_protocols HTTPS" + + # FTPS wasn't standards-compliant until version + # 7.11.0 + if test $_libcurl_version -ge 461568; then + _libcurl_protocols="$_libcurl_protocols FTPS" + fi + fi + fi + + for _libcurl_protocol in $_libcurl_protocols ; do + AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_protocol_$_libcurl_protocol),[1]) + eval AS_TR_SH(libcurl_protocol_$_libcurl_protocol)=yes + done + fi + fi + + unset _libcurl_try_link + unset _libcurl_version_parse + unset _libcurl_config + unset _libcurl_feature + unset _libcurl_features + unset _libcurl_protocol + unset _libcurl_protocols + unset _libcurl_version + fi + + if test x$_libcurl_with = xno || test x$libcurl_cv_lib_curl_usable != xyes ; then + # This is the IF-NO path + ifelse([$4],,:,[$4]) + else + # This is the IF-YES path + ifelse([$3],,:,[$3]) + fi + + unset _libcurl_with +])dnl -- cgit v1.2.1 From 177dbc7be07125582ddb7416dba7140b88ab9f62 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 25 Jan 2005 22:13:12 +0000 Subject: Ian Ford asked about support for the FTP command ACCT, and I discovered it is present in RFC959... so now (lib)curl supports it as well. --ftp-account and CURLOPT_FTP_ACCOUNT set the account string. (The server may ask for an account string after PASS have been sent away. The client responds with "ACCT [account string]".) Added test case 228 and 229 to verify the functionality. Updated the test FTP server to support ACCT somewhat. --- docs/libcurl/curl_easy_setopt.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 776e3da90..84e5c1b80 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "20 Jan 2005" "libcurl 7.12.4" "libcurl Manual" +.TH curl_easy_setopt 3 "25 Jan 2005" "libcurl 7.13.0" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -763,6 +763,10 @@ Exactly like \fICURLOPT_QUOTE\fP, but for the source host. Exactly like \fICURLOPT_PREQUOTE\fP, but for the source host. .IP CURLOPT_SOURCE_POSTQUOTE Exactly like \fICURLOPT_POSTQUOTE\fP, but for the source host. +.IP CURLOPT_FTP_ACCOUNT +Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP +server asks for "account data" after user name and password has been provided, +this data is sent off using the ACCT command. (Added in 7.13.0) .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A non-zero parameter tells the library to use ASCII mode for ftp transfers, -- cgit v1.2.1 From 14aa3fa25844e74e88e74af013ad739c6786e787 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 9 Feb 2005 14:13:21 +0000 Subject: add missing error codes --- docs/libcurl/libcurl-errors.3 | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index de28c2d41..c56ea4fd7 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH libcurl-errors 3 "27 Apr 2004" "libcurl 7.12" "libcurl errors" +.TH libcurl-errors 3 "9 Feb 2005" "libcurl 7.13.1" "libcurl errors" .SH NAME libcurl-errors \- error codes in libcurl .SH DESCRIPTION @@ -187,6 +187,13 @@ Invalid LDAP URL Maximum file size exceeded .IP "CURLE_FTP_SSL_FAILED (64)" 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 +.IP "CURLE_SSL_ENGINE_INITFAILED (66)" +Initiating the SSL Engine failed +.IP "CURLE_LOGIN_DENIED (67)" +The remote server denied curl to login (Added in 7.13.1) .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. Also consider \fIcurl_multi_strerror(3)\fI. -- cgit v1.2.1 From 6f752c64bc18a9fdd0c0b2321faa230781280b8b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 4 Mar 2005 00:26:50 +0000 Subject: Dave Dribin made it possible to set CURLOPT_COOKIEFILE to "" to activate the cookie "engine" without having to provide an empty or non-existing file. --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 84e5c1b80..8074798c0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -617,9 +617,9 @@ name of your file holding cookie data to read. The cookie data may be in Netscape / Mozilla cookie data format or just regular HTTP-style headers dumped to a file. -Given an empty or non-existing file, this option will enable cookies for this -curl handle, making it understand and parse received cookies and then use -matching cookies in future request. +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. .IP CURLOPT_COOKIEJAR Pass a file name as char *, zero terminated. This will make libcurl write all internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP -- cgit v1.2.1 From 5cd9f57137fc185786f10b16ab73743386b95bd3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 8 Mar 2005 11:15:29 +0000 Subject: days are english --- docs/libcurl/curl_getdate.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 9af2f8509..0ba4dfbd7 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -41,9 +41,9 @@ general you should instead use the specific relative time compared to UTC. Supported formats include: -1200, MST, +0100. .TP .B day of the week items -Specifies a day of the week. Days of the week may be spelled out in full: -`Sunday', `Monday', etc or they may be abbreviated to their first three -letters. This is usually not info that adds anything. +Specifies a day of the week. Days of the week may be spelled out in full +(using english): `Sunday', `Monday', etc or they may be abbreviated to their +first three letters. This is usually not info that adds anything. .TP .B pure numbers If a decimal number of the form YYYYMMDD appears, then YYYY is read as the -- cgit v1.2.1 From 8a96aec5673b9ba4787cef1319c105facbe82a40 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 8 Mar 2005 16:31:56 +0000 Subject: mktime() returns a time_t. time_t is often 32 bits, even on many architectures that feature 64 bit 'long'. Some systems have 64 bit time_t and deal with years beyond 2038. However, even some of the systems with 64 bit time_t returns -1 for dates beyond 03:14:07 UTC, January 19, 2038. (Such as AIX 5100-06) --- docs/libcurl/curl_getdate.3 | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 0ba4dfbd7..75fd0c039 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -85,7 +85,12 @@ This function returns -1 when it fails to parse the date string. Otherwise it returns the number of seconds as described. If the year is larger than 2037 on systems with 32 bit time_t, this function -will return 0x7fffffff (since that is the largest possible 31 bit number). +will return 0x7fffffff (since that is the largest possible signed 32 bit +number). + +Having a 64 bit time_t is not a guarantee that dates beyond 03:14:07 UTC, +January 19, 2038 will work fine. On systems with a 64 bit time_t but with a +crippled mktime(), \fIcurl_getdate\fP will return -1 in this case. .SH REWRITE 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 -- cgit v1.2.1 From fc80c714e84655c7ff9767ca056a181b0aaaec05 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 11 Mar 2005 15:18:46 +0000 Subject: added CURL_VERSION_SSPI --- docs/libcurl/curl_version_info.3 | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 95b99af2e..f77062fb1 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -1,8 +1,6 @@ -.\" You can view this file with: -.\" nroff -man [file] .\" $Id$ .\" -.TH curl_version_info 3 "11 May 2004" "libcurl 7.12" "libcurl Manual" +.TH curl_version_info 3 "11 Mar 2005" "libcurl 7.13.2" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -73,9 +71,9 @@ supports IPv6 .IP CURL_VERSION_KERBEROS4 supports kerberos4 (when using FTP) .IP CURL_VERSION_SSL -supports SSL (HTTPS/FTPS) +supports SSL (HTTPS/FTPS) (Added in 7.10) .IP CURL_VERSION_LIBZ -supports HTTP deflate using libz +supports HTTP deflate using libz (Added in 7.10) .IP CURL_VERSION_NTLM supports HTTP NTLM (added in 7.10.6) .IP CURL_VERSION_GSSNEGOTIATE @@ -91,10 +89,15 @@ interface. (added in 7.10.7) libcurl was built with support for SPNEGO authentication (Simple and Protected GSS-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) .IP CURL_VERSION_LARGEFILE -libcurl was built with support for large files. +libcurl was built with support for large files. (Added in 7.11.1) .IP CURL_VERSION_IDN libcurl was built with support for IDNA, domain names with international -letters. +letters. (Added in 7.12.0) +.IP CURL_VERSION_SSPI +libcurl was built with support for SSPI. This is only available on Windows and +makes libcurl use Windows-provided functions for NTLM authentication. It also +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) .RE \fIssl_version\fP is an ascii string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. -- cgit v1.2.1 From 015a6181725a654fb6d1eb8ff55e116ea15dc89a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Apr 2005 15:21:50 +0000 Subject: ssl_version_num is not used anymore --- docs/libcurl/curl_version_info.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index f77062fb1..80653fb3c 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -34,7 +34,7 @@ typedef struct { const char *host; /* human readable string */ int features; /* bitmask, see below */ char *ssl_version; /* human readable string */ - long ssl_version_num; /* number */ + long ssl_version_num; /* not used, always zero */ const char *libz_version; /* human readable string */ const char **protocols; /* list of protocols */ -- cgit v1.2.1 From 7fba9ed398ab0b7eb98d70af03fbe6f2e26c02d9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 17 Apr 2005 23:01:46 +0000 Subject: somewhat clarified that this only sets the fd_sets and expects them to be cleared before this function is called --- docs/libcurl/curl_multi_fdset.3 | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index e7e84fc3c..222c2f2d8 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_fdset 3 "15 Apr 2004" "libcurl 7.9.5" "libcurl Manual" +.TH curl_multi_fdset 3 "18 Apr 2005" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_fdset - extracts file descriptor information from a multi handle .SH SYNOPSIS @@ -15,15 +15,17 @@ CURLMcode curl_multi_fdset(CURLM *multi_handle, .ad .SH DESCRIPTION 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. 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. +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. You should also be aware that when doing select(), you should consider using a rather small (single-digit number of seconds) timeout and call \fIcurl_multi_perform\fP regularly - even if no activity has been seen on the fd_sets - as otherwise libcurl-internal retries and timeouts may not work as -you'd think. +you'd think and want. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP -- cgit v1.2.1 From 6a2744992285c39d0cb69295228722ed1e3037c5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 18 Apr 2005 14:32:48 +0000 Subject: digest works in the proxyauth too --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8074798c0..5b54a3472 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -442,7 +442,7 @@ use. Note that for some methods, this will induce an extra network round-trip. Set the actual name and password with the \fICURLOPT_PROXYUSERPWD\fP option. The bitmask can be constructed by or'ing together the bits listed above for the \fICURLOPT_HTTPAUTH\fP option. As of -this writing, only Basic and NTLM work. (Added in 7.10.7) +this writing, only Basic, Digest and NTLM work. (Added in 7.10.7) .SH HTTP OPTIONS .IP CURLOPT_AUTOREFERER Pass a non-zero parameter to enable this. When enabled, libcurl will -- cgit v1.2.1 From 6e1633a6c5f88479998a1e0675818c9d97d9ed90 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 25 Apr 2005 08:55:55 +0000 Subject: be specific about what max_fd contains after a call --- docs/libcurl/curl_multi_fdset.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 222c2f2d8..0efc68ab1 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_fdset 3 "18 Apr 2005" "libcurl 7.9.5" "libcurl Manual" +.TH curl_multi_fdset 3 "25 Apr 2005" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_fdset - extracts file descriptor information from a multi handle .SH SYNOPSIS @@ -21,6 +21,10 @@ but be sure to FD_ZERO them before calling this function as 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. +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 +libcurl set. + You should also be aware that when doing select(), you should consider using a rather small (single-digit number of seconds) timeout and call \fIcurl_multi_perform\fP regularly - even if no activity has been seen on the -- cgit v1.2.1 From d12b44204b0914d37cbc8508f2bfe304de946bc6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 May 2005 07:28:40 +0000 Subject: Bryan Henderson's fine update of SSL_VERIFYPEER and SSL_VERIFYHOST --- docs/libcurl/curl_easy_setopt.3 | 92 +++++++++++++++++++++++++++++++++-------- 1 file changed, 74 insertions(+), 18 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5b54a3472..237e833ec 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -999,25 +999,52 @@ operations. Pass a long as parameter. Set what version of SSL to attempt to use, 2 or 3. By default, the SSL library will try to solve this by itself although some servers make this difficult why you at times may have to use this option. + + .IP CURLOPT_SSL_VERIFYPEER -Pass a long that is set to a zero value to stop curl from verifying the peer's -certificate (7.10 starting setting this option to non-zero by default). -Alternate certificates to verify against can be specified with the -\fICURLOPT_CAINFO\fP option or a certificate directory can be specified with -the \fICURLOPT_CAPATH\fP option. As of 7.10, curl installs a default bundle. -\fICURLOPT_SSL_VERIFYHOST\fP may also need to be set to 1 or 0 if -\fICURLOPT_SSL_VERIFYPEER\fP is disabled (it defaults to 2). + +Pass a long as parameter. + +This option determines whether curl verifies the authenticity of the +peer's certificate. A nonzero value means curl verifies; zero means it +doesn't. The default is nonzero, but before 7.10, it was zero. + +When negotiating an SSL connection, the server sends a certificate +indicating its identity. Curl verifies whether the certificate is +authentic, i.e. that you can trust that the server is who the +certificate says it is. This trust is based on a chain of digital +signatures, rooted in certification authority (CA) certificates you +supply. As of 7.10, curl installs a default bundle of CA certificates +and you can specify alternate certificates with the +\fICURLOPT_CAINFO\fP option or the \fICURLOPT_CAPATH\fP option. + +When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification +fails to prove that the certificate is authentic, the connection +fails. When the option is zero, the connection succeeds regardless. + +Authenticating the certificate is not by itself very useful. You +typically want to ensure that the server, as authentically identified +by its certificate, is the server you mean to be talking to. Use +\fICURLOPT_SSL_VERIFYHOST\fP to control that. + .IP CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more -certificates to verify the peer with. This only makes sense when used in -combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. +certificates to verify the peer with. This makes sense only when used in +combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If +\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAINFO\fP need not +even indicate an accessible file. + .IP CURLOPT_CAPATH -Pass a char * to a zero terminated string naming a directory holding multiple -CA certificates to verify the peer with. The certificate directory must be -prepared using the openssl c_rehash utility. This only makes sense when used -in combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. The -\fICURLOPT_CAPATH\fP function apparently does not work in Windows due to some -limitation in openssl. (Added in 7.9.8) +Pass a char * to a zero terminated string naming a directory holding +multiple CA certificates to verify the peer with. The certificate +directory must be prepared using the openssl c_rehash utility. This +makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER\fP option. If \fICURLOPT_SSL_VERIFYPEER\fP +is zero, \fICURLOPT_CAPATH\fP need not even indicate an accessible +path. The \fICURLOPT_CAPATH\fP function apparently does not work in +Windows due to some limitation in openssl. (Added in 7.9.8) + + .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, @@ -1025,10 +1052,38 @@ the more secure the SSL connection will become. .IP CURLOPT_EGDSOCKET Pass a char * to the zero terminated path name to the Entropy Gathering Daemon socket. It will be used to seed the random engine for SSL. + .IP CURLOPT_SSL_VERIFYHOST -Pass a long. Set if we should verify the Common name from the peer certificate -in the SSL handshake, set 1 to check existence, 2 to ensure that it matches -the provided hostname. This is by default set to 2. (default changed in 7.10) + +Pass a long as parameter. + +This option determines whether curl verifies that the server claims to be +who you want it to be. + +When negotiating an SSL connection, the server sends a certificate +indicating its identity. + +When \fICURLOPT_SSL_VERIFYHOST\fP is 2, that certificate must indicate +that the server is the server to which you meant to connect, or the +connection fails. + +Curl considers the server the intended one when the Common Name field +or a Subject Alternate Name field in the certificate matches the host +name in the URL to which you told Curl to connect. + +When the value is 1, the certificate must contain a Common Name field, +but it doesn't matter what name it says. (This is not ordinarily a +useful setting). + +When the value is 0, the connection succeeds regardless of the names in +the 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. + .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, @@ -1040,6 +1095,7 @@ compile OpenSSL. You'll find more details about cipher lists on this URL: \fIhttp://www.openssl.org/docs/apps/ciphers.html\fP + .IP CURLOPT_KRB4LEVEL Pass a char * as parameter. Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or -- cgit v1.2.1 From e816bd259fec66d1c1f1b1c81e927650e49491f1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 9 May 2005 13:13:38 +0000 Subject: add multi-thread details for GnuTLS --- docs/libcurl/libcurl-tutorial.3 | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 80034a62b..1610fa559 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-tutorial 3 "25 Jan 2005" "libcurl" "libcurl programming" +.TH libcurl-tutorial 3 "9 May 2005" "libcurl" "libcurl programming" .SH NAME libcurl-tutorial \- libcurl programming tutorial .SH "Objective" @@ -246,16 +246,26 @@ you intend to make another transfer. libcurl will then attempt to re-use the previous .SH "Multi-threading Issues" -libcurl is completely thread safe, except for two issues: signals and alarm -handlers. Signals are needed for a SIGPIPE handler, and the alarm() call is -used to deal with timeouts (during DNS lookup). +The first basic rule is that you must \fBnever\fP share a libcurl handle (be +it easy or multi or whatever) between multiple threads. Only use one handle in +one thread at a time. + +libcurl is completely thread safe, except for two issues: signals and SSL/TLS +handlers. Signals are used timeouting name resolves (during DNS lookup) - 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 OpenSSL multi-threaded and it has itself a few -requirements on this. Basically, you need to provide one or two functions to -allow it to function properly. For all details, see this: +then of course using OpenSSL/GnuTLS multi-threaded and those libs have their +own requirements on this issue. Basically, you need to provide one or two +functions to allow it to function properly. For all details, see this: + +OpenSSL + + http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION + +GnuTLS - http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION + http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE for all handles. Everything will work fine except that timeouts are not -- cgit v1.2.1 From 8c573ca7f3870240afa836e5a36e9db2a35021ce Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 12 May 2005 21:49:42 +0000 Subject: CURLOPT_SSLVERSION clarified --- docs/libcurl/curl_easy_setopt.3 | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 237e833ec..dfb35a2e8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "25 Jan 2005" "libcurl 7.13.0" "libcurl Manual" +.TH curl_easy_setopt 3 "12 May 2005" "libcurl 7.14.0" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -996,13 +996,22 @@ operations. \fBNOTE:\fP If the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is returned. .IP CURLOPT_SSLVERSION -Pass a long as parameter. Set what version of SSL to attempt to use, 2 or -3. By default, the SSL library will try to solve this by itself although some -servers make this difficult why you at times may have to use this option. - - +Pass a long as parameter to control what version of SSL/TLS to attempt to use. +The available options are: +.RS +.IP CURL_SSLVERSION_DEFAULT +The default action. When libcurl built with OpenSSL, this will attempt to +figure out the remote SSL protocol version. Unfortunately there are a lot of +ancient and broken servers in use which cannot handle this technique and will +fail to connect. When libcurl is built with GnuTLS, this will mean SSLv3. +.IP CURL_SSLVERSION_TLSv1 +Force TLSv1 +.IP CURL_SSLVERSION_SSLv2 +Force SSLv2 +.IP CURL_SSLVERSION_SSLv3 +Force SSLv3 +.RE .IP CURLOPT_SSL_VERIFYPEER - Pass a long as parameter. This option determines whether curl verifies the authenticity of the -- cgit v1.2.1 From fa4cd8868cc5e8567c0392516c178051a56f24cb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 12 May 2005 21:56:26 +0000 Subject: remove blank lines --- docs/libcurl/curl_easy_setopt.3 | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index dfb35a2e8..ecdfdceec 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -410,7 +410,7 @@ is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. .IP CURLAUTH_GSSNEGOTIATE HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain -"Negotiate") method was designed by Microsoft and is used in their web +\&"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 information see IETF draft draft-brezak-spnego-http-04.txt. @@ -1035,14 +1035,12 @@ Authenticating the certificate is not by itself very useful. You typically want to ensure that the server, as authentically identified by its certificate, is the server you mean to be talking to. Use \fICURLOPT_SSL_VERIFYHOST\fP to control that. - .IP CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This makes sense only when used in combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If \fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAINFO\fP need not even indicate an accessible file. - .IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate @@ -1052,8 +1050,6 @@ makes sense only when used in combination with the is zero, \fICURLOPT_CAPATH\fP need not even indicate an accessible path. The \fICURLOPT_CAPATH\fP function apparently does not work in Windows due to some limitation in openssl. (Added in 7.9.8) - - .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, @@ -1061,9 +1057,7 @@ the more secure the SSL connection will become. .IP CURLOPT_EGDSOCKET Pass a char * to the zero terminated path name to the Entropy Gathering Daemon socket. It will be used to seed the random engine for SSL. - .IP CURLOPT_SSL_VERIFYHOST - Pass a long as parameter. This option determines whether curl verifies that the server claims to be @@ -1092,7 +1086,6 @@ 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. - .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, @@ -1104,7 +1097,6 @@ compile OpenSSL. You'll find more details about cipher lists on this URL: \fIhttp://www.openssl.org/docs/apps/ciphers.html\fP - .IP CURLOPT_KRB4LEVEL Pass a char * as parameter. Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or -- cgit v1.2.1 From 1e51c3a832aba5e790dfe82e5c04d47a961fb31b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 16 May 2005 22:30:00 +0000 Subject: bad formatting --- docs/libcurl/libcurl-errors.3 | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index c56ea4fd7..64b3454eb 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -196,8 +196,7 @@ Initiating the SSL Engine failed The remote server denied curl to login (Added in 7.13.1) .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi -interface. Also consider \fIcurl_multi_strerror(3)\fI. - +interface. Also consider \fIcurl_multi_strerror(3)\fP. .IP "CURLM_CALL_MULTI_PERFORM (-1)" This is not really an error. It means you should call \fIcurl_multi_perform(3)\fP again without doing select() or similar in between. @@ -213,9 +212,7 @@ You are doomed. This can only be returned if libcurl bugs. Please report it to us! .SH "CURLSHcode" The "share" interface will return a CURLSHcode to indicate when an error has -occurred. Also consider \fIcurl_share_strerror(3)\fI. - -CURLSHcode is one of the following: +occurred. Also consider \fIcurl_share_strerror(3)\fP. .IP "CURLSHE_OK (0)" All fine. Proceed as usual. .IP "CURLSHE_BAD_OPTION (1)" -- cgit v1.2.1 From eb162b73c2d619fd7db922aa92a43edb55548a8f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 3 Jun 2005 21:38:40 +0000 Subject: first rough version --- docs/libcurl/getinfo-times | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/libcurl/getinfo-times (limited to 'docs/libcurl') diff --git a/docs/libcurl/getinfo-times b/docs/libcurl/getinfo-times new file mode 100644 index 000000000..d767d7aae --- /dev/null +++ b/docs/libcurl/getinfo-times @@ -0,0 +1,27 @@ +An overview of the six time values available from curl_easy_getinfo() + +curk_easy_perform() + | + |--NT + |--|--CT + |--|--|--PT + |--|--|--|--ST + |--|--|--TT + |--|--|--|--|--RT + +NT = CURLINFO_NAMELOOKUP_TIME. The time it took from the start until the name + resolving was completed. +CT = CURLINFO_CONNECT_TIME. The time it took from the start until the connect + to the remote host (or proxy) was completed. +PT = CURLINFO_PRETRANSFER_TIME. The time it took from the start until the file + transfer is just about to begin. This includes all pre-transfer commands + and negotiations that are specific to the particular protocol(s) + involved. +ST = CURLINFO_STARTTRANSFER_TIME. The time it took from the start until the + first byte is just about to be transferred. +TT = CURLINFO_TOTAL_TIME. Time of the previous transfer. This time does not + include the connect time (CT), so if you want the complete operation + time, you should add that. +RT = CURLINFO_REDIRECT_TIME. The time it took for all redirection steps + include name lookup, connect, pretransfer and transfer before final + transaction was started. So, this is zero if no redirection took place. -- cgit v1.2.1 From c4bbcc83b60f5945e7dc3973209140179e49407e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 6 Jun 2005 21:19:04 +0000 Subject: Tupone Alfredo's fixes: 1) findtool does look per tool in PATH and think ./perl is the perl executable, while is just a local directory (I have . in the PATH) 2) I got several warning for head -1 deprecated in favour of head -n 1 3) ares directory is missing some file (missing is missing :-) ) because automake and friends is not run. (Let's hope number 2 doesn't break somewhere "out there", if so we can always search/replace that back.) --- docs/libcurl/Makefile.am | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index caea9b9aa..de7fd95dd 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -52,7 +52,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 \ + getinfo-times MAN2HTML= roffit --mandir=. < $< >$@ -- cgit v1.2.1 From c04fae3096309b66085ca4ab7edfe15dd0ff364f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 11 Jun 2005 22:04:41 +0000 Subject: CURLINFO_FILETIME returns the time for GMT --- docs/libcurl/curl_easy_getinfo.3 | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 8325aafde..44dc433a6 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -35,12 +35,14 @@ this. Pass a pointer to a long to receive the last received proxy response code to a CONNECT request. .IP CURLINFO_FILETIME -Pass a pointer to a long to receive the remote time of the retrieved -document. If you get -1, it can be because of many reasons (unknown, the -server hides it or the server doesn't support the command that tells document -time etc) and the time of the document is unknown. Note that you must tell the -server to collect this information before the transfer is made, by using the -CURLOPT_FILETIME option to \fIcurl_easy_setopt(3)\fP. (Added in 7.5) +Pass a pointer to a long to receive the remote time of the retrieved document +(in number of seconds since 1 jan 1970 in the GMT/UTC time zone). If you get +-1, it can be because of many reasons (unknown, the server hides it or the +server doesn't support the command that tells document time etc) and the time +of the document is unknown. Note that you must tell the server to collect this +information before the transfer is made, by using the CURLOPT_FILETIME option +to \fIcurl_easy_setopt(3)\fP or you will unconditionally get a -1 back. (Added +in 7.5) .IP CURLINFO_TOTAL_TIME Pass a pointer to a double to receive the total transaction time in seconds for the previous transfer. This time does not include the connect time, so if -- cgit v1.2.1 From 93558c4299f579a13a6f8fa7b262e65cb061ce8d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 20 Jun 2005 22:32:45 +0000 Subject: mistake --- docs/libcurl/curl_formadd.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 693ca0f2e..3a45f006e 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -90,7 +90,7 @@ followed by a pointer to a string to a name, will make libcurl use the given name in the file upload part, instead of the actual file name given to \fICURLFORM_FILE\fP. -.IP BCURLFORM_BUFFER +.IP CURLFORM_BUFFER followed by a string, tells libcurl that a buffer is to be used to upload data instead of using a file. The given string is used as the value of the file name field in the content header. -- cgit v1.2.1 From c73f8e835fa04e3801cc253c6dbf0fb765a29ad8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 22 Jun 2005 06:58:11 +0000 Subject: David Shaw's updated version: It now properly handles code that uses curl_free() (since not all versions of curl have it), and also fixes a few problems when detecting libcurl on MinGW, and a linker problem on OSX Panther. --- docs/libcurl/libcurl.m4 | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index e80c2066b..882770924 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -1,7 +1,7 @@ # LIBCURL_CHECK_CONFIG ([DEFAULT-ACTION], [MINIMUM-VERSION], # [ACTION-IF-YES], [ACTION-IF-NO]) # ---------------------------------------------------------- -# David Shaw Jan-23-2005 +# David Shaw Jun-21-2005 # # Checks for libcurl. DEFAULT-ACTION is the string yes or no to # specify whether to default to --with-libcurl or --without-libcurl. @@ -32,13 +32,7 @@ # found is after version 7.7.2, the first version that included the # curl-config script. Note that it is very important for people # packaging binary versions of libcurl to include this script! -# Without curl-config, we can only make educated guesses as to what -# protocols are available. Specifically, we assume that all of HTTP, -# FTP, GOPHER, FILE, TELNET, LDAP, and DICT exist, and (if SSL exists) -# HTTPS is present. All of these protocols existed when libcurl was -# first created in version 7, so this is a safe assumption. If the -# version is 7.11.0 or later, FTPS is assumed to be present as well. -# FTPS existed before then, but was not yet fully standards compliant. +# Without curl-config, we can only guess what protocols are available. AC_DEFUN([LIBCURL_CHECK_CONFIG], [ @@ -103,6 +97,15 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], fi if test x"$LIBCURL" = "x" ; then LIBCURL=`$_libcurl_config --libs` + + # This is so silly, but Apple actually has a bug in their + # curl-config script. Fixed in Tiger, but there are still + # lots of Panther installs around. + case "${host}" in + powerpc-apple-darwin7*) + LIBCURL=`echo $LIBCURL | sed -e 's|-arch i386||g'` + ;; + esac fi # All curl-config scripts support --feature @@ -130,8 +133,8 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], [ _libcurl_save_cppflags=$CPPFLAGS CPPFLAGS="$CPPFLAGS $LIBCURL_CPPFLAGS" - _libcurl_save_ldflags=$LDFLAGS - LDFLAGS="$LDFLAGS $LIBCURL" + _libcurl_save_libs=$LIBS + LIBS="$LIBS $LIBCURL" AC_LINK_IFELSE(AC_LANG_PROGRAM([#include ],[ /* Try and use a few common options to force a failure if we are @@ -147,12 +150,30 @@ x=CURLOPT_VERBOSE; ]),libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) CPPFLAGS=$_libcurl_save_cppflags - LDFLAGS=$_libcurl_save_ldflags + LIBS=$_libcurl_save_libs unset _libcurl_save_cppflags - unset _libcurl_save_ldflags + unset _libcurl_save_libs ]) if test $libcurl_cv_lib_curl_usable = yes ; then + + # Does curl_free() exist in this version of libcurl? + # If not, fake it with free() + + _libcurl_save_cppflags=$CPPFLAGS + CPPFLAGS="$CPPFLAGS $LIBCURL_CPPFLAGS" + _libcurl_save_libs=$LIBS + LIBS="$LIBS $LIBCURL" + + AC_CHECK_FUNC(curl_free,, + AC_DEFINE(curl_free,free, + [Define curl_free() as free() if our version of curl lacks curl_free.])) + + CPPFLAGS=$_libcurl_save_cppflags + LIBS=$_libcurl_save_libs + unset _libcurl_save_cppflags + unset _libcurl_save_libs + AC_DEFINE(HAVE_LIBCURL,1, [Define to 1 if you have a functional curl library.]) AC_SUBST(LIBCURL_CPPFLAGS) -- cgit v1.2.1 From d8dcd5e472ae856901ba7d93477cf8c14b80eb50 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 23 Jun 2005 23:07:07 +0000 Subject: added docs about the new proxy string support --- docs/libcurl/curl_easy_setopt.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ecdfdceec..78a6d3798 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "12 May 2005" "libcurl 7.14.0" "libcurl Manual" +.TH curl_easy_setopt 3 "24 Jun 2005" "libcurl 7.14.1" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -283,6 +283,10 @@ unless you tunnel through the HTTP proxy. Such tunneling is activated with \fBNOTE2:\fP libcurl respects the environment variables \fBhttp_proxy\fP, \fBftp_proxy\fP, \fBall_proxy\fP etc, if any of those is set. + +Starting with 7.14.1, the proxy host string can be specified the exact same +way as the proxy environment variables, include protocol prefix (http://) and +embedded user + password. .IP CURLOPT_PROXYPORT Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. -- cgit v1.2.1 From 36461fb2aadb98bb25ae75b8167ab93d048d98a9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 26 Jun 2005 10:08:08 +0000 Subject: clarify that ftp ascii transfers don't do right in current libcurl --- docs/libcurl/curl_easy_setopt.3 | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 78a6d3798..e7995e55a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -774,11 +774,15 @@ this data is sent off using the ACCT command. (Added in 7.13.0) .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A non-zero parameter tells the library to use ASCII mode for ftp transfers, -instead of the default binary transfer. For LDAP transfers it gets the data in -plain text instead of HTML and 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 or -similar. +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 +or similar. + +\fBNOTE:\fP 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. .IP CURLOPT_CRLF Convert Unix newlines to CRLF newlines on transfers. .IP CURLOPT_RANGE -- cgit v1.2.1 From a8a8ae2e92b4c8e824295839408e568c7dc1c6fc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 13 Jul 2005 09:37:22 +0000 Subject: elaborate a bit on how to deal with chunked-encoded trailers that now are passed to the app using the header callback --- docs/libcurl/curl_easy_setopt.3 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e7995e55a..d5ad5c673 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "24 Jun 2005" "libcurl 7.14.1" "libcurl Manual" +.TH curl_easy_setopt 3 "13 Jul 2005" "libcurl 7.14.1" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -180,6 +180,14 @@ you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the number of bytes actually written or return -1 to signal error to the library (it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return code). + +Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a +trailer. That trailer is identical to a HTTP header and if such a trailer is +received it is passed to the application using this callback as well. There +are several ways to detect it being a trailer and not an ordinary header: 1) +it comes after the response-body. 2) it comes after the final header line (CR +LF) 3) a Trailer: header among the response-headers mention what header to +expect in the trailer. .IP CURLOPT_WRITEHEADER Pass a pointer to be used to write the header part of the received data to. If you don't use your own callback to take care of the writing, this must be a -- cgit v1.2.1 From ee0666c8df0022a13fd478fe4a916f647a6338c5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 13 Jul 2005 09:46:37 +0000 Subject: better description for HEADERFUNCTION --- docs/libcurl/curl_easy_setopt.3 | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d5ad5c673..046cba0fb 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -171,13 +171,14 @@ argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. .IP CURLOPT_HEADERFUNCTION Function pointer that should match the following prototype: \fIsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This -function gets called by libcurl as soon as there is received header data that -needs to be written down. The headers are guaranteed to be written one-by-one -and only complete lines are written. Parsing headers should be easy enough +function gets called by libcurl as soon as it has received header data. The +header callback will be called once for each header and only complete header +lines are passed on to the callback. Parsing headers should be easy enough using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP -multiplied with \fInmemb\fP. The pointer named \fIstream\fP will be the one -you passed to libcurl with the \fICURLOPT_WRITEHEADER\fP option. Return the -number of bytes actually written or return -1 to signal error to the library +multiplied with \fInmemb\fP. Do not assume that the header line is zero +terminated! The pointer named \fIstream\fP is the one you set with the +\fICURLOPT_WRITEHEADER\fP option. The callback function must return the number +of bytes actually taken care of, or return -1 to signal error to the library (it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return code). @@ -189,10 +190,11 @@ it comes after the response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: header among the response-headers mention what header to expect in the trailer. .IP CURLOPT_WRITEHEADER -Pass a pointer to be used to write the header part of the received data to. If -you don't use your own callback to take care of the writing, this must be a -valid FILE *. See also the \fICURLOPT_HEADERFUNCTION\fP option above on how to -set a custom get-all-headers callback. +(This option is also known as \fBCURLOPT_HEADERDATA\fP) Pass a pointer to be +used to write the header part of the received data to. If you don't use your +own callback to take care of the writing, this must be a valid FILE *. See +also the \fICURLOPT_HEADERFUNCTION\fP option above on how to set a custom +get-all-headers callback. .IP CURLOPT_DEBUGFUNCTION Function pointer that should match the following prototype: \fIint curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP -- cgit v1.2.1 From 2236ba0d206fe9fef5d93889ee652feaa03fe089 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Jul 2005 22:17:14 +0000 Subject: Peteris Krumins added CURLOPT_COOKIELIST and CURLINFO_COOKIELIST, which is a simple interface to extracting and setting cookies in libcurl's internal "cookie jar". See the new cookie_interface.c example code. --- docs/libcurl/curl_easy_getinfo.3 | 7 +++++++ docs/libcurl/curl_easy_setopt.3 | 6 ++++++ 2 files changed, 13 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 44dc433a6..c9be5e6a0 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -134,6 +134,13 @@ counted). Combined with \fICURLINFO_REDIRECT_COUNT\fP you are able to know how many times libcurl successfully reused existing connection(s) or not. See the Connection Options of \fIcurl_easy_setopt(3)\fP to see how libcurl tries to make persistent connections to save time. (Added in 7.12.3) +.IP CURLINFO_COOKIELIST +Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all +cookies cURL knows (expired ones, too). Don't forget to +\fIcurl_slist_free_all(3)\fP the list after it has been used. +If there are no cookies (cookies for the handle have not been enabled or +simply none have been received) 'struct curl_slist *' will be set to +point to NULL. .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 046cba0fb..75fc28926 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -654,6 +654,12 @@ 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 without expiry date and they are meant to be alive and existing for this "session" only. +.IP CURLOPT_COOKIELIST +Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla +format or just regular HTTP-style header (Set-Cookie: ...) format. The passed +string will get modified so make sure it's writable. If cURL cookie engine +was not enabled it will enable its cookie engine. Passing a magic string +\&"ALL" will erase all cookies known by cURL. .IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. usable if a POST, HEAD, PUT or a custom request have been used -- cgit v1.2.1 From 726b9e2240a272304cefc61b6fb9d9bb9a9a78f4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Jul 2005 22:29:50 +0000 Subject: If any of the options CURLOPT_HTTPGET, CURLOPT_POST and CURLOPT_HTTPPOST is set to 1, CURLOPT_NOBODY will now automatically be set to 0. --- docs/libcurl/curl_easy_setopt.3 | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 75fc28926..8f653f595 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "13 Jul 2005" "libcurl 7.14.1" "libcurl Manual" +.TH curl_easy_setopt 3 "28 Jul 2005" "libcurl 7.14.1" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -525,8 +525,11 @@ adding a header like "Transfer-Encoding: chunked" with \fICURLOPT_HTTPHEADER\fP. With HTTP 1.0 or without chunked transfer, you must specify the size in the request. -NOTE: if you have issued a POST request and want to make a HEAD or GET -instead, you must explictly pick the new request type using +When setting \fICURLOPT_POST\fP to a non-zero value, it will automatically set +\fICURLOPT_NOBODY\fP to 0. + +If you issue a POST request and then want to make a HEAD or GET using the same +re-used handle, you must explictly set the new request type using \fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. .IP CURLOPT_POSTFIELDS Pass a char * as parameter, which should be the full data to post in an HTTP @@ -564,6 +567,9 @@ must remain intact until you close this curl handle again with Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. + +When setting \fICURLOPT_HTTPPOST\fP, it will automatically set +\fICURLOPT_NOBODY\fP to 0. .IP CURLOPT_REFERER Pass a pointer to a zero terminated string as parameter. It will be used to set the Referer: header in the http request sent to the remote server. This @@ -664,6 +670,9 @@ was not enabled it will enable its cookie engine. Passing a magic string Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. usable if a POST, HEAD, PUT or a custom request have been used previously using the same curl handle. + +When setting \fICURLOPT_HTTPGET\fP to a non-zero value, it will automatically +set \fICURLOPT_NOBODY\fP to 0. .IP CURLOPT_HTTP_VERSION Pass a long, set to one of the values described below. They force libcurl to use the specific HTTP versions. This is not sensible to do unless you have a -- cgit v1.2.1 From 84c2184909d47cdc1a17c20069a78634f72098b9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 30 Jul 2005 08:27:51 +0000 Subject: CURLOPT_COOKIELIST change since it no longer modifies the input string contents --- docs/libcurl/curl_easy_setopt.3 | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8f653f595..a63e225ef 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -662,10 +662,9 @@ cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only. .IP CURLOPT_COOKIELIST Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla -format or just regular HTTP-style header (Set-Cookie: ...) format. The passed -string will get modified so make sure it's writable. If cURL cookie engine -was not enabled it will enable its cookie engine. Passing a magic string -\&"ALL" will erase all cookies known by cURL. +format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL +cookie engine was not enabled it will enable its cookie engine. Passing a +magic string \&"ALL" will erase all cookies known by cURL. .IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. usable if a POST, HEAD, PUT or a custom request have been used -- cgit v1.2.1 From 9a264bf6106ee07829a3c418b6a5131aff6579b8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 1 Aug 2005 11:56:03 +0000 Subject: mention that the NOBODY reset thing is added in 7.14.1 --- docs/libcurl/curl_easy_setopt.3 | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a63e225ef..f4ba68346 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -526,7 +526,7 @@ adding a header like "Transfer-Encoding: chunked" with specify the size in the request. When setting \fICURLOPT_POST\fP to a non-zero value, it will automatically set -\fICURLOPT_NOBODY\fP to 0. +\fICURLOPT_NOBODY\fP to 0 (since 7.14.1). If you issue a POST request and then want to make a HEAD or GET using the same re-used handle, you must explictly set the new request type using @@ -569,7 +569,7 @@ Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. When setting \fICURLOPT_HTTPPOST\fP, it will automatically set -\fICURLOPT_NOBODY\fP to 0. +\fICURLOPT_NOBODY\fP to 0 (since 7.14.1). .IP CURLOPT_REFERER Pass a pointer to a zero terminated string as parameter. It will be used to set the Referer: header in the http request sent to the remote server. This @@ -671,7 +671,7 @@ to GET. usable if a POST, HEAD, PUT or a custom request have been used previously using the same curl handle. When setting \fICURLOPT_HTTPGET\fP to a non-zero value, it will automatically -set \fICURLOPT_NOBODY\fP to 0. +set \fICURLOPT_NOBODY\fP to 0 (since 7.14.1). .IP CURLOPT_HTTP_VERSION Pass a long, set to one of the values described below. They force libcurl to use the specific HTTP versions. This is not sensible to do unless you have a @@ -850,9 +850,8 @@ A non-zero parameter tells the library to not include the body-part in the output. This is only relevant for protocols that have separate header and body parts. On HTTP(S) servers, this will make libcurl do a HEAD request. -To change back to GET, you should use \fICURLOPT_HTTPGET\fP. To change back to -POST, you should use \fICURLOPT_POST\fP. Setting \fICURLOPT_NOBODY\fP to zero -has no effect. +To change request to GET, you should use \fICURLOPT_HTTPGET\fP. Change request +to POST with \fICURLOPT_POST\fP etc. .IP CURLOPT_INFILESIZE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed -- cgit v1.2.1 From 2f78c96330f4ea921af711d8fd1526f25c33b2f7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 12 Aug 2005 21:47:05 +0000 Subject: clarify --- docs/libcurl/curl_getdate.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 75fd0c039..0cd26e677 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_getdate 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" +.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, 1970 @@ -26,7 +26,7 @@ order of the items is immaterial. A date string may contain many flavors of items: .TP 0.8i .B calendar date items -Can be specified several ways. Month names can only be three-letter +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. Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. .TP @@ -94,7 +94,7 @@ crippled mktime(), \fIcurl_getdate\fP will return -1 in this case. .SH REWRITE 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 Bison could make it thread-safe! +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 code. -- cgit v1.2.1 From 94692b904e6ebe7c08f8ebcdc4b4cea8ccf9dfd1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 18 Aug 2005 06:14:17 +0000 Subject: it isn't strictly necessary to use it after a perform --- docs/libcurl/curl_easy_getinfo.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index c9be5e6a0..27fca27e6 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -15,9 +15,9 @@ Request internal information from the curl session with this function. The third argument \fBMUST\fP be a pointer to a long, a pointer to a char *, a pointer to a struct curl_slist * or a pointer to a double (as this documentation describes further down). The data pointed-to will be filled in -accordingly and can be relied upon only if the function returns CURLE_OK. -This function is intended to get used AFTER a performed transfer, all results -from this function are undefined until the transfer is completed. +accordingly and can be relied upon only if the function returns CURLE_OK. Use +this function AFTER a performed transfer if you want to get transfer- oriented +data. You should not free the memory returned by this function unless it is explictly mentioned below. -- cgit v1.2.1 From 747a05844d66e070dbee9a2ad93695480ab07237 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 19 Aug 2005 21:38:44 +0000 Subject: Using CURLOPT_COOKIEFILE serveral times add more files to read from. --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f4ba68346..0b2649e1e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -640,6 +640,9 @@ 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. + +If you use this option multiple times, you just add more files to read. +Subsequent files will add more cookies. .IP CURLOPT_COOKIEJAR Pass a file name as char *, zero terminated. This will make libcurl write all internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP -- cgit v1.2.1 From a4773fcbbbf42a25c1037573fbab58aa275b9ed1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 24 Aug 2005 10:57:28 +0000 Subject: Toby Peterson added CURLOPT_IGNORE_CONTENT_LENGTH to the library, accessible from the command line tool with --ignore-content-length. This will make it easier to download files from Apache 1.x (and similar) servers that are still having problems serving files larger than 2 or 4 GB. When this option is enabled, curl will simply have to wait for the server to close the connection to signal end of transfer. I wrote test case 269 that runs a simple test that this works. --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0b2649e1e..07f6f09e5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -687,6 +687,11 @@ it thinks fit. Enforce HTTP 1.0 requests. .IP CURL_HTTP_VERSION_1_1 Enforce HTTP 1.1 requests. +.IP CURLOPT_IGNORE_CONTENT_LENGTH +Ignore the Content-Length header. This is useful for Apache 1.x which will +report incorrect content length for files over 2 gigabytes. If this option +is used, curl will not be able to accurately report progress, and will +simply stop the download when the server ends the connection. .RE .SH FTP OPTIONS .IP CURLOPT_FTPPORT -- cgit v1.2.1 From 573350637ef63a39740e46b1abac711f91e4b52c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 25 Aug 2005 07:06:15 +0000 Subject: CURLINFO_COOKIELIST is added in 7.14.1 --- docs/libcurl/curl_easy_getinfo.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 27fca27e6..75b93e3a5 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -137,10 +137,10 @@ to make persistent connections to save time. (Added in 7.12.3) .IP CURLINFO_COOKIELIST Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all cookies cURL knows (expired ones, too). Don't forget to -\fIcurl_slist_free_all(3)\fP the list after it has been used. -If there are no cookies (cookies for the handle have not been enabled or -simply none have been received) 'struct curl_slist *' will be set to -point to NULL. +\fIcurl_slist_free_all(3)\fP the list after it has been used. If there are no +cookies (cookies for the handle have not been enabled or simply none have been +received) 'struct curl_slist *' will be set to point to NULL. (Added in +7.14.1) .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. -- cgit v1.2.1 From 54887af4717ca54dc7e539c47f4396282efabcc6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 25 Aug 2005 07:06:50 +0000 Subject: "Added in 7.14.1" notes and some minor edits --- docs/libcurl/curl_easy_setopt.3 | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 07f6f09e5..68fc0f328 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -284,15 +284,16 @@ be prefixed with [protocol]:// since any such prefix will be ignored. The proxy's port number may optionally be specified with the separate option \fICURLOPT_PROXYPORT\fP. -\fBNOTE:\fP when you tell the library to use an HTTP proxy, libcurl will -transparently convert operations to HTTP even if you specify an FTP URL -etc. This may have an impact on what other features of the library you can -use, such as \fICURLOPT_QUOTE\fP and similar FTP specifics that don't work -unless you tunnel through the HTTP proxy. Such tunneling is activated with +When you tell the library to use an HTTP proxy, libcurl will transparently +convert operations to HTTP even if you specify an FTP URL etc. This may have +an impact on what other features of the library you can use, such as +\fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you +tunnel through the HTTP proxy. Such tunneling is activated with \fICURLOPT_HTTPPROXYTUNNEL\fP. -\fBNOTE2:\fP libcurl respects the environment variables \fBhttp_proxy\fP, -\fBftp_proxy\fP, \fBall_proxy\fP etc, if any of those is set. +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 +does however override any possibly set environment variables. Starting with 7.14.1, the proxy host string can be specified the exact same way as the proxy environment variables, include protocol prefix (http://) and @@ -667,7 +668,7 @@ existing for this "session" only. Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL cookie engine was not enabled it will enable its cookie engine. Passing a -magic string \&"ALL" will erase all cookies known by cURL. +magic string \&"ALL" will erase all cookies known by cURL. (Added in 7.14.1) .IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. usable if a POST, HEAD, PUT or a custom request have been used @@ -688,10 +689,11 @@ Enforce HTTP 1.0 requests. .IP CURL_HTTP_VERSION_1_1 Enforce HTTP 1.1 requests. .IP CURLOPT_IGNORE_CONTENT_LENGTH -Ignore the Content-Length header. This is useful for Apache 1.x which will -report incorrect content length for files over 2 gigabytes. If this option -is used, curl will not be able to accurately report progress, and will -simply stop the download when the server ends the connection. +Ignore the Content-Length header. This is useful for Apache 1.x (and similar +servers) which will report incorrect content length for files over 2 +gigabytes. If this option is used, curl will not be able to accurately report +progress, and will simply stop the download when the server ends the +connection. (added in 7.14.1) .RE .SH FTP OPTIONS .IP CURLOPT_FTPPORT -- cgit v1.2.1 From 0177ed6f030afe66cf47e4c8ef659ccfcd890b73 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 1 Sep 2005 13:41:29 +0000 Subject: clarify that the ctxfunc is called on all new connects --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 68fc0f328..ea009ca6c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -233,6 +233,9 @@ perform operation will return the error code from this callback function. Set the \fIparm\fP argument with the \fICURLOPT_SSL_CTX_DATA\fP option. This option was introduced in 7.11.0. +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. + \fBNOTE:\fP 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 callbacks to add additional validation code for certificates, and even -- cgit v1.2.1 From 7e845e7cfdd658caccc60f687d5d5d68d7e88937 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 4 Sep 2005 05:16:06 +0000 Subject: Added FTP_SKIP_PASV_IP and --ftp-skip-pasv-ip --- docs/libcurl/curl_easy_setopt.3 | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ea009ca6c..aa351e959 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -767,6 +767,14 @@ curl is waiting for a response, this value overrides \fICURLOPT_TIMEOUT\fP. It is recommended that if used in conjunction with \fICURLOPT_TIMEOUT\fP, you set \fICURLOPT_FTP_RESPONSE_TIMEOUT\fP to a value smaller than \fICURLOPT_TIMEOUT\fP. (Added in 7.10.8) +.IP CURLOPT_FTP_SKIP_PASV_IP +Pass a long. If set to a non-zero value, it instructs libcurl to not use the +IP address the server suggests in its 227-response to libcurl's PASV command +when libcurl connects the data connection. Instead libcurl will re-use the +same IP address it already uses for the control connection. But it will use +the port number from the 227-response. (Added in 7.14.1) + +This option has no effect if PORT, EPRT or EPSV is used instead of PASV. .IP CURLOPT_FTP_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) -- cgit v1.2.1 From e369270f88c86dc6c0acdd2665cc7064b20d8de9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 4 Sep 2005 05:23:08 +0000 Subject: 7.14.2 actually --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index aa351e959..3153042d4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "28 Jul 2005" "libcurl 7.14.1" "libcurl Manual" +.TH curl_easy_setopt 3 "4 Sep 2005" "libcurl 7.14.2" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -772,7 +772,7 @@ Pass a long. If set to a non-zero value, it instructs libcurl to not use the IP address the server suggests in its 227-response to libcurl's PASV command when libcurl connects the data connection. Instead libcurl will re-use the same IP address it already uses for the control connection. But it will use -the port number from the 227-response. (Added in 7.14.1) +the port number 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_FTP_SSL -- cgit v1.2.1 From 0b7f5ad508337f2c9647debf19cbd5fbffda3484 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 Sep 2005 20:36:17 +0000 Subject: CURLOPT_BUFFERSIZE clarification --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3153042d4..d92dd5396 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -331,10 +331,14 @@ thread-safe and this will use a global variable. to using the share interface instead! See \fICURLOPT_SHARE\fP and \fIcurl_share_init(3)\fP. .IP CURLOPT_BUFFERSIZE -Pass a long specifying your preferred size for the receive buffer in libcurl. -The main point of this would be that the write callback gets called more often -and with smaller chunks. This is just treated as a request, not an order. You -cannot be guaranteed to actually get the given size. (Added in 7.10) +Pass a long specifying your preferred size (in bytes) for the receive buffer +in libcurl. The main point of this would be that the write callback gets +called more often and with smaller chunks. This is just treated as a request, +not an order. You cannot be guaranteed to actually get the given size. (Added +in 7.10) + +This size is by default set as big as possible (CURL_MAX_WRITE_SIZE), so it +only makse sense to use this option if you want it smaller. .IP CURLOPT_PORT Pass a long specifying what remote port number to connect to, instead of the one specified in the URL or the default port for the used protocol. -- cgit v1.2.1 From e3bdb98f7a07ca7c8c12b4d7960936398e6b73d4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 21 Sep 2005 06:07:41 +0000 Subject: oops, broken sentence fixed: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=329305 --- docs/libcurl/libcurl-tutorial.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 1610fa559..0a0a5f095 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -243,7 +243,7 @@ where it'll store a human readable error message as well. If you then want to transfer another file, the handle is ready to be used again. Mind you, it is even preferred that you re-use an existing handle if you intend to make another transfer. libcurl will then attempt to re-use the -previous +previous connection. .SH "Multi-threading Issues" The first basic rule is that you must \fBnever\fP share a libcurl handle (be -- cgit v1.2.1 From 774dab58f6bba7ba727e448ee6c837b8b51b400d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 21 Sep 2005 06:12:41 +0000 Subject: mention what WRITEFUNCTION and WRITEDATA do by default --- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d92dd5396..20510b4af 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -96,6 +96,10 @@ transfer and return \fICURLE_WRITE_ERROR\fP. This function may be called with zero bytes data if the transfered file is empty. +Set this option to NULL to get the internal default function. The internal +default function will write the data to the FILE * given with +\fICURLOPT_WRITEDATA\fP. + Set the \fIstream\fP argument with the \fICURLOPT_WRITEDATA\fP option. \fBNOTE:\fP you will be passed as much data as possible in all invokes, but @@ -108,6 +112,9 @@ Data pointer to pass to the file write function. Note that if you specify the don't use a callback, you must pass a 'FILE *' as libcurl will pass this to fwrite() when writing data. +The internal \fICURLOPT_WRITEFUNCTION\fP will write the data to the FILE * +given with this option, or to stdout if this option hasn't been set. + \fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use the \fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience crashes. -- cgit v1.2.1 From 6af5ea38ce25d30a9065275a6dbf62099e0a752c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 21 Sep 2005 06:59:01 +0000 Subject: clarified ERRORBUFFER - some errors just don't write a string even though they should. And I removed all uses 'Note' (as they are pretty useless) and did some other language and phrasing cleanups. --- docs/libcurl/curl_easy_setopt.3 | 199 ++++++++++++++++++++-------------------- 1 file changed, 101 insertions(+), 98 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 20510b4af..fe54aeebd 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -44,11 +44,11 @@ between transfers, so if you want subsequent transfers with different options, you must change them between the transfers. You can optionally reset all options back to internal default with \fIcurl_easy_reset(3)\fP. -\fBNOTE:\fP strings passed to libcurl as 'char *' arguments, will not be -copied by the library. Instead you should keep them available until libcurl no -longer needs them. Failing to do so will cause very odd behavior or even -crashes. libcurl will need them until you call \fIcurl_easy_cleanup(3)\fP or -you set the same option again to use a different pointer. +Strings passed to libcurl as 'char *' arguments, will not be copied by the +library. Instead you should keep them available until libcurl no longer needs +them. Failing to do so will cause very odd behavior or even crashes. libcurl +will need them until you call \fIcurl_easy_cleanup(3)\fP or you set the same +option again to use a different pointer. The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. @@ -70,8 +70,8 @@ preceding the data (like HTTP). A non-zero parameter tells the library to shut off the built-in progress meter completely. -\fBNOTE:\fP future versions of libcurl is likely to not have any built-in -progress meter at all. +Future versions of libcurl is likely to not have any built-in progress meter +at all. .IP CURLOPT_NOSIGNAL Pass a long. If it is non-zero, libcurl will not use any functions that install signal handlers or any functions that cause signals to be sent to the @@ -102,20 +102,20 @@ default function will write the data to the FILE * given with Set the \fIstream\fP argument with the \fICURLOPT_WRITEDATA\fP option. -\fBNOTE:\fP you will be passed as much data as possible in all invokes, but -you cannot possibly make any assumptions. It may be one byte, it may be +The callback function will be passed as much data as possible in all invokes, +but you cannot possibly make any assumptions. It may be one byte, it may be thousands. The maximum amount of data that can be passed to the write callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE. .IP CURLOPT_WRITEDATA -Data pointer to pass to the file write function. Note that if you specify the -\fICURLOPT_WRITEFUNCTION\fP, this is the pointer you'll get as input. If you -don't use a callback, you must pass a 'FILE *' as libcurl will pass this to -fwrite() when writing data. +Data pointer to pass to the file write function. If you use the +\fICURLOPT_WRITEFUNCTION\fP option, this is the pointer you'll get as +input. If you don't use a callback, you must pass a 'FILE *' as libcurl will +pass this to fwrite() when writing data. The internal \fICURLOPT_WRITEFUNCTION\fP will write the data to the FILE * given with this option, or to stdout if this option hasn't been set. -\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use the +If you're using libcurl as a win32 DLL, you \fBMUST\fP use the \fICURLOPT_WRITEFUNCTION\fP if you set this option or you will experience crashes. @@ -140,11 +140,11 @@ In libcurl 7.12.1 and later, the read callback may return \fICURL_READFUNC_ABORT\fP to stop the current operation at once, with a \fICURLE_ABORTED_BY_CALLBACK\fP error code from the transfer. .IP CURLOPT_READDATA -Data pointer to pass to the file read function. Note that if you specify the -\fICURLOPT_READFUNCTION\fP, this is the pointer you'll get as input. If you -don't specify a read callback, this must be a valid FILE *. +Data pointer to pass to the file read function. If you use the +\fICURLOPT_READFUNCTION\fP option, this is the pointer you'll get as input. If +you don't specify a read callback, this must be a valid FILE *. -\fBNOTE:\fP If you're using libcurl as a win32 DLL, you MUST use a +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 @@ -170,8 +170,8 @@ data, the upload size will remain 0). Returning a non-zero value from this callback will cause libcurl to abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. -Also note that \fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this -function actually get called. +\fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually +get called. .IP CURLOPT_PROGRESSDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. @@ -243,10 +243,10 @@ option was introduced in 7.11.0. 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. -\fBNOTE:\fP 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 callbacks to add additional validation code for certificates, and even -to change the actual URI of an HTTPS request (example used in the lib509 test +To use this properly, a non-trivial amount of knowledge of the openssl +libraries is necessary. Using this function allows for example 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 and trust file settings. .IP CURLOPT_SSL_CTX_DATA @@ -256,14 +256,21 @@ parameter, otherwise \fBNULL\fP. (Added in 7.11.0) .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error -messages in. This may be more helpful than just the return code from the -library. The buffer must be at least CURL_ERROR_SIZE big. +messages in. This may be more helpful than just the return code from +\fIcurl_easy_perform\fP. The buffer must be at least CURL_ERROR_SIZE big. Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better debug/trace why errors happen. -\fBNote:\fP if the library does not return an error, the buffer may not have -been touched. Do not rely on the contents in those cases. +If the library does not return an error, the buffer may not have been +touched. Do not rely on the contents in those cases. + +In a few rare cases, there is no text string associated with the error in +libcurl and then you may not get a string in the buffer even though it returns +an error. This is considered a bug and we appreciate your reports about these +cases. Anyway, you can avoid problems with these cases in your program by +making sure to clear the first byte of the error buffer before you call +curl_easy_perform(). .IP CURLOPT_STDERR Pass a FILE * as parameter. Tell libcurl to use this stream instead of stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data. @@ -284,7 +291,7 @@ given protocol of the set URL is not supported, libcurl will return on error \fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info on which protocols that are supported. -\fBNOTE:\fP \fICURLOPT_URL\fP is the only option that must be set before +\fICURLOPT_URL\fP is the only option that must be set before \fIcurl_easy_perform(3)\fP is called. .IP CURLOPT_PROXY Set HTTP proxy to use. The parameter should be a char * to a zero terminated @@ -317,9 +324,9 @@ this are \fICURLPROXY_HTTP\fP and \fICURLPROXY_SOCKS5\fP, with the HTTP one being default. (Added in 7.10) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations -through a given HTTP proxy. Note that 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. +through a 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 @@ -371,9 +378,9 @@ This parameter controls the preference of libcurl between using user names and passwords from your \fI~/.netrc\fP file, relative to user names and passwords in the URL supplied with \fICURLOPT_URL\fP. -\fBNote:\fP libcurl uses a user name (and supplied or prompted password) -supplied with \fICURLOPT_USERPWD\fP in preference to any of the options -controlled by this parameter. +libcurl uses a user name (and supplied or prompted password) supplied with +\fICURLOPT_USERPWD\fP in preference to any of the options controlled by this +parameter. Pass a long, set to one of the values described below. .RS @@ -397,9 +404,8 @@ and to search the file with the host only. Only machine name, user name and password are taken into account (init macros and similar things aren't supported). -\fBNote:\fP libcurl does not verify that the file has the correct properties -set (as the standard Unix ftp client does). It should only be readable by -user. +libcurl does not verify that the file has the correct properties set (as the +standard Unix ftp client does). It should only be readable by user. .IP CURLOPT_NETRC_FILE Pass a char * as parameter, pointing to a zero terminated string containing the full path name to the file you want libcurl to use as .netrc file. If this @@ -424,9 +430,9 @@ Pass a long as parameter, which is set to a bitmask, to tell libcurl what 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 -it to use. Note that for some methods, this will induce an extra network -round-trip. Set the actual name and password with the \fICURLOPT_USERPWD\fP -option. (Added in 7.10.6) +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. (Added in +7.10.6) .RS .IP CURLAUTH_BASIC HTTP Basic authentication. This is the default choice, and the only method @@ -444,15 +450,13 @@ applications. It is primarily meant as a support for Kerberos5 authentication but may be also used along with another authentication methods. For more information see IETF draft draft-brezak-spnego-http-04.txt. -\fBNOTE\fP that you need to build libcurl with a suitable GSS-API library for -this to work. +You need to build libcurl with a suitable GSS-API library for this to work. .IP CURLAUTH_NTLM HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being eavesdropped. -\fBNOTE\fP that you need to build libcurl with SSL support for this option to -work. +You need to build libcurl with SSL support for this option to work. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most @@ -467,11 +471,11 @@ Pass a long as parameter, which is set to a bitmask, to tell libcurl what 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 -use. Note that for some methods, this will induce an extra network -round-trip. Set the actual name and password with the -\fICURLOPT_PROXYUSERPWD\fP option. The bitmask can be constructed by or'ing -together the bits listed above for the \fICURLOPT_HTTPAUTH\fP option. As of -this writing, only Basic, Digest and NTLM work. (Added in 7.10.7) +use. For some methods, this will induce an extra network round-trip. Set the +actual name and password with the \fICURLOPT_PROXYUSERPWD\fP option. The +bitmask can be constructed by or'ing together the bits listed above for the +\fICURLOPT_HTTPAUTH\fP option. As of this writing, only Basic, Digest and NTLM +work. (Added in 7.10.7) .SH HTTP OPTIONS .IP CURLOPT_AUTOREFERER Pass a non-zero parameter to enable this. When enabled, libcurl will @@ -494,14 +498,14 @@ lib/README.encoding for details. A non-zero parameter tells the library to follow any Location: header that the server sends as part of an HTTP header. -\fBNOTE:\fP this means that the library will re-send the same request on the -new location and follow new Location: headers all the way until no more such -headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number -of redirects libcurl will follow. +This means that the library will re-send the same request on the new location +and follow new Location: headers all the way until no more such headers are +returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects +libcurl will follow. .IP CURLOPT_UNRESTRICTED_AUTH A non-zero parameter tells the library it can continue to send authentication -(user+password) when following locations, even when hostname changed. Note -that this is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. +(user+password) when following locations, even when hostname changed. This +option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. .IP CURLOPT_MAXREDIRS Pass a long. The set number will be the redirection limit. If that many redirections have been followed, the next redirect will cause an error @@ -560,8 +564,8 @@ commonly used one by HTML forms. See also the \fICURLOPT_POST\fP. Using Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. -\fBNote:\fP to make multipart/formdata posts (aka rfc1867-posts), check out -the \fICURLOPT_HTTPPOST\fP option. +To make multipart/formdata posts (aka rfc1867-posts), check out the +\fICURLOPT_HTTPPOST\fP option. .IP CURLOPT_POSTFIELDSIZE If you want to post data to the server without letting libcurl do a strlen() to measure the data size, this option must be used. When this option is used @@ -616,7 +620,7 @@ request-line are headers. Pass a NULL to this to reset back to no custom headers. -\fBNOTE:\fP The most commonly replaced headers have "shortcuts" in the options +The most commonly replaced headers have "shortcuts" in the options \fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP. .IP CURLOPT_HTTP200ALIASES Pass a pointer to a linked list of aliases to be treated as valid HTTP 200 @@ -629,9 +633,9 @@ The linked list should be a fully valid list of struct curl_slist structs, and be 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. -\fBNOTE:\fP The alias itself is not parsed for any version strings. So if your -alias is "MYHTTP/9.9", Libcurl will not treat the server as responding with -HTTP version 9.9. Instead Libcurl will use the value set by option +The alias itself is not parsed for any version strings. So if your alias is +\&"MYHTTP/9.9", Libcurl will not treat the server as responding with HTTP +version 9.9. Instead Libcurl will use the value set by option \fICURLOPT_HTTP_VERSION\fP. .IP CURLOPT_COOKIE Pass a pointer to a zero terminated string as parameter. It will be used to @@ -666,7 +670,7 @@ instead have the cookies written to stdout. Using this option also enables cookies for this session, so if you for example follow a location it will make matching cookies get sent accordingly. -\fBNOTE:\fP If the cookie jar file can't be created or written to (when the +If the cookie jar file can't be created or written to (when the \fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an error for this. Using \fICURLOPT_VERBOSE\fP or \fICURLOPT_DEBUGFUNCTION\fP will get a warning to display, but that is the only visible feedback you get @@ -773,9 +777,9 @@ directory. (Added in 7.10.7) .IP CURLOPT_FTP_RESPONSE_TIMEOUT Pass a long. Causes curl to set a timeout period (in seconds) on the amount of time that the server is allowed to take in order to generate a response -message for a command before the session is considered hung. Note that while -curl is waiting for a response, this value overrides \fICURLOPT_TIMEOUT\fP. It -is recommended that if used in conjunction with \fICURLOPT_TIMEOUT\fP, you set +message for a command before the session is considered hung. While curl is +waiting for a response, this value overrides \fICURLOPT_TIMEOUT\fP. It is +recommended that if used in conjunction with \fICURLOPT_TIMEOUT\fP, you set \fICURLOPT_FTP_RESPONSE_TIMEOUT\fP to a value smaller than \fICURLOPT_TIMEOUT\fP. (Added in 7.10.8) .IP CURLOPT_FTP_SKIP_PASV_IP @@ -835,10 +839,9 @@ stdout to binary mode. This option can be usable when transferring text data between systems with different views on certain characters, such as newlines or similar. -\fBNOTE:\fP 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. +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. .IP CURLOPT_CRLF Convert Unix newlines to CRLF newlines on transfers. .IP CURLOPT_RANGE @@ -864,11 +867,11 @@ server supports the command first. Restore to the internal default by setting this to NULL. -\fBNOTE:\fP Many people have wrongly used this option to replace the entire -request with their own, including multiple headers and POST contents. While -that might work in many cases, it will cause libcurl to send invalid requests -and it could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP -and \fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to +Many people have wrongly used this option to replace the entire request with +their own, including multiple headers and POST contents. While that might work +in many cases, it will cause libcurl to send invalid requests and it could +possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and +\fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to replace or extend the set of headers sent by libcurl. Use \fICURLOPT_HTTP_VERSION\fP to change HTTP version. .IP CURLOPT_FILETIME @@ -912,26 +915,26 @@ Pass a long as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and CURLE_FILESIZE_EXCEEDED will be returned. -\fBNOTE:\fP The file size is not always known prior to download, and for such -files this option has no effect even if the file transfer ends up being larger -than this given limit. This concerns both FTP and HTTP transfers. +The file size is not always known prior to download, and for such files this +option has no effect even if the file transfer ends up being larger than this +given limit. This concerns both FTP and HTTP transfers. .IP CURLOPT_MAXFILESIZE_LARGE Pass a curl_off_t as parameter. This allows you to specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer will not start and \fICURLE_FILESIZE_EXCEEDED\fP will be returned. (Added in 7.11.0) -\fBNOTE:\fP The file size is not always known prior to download, and for such -files this option has no effect even if the file transfer ends up being larger -than this given limit. This concerns both FTP and HTTP transfers. +The file size is not always known prior to download, and for such files this +option has no effect even if the file transfer ends up being larger than this +given limit. This concerns both FTP and HTTP transfers. .IP CURLOPT_TIMECONDITION Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time 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. -\fBNOTE:\fP 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. +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. .IP CURLOPT_TIMEVALUE 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 @@ -944,8 +947,8 @@ considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations. This option will cause curl to use the SIGALRM to enable time-outing system calls. -\fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as -it uses signals unless \fICURLOPT_NOSIGNAL\fP (see above) is set. +In unix-like systems, this might cause signals to be used unless +\fICURLOPT_NOSIGNAL\fP is set. .IP CURLOPT_LOW_SPEED_LIMIT Pass a long as parameter. It contains the transfer speed in bytes per second that the transfer should be below during \fICURLOPT_LOW_SPEED_TIME\fP seconds @@ -966,9 +969,9 @@ When reaching the maximum limit, curl uses the \fICURLOPT_CLOSEPOLICY\fP to figure out which of the existing connections to close to prevent the number of open connections to increase. -\fBNOTE:\fP if you already have performed transfers with this curl handle, -setting a smaller MAXCONNECTS than before may cause open connections to get -closed unnecessarily. +If you already have performed transfers with this curl handle, setting a +smaller MAXCONNECTS than before may cause open connections to get closed +unnecessarily. .IP CURLOPT_CLOSEPOLICY Pass a long. This option sets what policy libcurl should use when the connection cache is filled and one of the open connections has to be closed to @@ -1000,8 +1003,8 @@ it has connected, this option is of no more use. Set to zero to disable connection timeout (it will then only timeout on the system's internal timeouts). See also the \fICURLOPT_TIMEOUT\fP option. -\fBNOTE:\fP this is not recommended to use in unix multi-threaded programs, as -it uses signals unless \fICURLOPT_NOSIGNAL\fP (see above) is set. +In unix-like systems, this might cause signals to be used unless +\fICURLOPT_NOSIGNAL\fP is set. .IP CURLOPT_IPRESOLVE Allows an application to select what kind of IP addresses to use when resolving host names. This is only interesting when using host names that @@ -1038,9 +1041,9 @@ changed with \fICURLOPT_SSLKEYTYPE\fP. Pass a pointer to a zero terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG". -\fBNOTE:\fP The format "ENG" enables you to load the private key from a crypto -engine. In this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to -the engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE\fP. +The format "ENG" enables you to load the private key from a crypto engine. In +this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to the +engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE\fP. \&"DER" format key file currently does not work because of a bug in OpenSSL. .IP CURLOPT_SSLKEYPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as @@ -1050,14 +1053,14 @@ Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private key. -\fBNOTE:\fP If the crypto device cannot be loaded, -\fICURLE_SSL_ENGINE_NOTFOUND\fP is returned. +If the crypto device cannot be loaded, \fICURLE_SSL_ENGINE_NOTFOUND\fP is +returned. .IP CURLOPT_SSLENGINE_DEFAULT Sets the actual crypto engine as the default for (asymmetric) crypto operations. -\fBNOTE:\fP If the crypto device cannot be set, -\fICURLE_SSL_ENGINE_SETFAILED\fP is returned. +If the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is +returned. .IP CURLOPT_SSLVERSION Pass a long as parameter to control what version of SSL/TLS to attempt to use. The available options are: -- cgit v1.2.1 From da192f79553fb1b6eb112fd68cee7b01e0a56540 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Sep 2005 10:15:10 +0000 Subject: clarify what the default read callback does and how it uses the READDATA option --- docs/libcurl/curl_easy_setopt.3 | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index fe54aeebd..565527f7a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "4 Sep 2005" "libcurl 7.14.2" "libcurl Manual" +.TH curl_easy_setopt 3 "22 Sep 2005" "libcurl 7.14.2" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -136,13 +136,18 @@ server expected it, like when you've told 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. -In libcurl 7.12.1 and later, the read callback may return -\fICURL_READFUNC_ABORT\fP to stop the current operation at once, with a -\fICURLE_ABORTED_BY_CALLBACK\fP error code from the transfer. +The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current +operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error +code from the transfer (Added in 7.12.1) + +If you set the callback pointer to NULL, or doesn'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 Data pointer to pass to the file read function. If you use the \fICURLOPT_READFUNCTION\fP option, this is the pointer you'll get as input. If -you don't specify a read callback, this must be a valid FILE *. +you don't specify a read callback but instead rely on the default internal +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. -- cgit v1.2.1 From 6d9fddb95dbc0a4286e78370738c724732243110 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 Oct 2005 10:58:14 +0000 Subject: Domenico Andreoli's SEE ALSO patch --- docs/libcurl/curl_escape.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index c10a87864..66eba1477 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -23,4 +23,4 @@ You must curl_free() the returned string when you're done with it. .SH RETURN VALUE A pointer to a zero terminated string or NULL if it failed. .SH "SEE ALSO" -.BR curl_unescape(3), curl_free(3), RFC 2396 +.BR curl_unescape "(3), " curl_free "(3), " RFC 2396 -- cgit v1.2.1 From e5b2f33b4f90741e895c19a5e43ed4a1923e0475 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 6 Oct 2005 08:58:44 +0000 Subject: Added the info from getinfo-times as it really belongs in this man page. --- docs/libcurl/curl_easy_getinfo.3 | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 75b93e3a5..7c7b7c261 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_getinfo 3 "22 Dec 2004" "libcurl 7.12.3" "libcurl Manual" +.TH curl_easy_getinfo 3 "6 Oct 2005" "libcurl 7.12.3" "libcurl Manual" .SH NAME curl_easy_getinfo - extract information from a curl handle .SH SYNOPSIS @@ -141,6 +141,40 @@ cookies cURL knows (expired ones, too). Don't forget to cookies (cookies for the handle have not been enabled or simply none have been received) 'struct curl_slist *' will be set to point to NULL. (Added in 7.14.1) +.SH TIMES +.NF +An overview of the six time values available from curl_easy_getinfo() + +curk_easy_perform() + | + |--NT + |--|--CT + |--|--|--PT + |--|--|--|--ST + |--|--|--TT + |--|--|--|--|--RT + +.IP NT +CURLINFO_NAMELOOKUP_TIME. The time it took from the start until the name +resolving was completed. +.IP CT +CURLINFO_CONNECT_TIME. The time it took from the start until the connect to +the remote host (or proxy) was completed. +.IP PT +CURLINFO_PRETRANSFER_TIME. The time it took from the start until the file +transfer is just about to begin. This includes all pre-transfer commands and +negotiations that are specific to the particular protocol(s) involved. +.IP ST +CURLINFO_STARTTRANSFER_TIME. The time it took from the start until the first +byte is just about to be transferred. +.IP TT +CURLINFO_TOTAL_TIME. Time of the previous transfer. This time does not include +the connect time (CT), so if you want the complete operation time, you should +add that. +.IP RT +CURLINFO_REDIRECT_TIME. The time it took for all redirection steps include +name lookup, connect, pretransfer and transfer before final transaction was +started. So, this is zero if no redirection took place. .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. -- cgit v1.2.1 From 89df76e449b81e08d6a28760d4db5a7b61821238 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 6 Oct 2005 09:03:36 +0000 Subject: end the .nf section, mark the option names properly so that they end up as links in the html version --- docs/libcurl/curl_easy_getinfo.3 | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 7c7b7c261..bc4f2063b 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -153,28 +153,28 @@ curk_easy_perform() |--|--|--|--ST |--|--|--TT |--|--|--|--|--RT - +.FI .IP NT -CURLINFO_NAMELOOKUP_TIME. The time it took from the start until the name +\fICURLINFO_NAMELOOKUP_TIME\fP. The time it took from the start until the name resolving was completed. .IP CT -CURLINFO_CONNECT_TIME. The time it took from the start until the connect to -the remote host (or proxy) was completed. +\fICURLINFO_CONNECT_TIME\fP. The time it took from the start until the connect +to the remote host (or proxy) was completed. .IP PT -CURLINFO_PRETRANSFER_TIME. The time it took from the start until the file -transfer is just about to begin. This includes all pre-transfer commands and -negotiations that are specific to the particular protocol(s) involved. +\fICURLINFO_PRETRANSFER_TIME\fP. The time it took from the start until the +file transfer is just about to begin. This includes all pre-transfer commands +and negotiations that are specific to the particular protocol(s) involved. .IP ST -CURLINFO_STARTTRANSFER_TIME. The time it took from the start until the first -byte is just about to be transferred. +\fICURLINFO_STARTTRANSFER_TIME\fP. The time it took from the start until the +first byte is just about to be transferred. .IP TT -CURLINFO_TOTAL_TIME. Time of the previous transfer. This time does not include -the connect time (CT), so if you want the complete operation time, you should -add that. +\fICURLINFO_TOTAL_TIME\fP. Time of the previous transfer. This time does not +include the connect time (CT), so if you want the complete operation time, you +should add that. .IP RT -CURLINFO_REDIRECT_TIME. The time it took for all redirection steps include -name lookup, connect, pretransfer and transfer before final transaction was -started. So, this is zero if no redirection took place. +\fICURLINFO_REDIRECT_TIME\fP. The time it took for all redirection steps +include name lookup, connect, pretransfer and transfer before final +transaction was started. So, this is zero if no redirection took place. .SH RETURN VALUE If the operation was successful, CURLE_OK is returned. Otherwise an appropriate error code will be returned. -- cgit v1.2.1 From d3569a357224f20265a330e999c78ae8db81f46b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 6 Oct 2005 09:05:08 +0000 Subject: remove getinfo-times from the dist archive since the info is now in the curl_easy_getinfo man page --- docs/libcurl/Makefile.am | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index de7fd95dd..caea9b9aa 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -52,8 +52,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 \ - getinfo-times +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 MAN2HTML= roffit --mandir=. < $< >$@ -- cgit v1.2.1 From b433e4a1e78b4a93857779ab3997ad88efa38140 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 13 Oct 2005 06:20:43 +0000 Subject: NTLM requires windows or OpenSSL. If you build with GnuTLS for example you do not get NTLM support enabled. --- docs/libcurl/curl_easy_setopt.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 565527f7a..818502969 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -461,7 +461,8 @@ HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being eavesdropped. -You need to build libcurl with SSL support for this option to work. +You need to build libcurl with OpenSSL support for this option to work, or +build libcurl on Windows. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most -- cgit v1.2.1 From 82a4c2bce3c7a7834bd18920aee2f22d42a2ebb3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 13 Oct 2005 21:49:28 +0000 Subject: Slight editing of wording in the CURLOPT_SSL_VERIFYHOST section. --- docs/libcurl/curl_easy_setopt.3 | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 818502969..99e57e684 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1132,26 +1132,25 @@ socket. It will be used to seed the random engine for SSL. .IP CURLOPT_SSL_VERIFYHOST Pass a long as parameter. -This option determines whether curl verifies that the server claims to be -who you want it to be. +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 its identity. +When negotiating an SSL connection, the server sends a certificate indicating +its identity. -When \fICURLOPT_SSL_VERIFYHOST\fP is 2, that certificate must indicate -that the server is the server to which you meant to connect, or the -connection fails. +When \fICURLOPT_SSL_VERIFYHOST\fP is 2, that certificate must indicate that +the server is the server to which you meant to connect, or the connection +fails. -Curl considers the server the intended one when the Common Name field -or a Subject Alternate Name field in the certificate matches the host -name in the URL to which you told Curl to connect. +Curl considers the server the intended one when the Common Name field or a +Subject Alternate Name field in the certificate matches the host name in the +URL to which you told Curl to connect. -When the value is 1, the certificate must contain a Common Name field, -but it doesn't matter what name it says. (This is not ordinarily a -useful setting). +When the value is 1, the certificate must contain a Common Name field, but it +doesn't matter what name it says. (This is not ordinarily a useful setting). -When the value is 0, the connection succeeds regardless of the names in -the certificate. +When the value is 0, the connection succeeds regardless of the names in the +certificate. The default, since 7.10, is 2. -- cgit v1.2.1 From 966fa848a0213be52d3a4b3787c36ec7c5553f22 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 27 Oct 2005 22:05:38 +0000 Subject: Nis Jorgensen filed bug report #1338648 (http://curl.haxx.se/bug/view.cgi?id=1338648) which really is more of a feature request, but anyway. It pointed out that --max-redirs did not allow it to be set to 0, which then would return an error code on the first Location: found. Based on Nis' patch, now libcurl supports CURLOPT_MAXREDIRS set to 0, or -1 for infinity. Added test case 274 to verify. --- docs/libcurl/curl_easy_setopt.3 | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 99e57e684..3e49643e9 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "22 Sep 2005" "libcurl 7.14.2" "libcurl Manual" +.TH curl_easy_setopt 3 "27 Oct 2005" "libcurl 7.14.2" "libcurl Manual" .SH NAME curl_easy_setopt - set options for a curl easy handle .SH SYNOPSIS @@ -516,7 +516,9 @@ option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. Pass a long. The set number will be the redirection limit. If that many redirections have been followed, the next redirect will cause an error (\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the -\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. +\fICURLOPT_FOLLOWLOCATION\fP is used at the same time. Added in 7.15.1: +Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for +an infinite number of redirects (which is the default) .IP CURLOPT_PUT A non-zero parameter tells the library to use HTTP PUT to transfer data. The data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP. -- cgit v1.2.1 From 89024febde5a58322099ae6a5547db1555666bc4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 11 Nov 2005 08:52:29 +0000 Subject: mention how to set domain when using NTLM --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3e49643e9..8509aeb68 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -420,6 +420,11 @@ find the a .netrc file in the current user's home directory. (Added in 7.10.9) Pass a char * as parameter, which should be [user name]:[password] to use for the connection. Use \fICURLOPT_HTTPAUTH\fP to decide authentication method. +When using NTLM, you can set 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. + When using HTTP and \fICURLOPT_FOLLOWLOCATION\fP, libcurl might perform several requests to possibly different hosts. libcurl will only send this user and password information to hosts using the initial host name (unless -- cgit v1.2.1 From 4022a60ea7f88650f1b4abfe1e41c973cca7861d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 17 Nov 2005 14:29:54 +0000 Subject: I extended a patch from David Shaw to make libcurl _always_ provide an error string in the given error buffer to address the flaw mention on 21 sep 2005. --- docs/libcurl/curl_easy_setopt.3 | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8509aeb68..0cabd0047 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -270,12 +270,6 @@ debug/trace why errors happen. If the library does not return an error, the buffer may not have been touched. Do not rely on the contents in those cases. -In a few rare cases, there is no text string associated with the error in -libcurl and then you may not get a string in the buffer even though it returns -an error. This is considered a bug and we appreciate your reports about these -cases. Anyway, you can avoid problems with these cases in your program by -making sure to clear the first byte of the error buffer before you call -curl_easy_perform(). .IP CURLOPT_STDERR Pass a FILE * as parameter. Tell libcurl to use this stream instead of stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data. -- cgit v1.2.1 From 2d71e22f086d05b4d165c338af5f91995fbd6cca Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 10 Dec 2005 22:12:44 +0000 Subject: fix CURLOPT_FAILONERROR error, pointed out by Shailesh N. Humbad --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0cabd0047..c6ba03b64 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -275,7 +275,7 @@ Pass a FILE * as parameter. Tell libcurl to use this stream instead of stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data. .IP CURLOPT_FAILONERROR A non-zero parameter tells the library to fail silently if the HTTP code -returned is equal to or larger than 300. The default action would be to return +returned is equal to or larger than 400. The default action would be to return the page normally, ignoring that code. .SH NETWORK OPTIONS .IP CURLOPT_URL -- cgit v1.2.1 From a718cb05ff4405dd5a3e09b718413b5066fc5e09 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Dec 2005 15:11:11 +0000 Subject: The inital early embryos to describe the curl_multi_socket() API. Committed now to enable them to get added as web pages easier, they are not ready for anything "real" just yet. --- docs/libcurl/curl_multi_socket.3 | 82 ++++++++++++++++++++++++++++++++++++ docs/libcurl/curl_multi_socket_all.3 | 1 + 2 files changed, 83 insertions(+) create mode 100644 docs/libcurl/curl_multi_socket.3 create mode 100644 docs/libcurl/curl_multi_socket_all.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 new file mode 100644 index 000000000..8c42a8db1 --- /dev/null +++ b/docs/libcurl/curl_multi_socket.3 @@ -0,0 +1,82 @@ +.\" $Id$ +.\" +.TH curl_multi_socket 3 "21 Dec 2005" "libcurl 7.16.0" "libcurl Manual" +.SH NAME +curl_multi_socket - reads/writes available data +.SH SYNOPSIS +#include + +CURLMcode curl_multi_socket(CURLM * multi_handle, + curl_socket_t sockfd, + CURL *easy, + curl_socket_callback callback, + void *userp); + +CURLMcode curl_multi_socket_all(CURLM *multi_handle, + curl_socket_callback callback, + void *userp); +.SH DESCRIPTION +Alternative versions of \fIcurl_multi_perform()\fP that allows the application +to pass in one of the file descriptors/sockets that have been detected to have +\&"action" on them and let libcurl perform. This allows libcurl to not have to +scan through all possible file descriptors to check for action. The +application is recommended to pass in the \fBeasy\fP argument (or set it to +CURL_EASY_NONE) to make libcurl figure out the internal structure even faster +and easier. If the easy argument is set to something else than +CURL_EASY_NONE, the \fBsockfd\fP argument will be ignored by libcurl. + +These functions inform the application about updates in the socket (file +descriptor) status by doing none, one or multiple calls to the +curl_socket_callback given in the \fBcallback\fP argument. They update the +status with changes since the previous time this function was used. If +\fBcallback\fP is NULL, no callback will be called. A status change may also +be a new timeout only, having the same IN/OUT status as before. + +If a previous wait for socket action(s) timed out, you should call this +function with the socket argument set to CURL_SOCKET_TIMEOUT. If you want to +force libcurl to (re-)check all its internal sockets, and call the callback +with status for all sockets no matter what the previous state is, you call +curl_multi_socket_all() instead. + +curl_multi_perform() is the equivalent of calling +curl_multi_socket_all(handle, NULL, NULL); + +Regarding the timeout argument in the callback: it is the timeout (in +milliseconds) for waiting on action on this socket (and the given time period +starts when the callback is called) until you should call curl_multi_socket() +with the timeout stuff mentioned above. If "actions" happens on the socket +before the timeout happens, remember that the timout timer keeps ticking until +told otherwise. + +The "what" argument has one of five values: +.RS +.IP "CURL_POLL_NONE (0)" +register, not interested in readiness (yet) +.IP "CURL_POLL_IN (1)" +register, interested in read readiness +.IP "CURL_POLL_OUT (2)" +register, interested in write readiness +.IP "CURL_POLL_INOUT (3)" +register, interested in both read and write readiness +.IP "CURL_POLL_REMOVE (4)" +deregister +.RE +.SH "RETURN VALUE" +CURLMcode type, general libcurl multi interface error code. + +If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you +should call \fIcurl_multi_perform\fP again, before you select() on more +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". + +NOTE that this only returns errors etc regarding the whole multi stack. There +might still have occurred problems on individual transfers even when this +function returns OK. +.SH "TYPICAL USAGE" +Call curl_multi_socket_all() first. Setup a "collection" of sockets to +supervise, then when action happens call curl_multi_socket() for the easy +handle that got the action. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " +.BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" diff --git a/docs/libcurl/curl_multi_socket_all.3 b/docs/libcurl/curl_multi_socket_all.3 new file mode 100644 index 000000000..428dd06f9 --- /dev/null +++ b/docs/libcurl/curl_multi_socket_all.3 @@ -0,0 +1 @@ +.so man3/curl_multi_socket.3 -- cgit v1.2.1 From 598965a6061e7c6d6adadf104c84bc7cd6cdeb07 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 23 Dec 2005 23:22:23 +0000 Subject: clarified that curl_global_init() isn't thread-safe and that it might affect curl_easy_init() if you don't call curl_global_init() explicitly in your app --- docs/libcurl/curl_easy_init.3 | 6 ++++++ docs/libcurl/curl_global_init.3 | 9 ++++++--- 2 files changed, 12 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 62a6fbc50..a9fbe792a 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -14,6 +14,12 @@ handle that you must use as input to other easy-functions. curl_easy_init initializes curl and this call \fBMUST\fP have a corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is complete. +If you did not already call \fIcurl_global_init(3)\fP, it will be done +automatically with a default setup when you call \fIcurl_easy_init(3)\fP. +This may be lethal in multi-threaded cases, since \fIcurl_global_init(3)\fP is +not thread-safe and must not be called more than once (or from more than one +thread). You are strongly adviced to not rely on this automatic behaviour, but +call \fIcurl_global_init(3)\fP yourself properly. .SH RETURN VALUE If this function returns NULL, something went wrong and you cannot use the other curl functions. diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index b408850ad..8e8ec09f4 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -15,7 +15,8 @@ This function should only be called once (no matter how many threads or libcurl sessions that'll be used) by every application that uses libcurl. If this function hasn't been invoked when \fIcurl_easy_init(3)\fP is called, -it will be done automatically by libcurl. +it will be done automatically by libcurl. It is adviced that you do not rely +on this automatic call, but instead call \fIcurl_global_init(3)\fP properly. The flags option is a bit pattern that tells libcurl exact what features to init, as described below. Set the desired bits by ORing the values together. @@ -23,8 +24,9 @@ init, as described below. Set the desired bits by ORing the values together. You must however \fBalways\fP use the \fIcurl_global_cleanup(3)\fP function, as that cannot be called automatically for you by libcurl. -Calling this function more than once will cause unpredictable results. - +Calling this function more than once will cause unpredictable results. If that +is not enough, calling this function from more than one thread may also cause +unpredictable results. .SH FLAGS .TP 5 .B CURL_GLOBAL_ALL @@ -44,3 +46,4 @@ other curl functions. .SH "SEE ALSO" .BR curl_global_init_mem "(3), " .BR curl_global_cleanup "(3), " +.BR curl_easy_init "(3) " \ No newline at end of file -- cgit v1.2.1 From fa18d6fb76253c4800b5ef2e052a8a39e210e59d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 Jan 2006 22:58:56 +0000 Subject: I removed the timeout argument from the socket callback and did some other cleanups of this man page. The lengthy description has now also been removed from curl/multi.h since it immediately got tedious to maintain the info on two places when I did major updates... --- docs/libcurl/curl_multi_socket.3 | 40 +++++++++++++++++++++++++--------------- 1 file changed, 25 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 8c42a8db1..fb118eb65 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -2,7 +2,7 @@ .\" .TH curl_multi_socket 3 "21 Dec 2005" "libcurl 7.16.0" "libcurl Manual" .SH NAME -curl_multi_socket - reads/writes available data +curl_multi_socket \- reads/writes available data .SH SYNOPSIS #include @@ -32,23 +32,31 @@ status with changes since the previous time this function was used. If \fBcallback\fP is NULL, no callback will be called. A status change may also be a new timeout only, having the same IN/OUT status as before. -If a previous wait for socket action(s) timed out, you should call this -function with the socket argument set to CURL_SOCKET_TIMEOUT. If you want to -force libcurl to (re-)check all its internal sockets, and call the callback -with status for all sockets no matter what the previous state is, you call -curl_multi_socket_all() instead. +If you want to force libcurl to (re-)check all its internal sockets and +transfers instead of just a single one, you call +\fBcurl_multi_socket_all(3)\fP instead. -curl_multi_perform() is the equivalent of calling -curl_multi_socket_all(handle, NULL, NULL); +An application should call \fBcurl_multi_timeout(3)\fP to figure out how long +it should wait for socket actions \- at most \- before doing the timeout +action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP +argument set to CURL_SOCKET_TIMEOUT and the \fBeasy\fP argument set to +CURL_EASY_TIMEOUT. -Regarding the timeout argument in the callback: it is the timeout (in -milliseconds) for waiting on action on this socket (and the given time period -starts when the callback is called) until you should call curl_multi_socket() -with the timeout stuff mentioned above. If "actions" happens on the socket -before the timeout happens, remember that the timout timer keeps ticking until -told otherwise. +\fBcurl_multi_perform(3)\fP is the exact equivalent of calling +\fBcurl_multi_socket_all\fP(handle, NULL, NULL); -The "what" argument has one of five values: +The socket \fBcallback\fP function uses a prototype like this +.nf + + int curl_socket_callback(CURL *easy, /* easy handle */ + curl_socket_t s, /* socket */ + int action, /* see values below */ + void *userp); /* "private" pointer */ + +.fi +The callback MUST return 0. + +The \fIaction\fP (third) argument to the callback has one of five values: .RS .IP "CURL_POLL_NONE (0)" register, not interested in readiness (yet) @@ -77,6 +85,8 @@ function returns OK. Call curl_multi_socket_all() first. Setup a "collection" of sockets to supervise, then when action happens call curl_multi_socket() for the easy handle that got the action. +.SH AVAILABILITY +This function was added in libcurl 7.16.0 .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" -- cgit v1.2.1 From 58d2e7c6d11e1f5b454a6f72ba8b318fe9bd1b40 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 Jan 2006 23:00:04 +0000 Subject: Initial description of the upcoming curl_multi_timeout() function --- docs/libcurl/curl_multi_timeout.3 | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/libcurl/curl_multi_timeout.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 new file mode 100644 index 000000000..636520f5c --- /dev/null +++ b/docs/libcurl/curl_multi_timeout.3 @@ -0,0 +1,35 @@ +.\" $Id$ +.\" +.TH curl_multi_timeout 3 "2 Jan 2006" "libcurl 7.16.0" "libcurl Manual" +.SH NAME +curl_multi_timeout \- how long to wait for action before proceeding +.SH SYNOPSIS +#include + +long curl_multi_timeout(CURLM *multi_handle); +.SH DESCRIPTION + +An application using the libcurl multi interface should call +\fBcurl_multi_timeout(3)\fP to figure out how long it should wait for socket +actions \- at most \- before proceeding. + +Proceeding means either doing the socket-style timeout action: call the +\fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to +CURL_SOCKET_TIMEOUT and the \fBeasy\fP argument set to CURL_EASY_TIMEOUT, or +simply calling \fBcurl_multi_perform(3)\fP if you're using the simpler and +older multi interface approach. + +.SH "RETURN VALUE" +The timeout value in number of milliseconds. If 0, it means you should proceed +immediately without waiting for anything. +.SH "TYPICAL USAGE" +Call \fBcurl_multi_timeout(3)\fP, then wait for action on the sockets. You +figure out which sockets to wait for by calling \fBcurl_multi_fdset(3)\fP or +by a previous call to \fBcurl_multi_socket(3)\fP. +.SH AVAILABILITY +This function was added in libcurl 7.16.0 +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " +.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " +.BR curl_multi_socket "(3) " + -- cgit v1.2.1 From 089e4848d83fcc00bc60afd676ee202090aca4b2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 Jan 2006 23:32:36 +0000 Subject: minor edits --- docs/libcurl/curl_easy_reset.3 | 4 ++-- docs/libcurl/curl_easy_strerror.3 | 2 +- docs/libcurl/curl_multi_fdset.3 | 8 ++++++-- docs/libcurl/curl_multi_perform.3 | 6 +++--- docs/libcurl/curl_multi_strerror.3 | 2 +- docs/libcurl/curl_share_strerror.3 | 2 +- 6 files changed, 14 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_reset.3 b/docs/libcurl/curl_easy_reset.3 index 812be4c8b..30d031610 100644 --- a/docs/libcurl/curl_easy_reset.3 +++ b/docs/libcurl/curl_easy_reset.3 @@ -15,8 +15,8 @@ it was just created with \fIcurl_easy_init(3)\fP. It does not change the following information kept in the handle: live connections, the Session ID cache, the DNS cache, the cookies and shares. - -This function was added in libcurl 7.12.1. +.SH AVAILABILITY +This function was added in libcurl 7.12.1 .SH RETURN VALUE Nothing .SH "SEE ALSO" diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 index e733da62d..be8f1b454 100644 --- a/docs/libcurl/curl_easy_strerror.3 +++ b/docs/libcurl/curl_easy_strerror.3 @@ -12,7 +12,7 @@ curl_easy_strerror - return string describing error code .SH DESCRIPTION The curl_easy_strerror() function returns a string describing the CURLcode error code passed in the argument \fIerrornum\fP. - +.SH AVAILABILITY This function was added in libcurl 7.12.0 .SH RETURN VALUE A pointer to a zero terminated string. diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 0efc68ab1..5f3cf1891 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_fdset 3 "25 Apr 2005" "libcurl 7.9.5" "libcurl Manual" +.TH curl_multi_fdset 3 "2 Jan 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_fdset - extracts file descriptor information from a multi handle .SH SYNOPSIS @@ -30,8 +30,12 @@ rather small (single-digit number of seconds) timeout and call \fIcurl_multi_perform\fP regularly - even if no activity has been seen on the fd_sets - as otherwise libcurl-internal retries and timeouts may not work as you'd think and want. + +Starting with libcurl 7.16.0, you should use \fBcurl_multi_timeout\fP to +figure out how long to wait for action. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP .SH "SEE ALSO" -.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3), " +.BR curl_multi_timeout "(3) " diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 75f72c5d8..51d3a3c34 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -36,9 +36,9 @@ NOTE that this only returns errors etc regarding the whole multi stack. There might still have occurred problems on individual transfers even when this function returns OK. .SH "TYPICAL USAGE" -Most application will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's -file descriptors, then it'll wait for action on them using select() and as -soon as one or more of them are ready, \fIcurl_multi_perform(3)\fP gets +Most applications will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's +file descriptors, then it'll wait for action on them using \fBselect(3)\fP and +as soon as one or more of them are ready, \fIcurl_multi_perform(3)\fP gets called. .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 index 8145c63f9..a08243f1d 100644 --- a/docs/libcurl/curl_multi_strerror.3 +++ b/docs/libcurl/curl_multi_strerror.3 @@ -12,7 +12,7 @@ curl_multi_strerror - return string describing error code .SH DESCRIPTION The curl_multi_strerror() function returns a string describing the CURLMcode error code passed in the argument \fIerrornum\fP. - +.SH AVAILABILITY This function was added in libcurl 7.12.0 .SH RETURN VALUE A pointer to a zero terminated string. diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 index 20c008d21..b5199d57c 100644 --- a/docs/libcurl/curl_share_strerror.3 +++ b/docs/libcurl/curl_share_strerror.3 @@ -12,7 +12,7 @@ curl_share_strerror - return string describing error code .SH DESCRIPTION The curl_share_strerror() function returns a string describing the CURLSHcode error code passed in the argument \fIerrornum\fP. - +.SH AVAILABILITY This function was added in libcurl 7.12.0 .SH RETURN VALUE A pointer to a zero terminated string. -- cgit v1.2.1 From 53b5fdbe9e953e1aadf7bfeeb15a978cd0f74c42 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Jan 2006 15:52:59 +0000 Subject: fixed the prototype --- docs/libcurl/curl_multi_timeout.3 | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index 636520f5c..a06bffbdc 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -6,7 +6,7 @@ curl_multi_timeout \- how long to wait for action before proceeding .SH SYNOPSIS #include -long curl_multi_timeout(CURLM *multi_handle); +CURLMcode curl_multi_timeout(CURLM *multi_handle, long *timeout); .SH DESCRIPTION An application using the libcurl multi interface should call @@ -19,9 +19,12 @@ CURL_SOCKET_TIMEOUT and the \fBeasy\fP argument set to CURL_EASY_TIMEOUT, or simply calling \fBcurl_multi_perform(3)\fP if you're using the simpler and older multi interface approach. +The timeout value returned in the long \fBtimeout\fP points to, is in number +of milliseconds at this very moment. If 0, it means you should proceed +immediately without waiting for anything. If it returns -1, there's no timeout +at all set. .SH "RETURN VALUE" -The timeout value in number of milliseconds. If 0, it means you should proceed -immediately without waiting for anything. +The standard CURLMcode for multi interface error codes. .SH "TYPICAL USAGE" Call \fBcurl_multi_timeout(3)\fP, then wait for action on the sockets. You figure out which sockets to wait for by calling \fBcurl_multi_fdset(3)\fP or -- cgit v1.2.1 From c1a06d858de26054fe8add4d63261ea82cc2dcb7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Jan 2006 15:53:29 +0000 Subject: CURLOPT_PROGRESSFUNCTION is really not a good idea when using the multi interface --- docs/libcurl/curl_easy_setopt.3 | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c6ba03b64..b0c2745b0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -169,11 +169,16 @@ added in 7.12.3) .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of -its internal equivalent with a frequent interval during data transfer. -Unknown/unused argument values will be set to zero (like if you only download -data, the upload size will remain 0). Returning a non-zero value from this -callback will cause libcurl to abort the transfer and return -\fICURLE_ABORTED_BY_CALLBACK\fP. +its internal equivalent with a frequent interval during data transfer (roughly +once per second). Unknown/unused argument values pass to the callback will be +set to zero (like if you only download data, the upload size will remain +0). Returning a non-zero value from this callback will cause libcurl to abort +the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. + +If you transfer data with the multi interface, this function will not be +called during periods of idleness unless you call the appropriate libcurl +function that performs transfers. Usage of the \fBCURLOPT_PROGRESSFUNCTION\fP +callback is not recommended when using the multi interface. \fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually get called. -- cgit v1.2.1 From 5acf997e69734bb09110fc8a275ce57c8cb6a5f7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 4 Jan 2006 14:09:42 +0000 Subject: upcoming new error code --- docs/libcurl/libcurl-errors.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 64b3454eb..596d0e0b1 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -210,6 +210,9 @@ An easy handle was not good/valid. You are doomed. .IP "CURLM_INTERNAL_ERROR (4)" This can only be returned if libcurl bugs. Please report it to us! +.IP "CURLM_BAD_SOCKET (5)" +The passed-in socket is not a valid one that libcurl already knows about. +(Added in 7.16.0) .SH "CURLSHcode" The "share" interface will return a CURLSHcode to indicate when an error has occurred. Also consider \fIcurl_share_strerror(3)\fP. -- cgit v1.2.1 From 99c0a1a7d06a26c5a07f1157c5423ab4275e698b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 4 Jan 2006 14:09:57 +0000 Subject: removed easy handle argument from proto --- docs/libcurl/curl_multi_socket.3 | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index fb118eb65..6f03cdc68 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -8,7 +8,6 @@ curl_multi_socket \- reads/writes available data CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, - CURL *easy, curl_socket_callback callback, void *userp); @@ -19,11 +18,10 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle, Alternative versions of \fIcurl_multi_perform()\fP that allows the application to pass in one of the file descriptors/sockets that have been detected to have \&"action" on them and let libcurl perform. This allows libcurl to not have to -scan through all possible file descriptors to check for action. The -application is recommended to pass in the \fBeasy\fP argument (or set it to -CURL_EASY_NONE) to make libcurl figure out the internal structure even faster -and easier. If the easy argument is set to something else than -CURL_EASY_NONE, the \fBsockfd\fP argument will be ignored by libcurl. +scan through all possible file descriptors to check for action. When the +application has detected on a socket handled by libcurl, call +\fIcurl_multi_perform()\fP with the \fBsockfd\fP argument set to the socket +with the action. These functions inform the application about updates in the socket (file descriptor) status by doing none, one or multiple calls to the @@ -39,8 +37,7 @@ transfers instead of just a single one, you call An application should call \fBcurl_multi_timeout(3)\fP to figure out how long it should wait for socket actions \- at most \- before doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP -argument set to CURL_SOCKET_TIMEOUT and the \fBeasy\fP argument set to -CURL_EASY_TIMEOUT. +argument set to CURL_SOCKET_TIMEOUT. \fBcurl_multi_perform(3)\fP is the exact equivalent of calling \fBcurl_multi_socket_all\fP(handle, NULL, NULL); -- cgit v1.2.1 From e1e753179a73d3f1cc61005eeca50dbb314c7b6a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 8 Jan 2006 22:55:13 +0000 Subject: use the proper dash --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b0c2745b0..23194999c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -23,7 +23,7 @@ .\" .TH curl_easy_setopt 3 "27 Oct 2005" "libcurl 7.14.2" "libcurl Manual" .SH NAME -curl_easy_setopt - set options for a curl easy handle +curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS #include -- cgit v1.2.1 From bda1e9aeab019d003036a3ec24193605bc191b3a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 9 Jan 2006 13:17:14 +0000 Subject: Made the copyright year match the latest modification's year. --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 23194999c..9db26d7d5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2005, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -- cgit v1.2.1 From 0e79a8944b39804bfb956113dd77d9f5edd0bff8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 15 Jan 2006 23:15:24 +0000 Subject: adjusted to the new concept of the callback --- docs/libcurl/curl_multi_setopt.3 | 42 +++++++++++++++++++++++++++++++ docs/libcurl/curl_multi_socket.3 | 53 +++++++++++++++++++++++----------------- 2 files changed, 72 insertions(+), 23 deletions(-) create mode 100644 docs/libcurl/curl_multi_setopt.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 new file mode 100644 index 000000000..6f88b989b --- /dev/null +++ b/docs/libcurl/curl_multi_setopt.3 @@ -0,0 +1,42 @@ +.\" $Id$ +.\" +.TH curl_multi_setopt 3 "8 Jan 2006" "libcurl 7.16.0" "libcurl Manual" +.SH NAME +curl_multi_setopt \- set options for a curl multi handle +.SH SYNOPSIS +#include + +CURLMcode curl_multi_setopt(CURLM * multi_handle, CURLMoption option, param); +.SH DESCRIPTION +curl_multi_setopt() is used to tell a libcurl multi handle how to behave. By +using the appropriate options to \fIcurl_multi_setopt\fP, you can change +libcurl's behaviour when using that multi handle. All options are set with +the \fIoption\fP followed by the parameter \fIparam\fP. That parameter can be +a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a +\fBcurl_off_t\fP type, depending on what the specific option expects. Read +this manual carefully as bad input values may cause libcurl to behave badly! +You can only set one option in each function call. + +.SH OPTIONS +.IP CURLMOPT_SOCKETFUNCTION +Pass a pointer to a function matching the curl_socket_callback prototype. The +\fIcurl_multi_socket(3)\fP functions inform the application 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 is NULL, no callback will +be called. Set the callback's fourth argument with \fICURLMOPT_SOCKETDATA\fP. +See \fIcurl_multi_socket(3)\fP for more callback details. +.IP CURLMOPT_SOCKETDATA +Pass a pointer to whatever you want passed to the curl_socket_callback's forth +argument, the userp pointer. This is not used by libcurl but only passed-thru +as-is. Set the callback pointer with \fICURLMOPT_SOCKETFUNCTION\fP. +.SH RETURNS +The standard CURLMcode for multi interface error codes. Note that it returns a +CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl +doesn't know of. +.SH AVAILABILITY +This function was added in libcurl 7.16.0 +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " +.BR curl_multi_socket "(3), " curl_multi_info_read "(3)" diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 6f03cdc68..12082ff3f 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -6,29 +6,23 @@ curl_multi_socket \- reads/writes available data .SH SYNOPSIS #include -CURLMcode curl_multi_socket(CURLM * multi_handle, - curl_socket_t sockfd, - curl_socket_callback callback, - void *userp); - -CURLMcode curl_multi_socket_all(CURLM *multi_handle, - curl_socket_callback callback, - void *userp); +CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd); + +CURLMcode curl_multi_socket_all(CURLM *multi_handle); .SH DESCRIPTION Alternative versions of \fIcurl_multi_perform()\fP that allows the application to pass in one of the file descriptors/sockets that have been detected to have \&"action" on them and let libcurl perform. This allows libcurl to not have to scan through all possible file descriptors to check for action. When the -application has detected on a socket handled by libcurl, call +application has detected action on a socket handled by libcurl, it should call \fIcurl_multi_perform()\fP with the \fBsockfd\fP argument set to the socket with the action. These functions inform the application about updates in the socket (file descriptor) status by doing none, one or multiple calls to the -curl_socket_callback given in the \fBcallback\fP argument. They update the -status with changes since the previous time this function was used. If -\fBcallback\fP is NULL, no callback will be called. A status change may also -be a new timeout only, having the same IN/OUT status as before. +curl_socket_callback given with the CURLMOPT_SOCKETFUNCTION option to +\fIcurl_multi_setopt(3)\fP. They update the status with changes since the +previous time this function was called. If you want to force libcurl to (re-)check all its internal sockets and transfers instead of just a single one, you call @@ -39,9 +33,6 @@ it should wait for socket actions \- at most \- before doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. -\fBcurl_multi_perform(3)\fP is the exact equivalent of calling -\fBcurl_multi_socket_all\fP(handle, NULL, NULL); - The socket \fBcallback\fP function uses a prototype like this .nf @@ -70,18 +61,34 @@ deregister CURLMcode type, general libcurl multi interface error code. If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you -should call \fIcurl_multi_perform\fP again, before you select() on more -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". +should call \fIcurl_multi_perform\fP again, before you wait for more actions +on libcurl's sockets. 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". NOTE that this only returns errors etc regarding the whole multi stack. There might still have occurred problems on individual transfers even when this function returns OK. .SH "TYPICAL USAGE" -Call curl_multi_socket_all() first. Setup a "collection" of sockets to -supervise, then when action happens call curl_multi_socket() for the easy -handle that got the action. +1. Create a multi handle + +2. Set the socket callback with CURLMOPT_SOCKETFUNCTION + +3. Add easy handles + +4. Call curl_multi_socket_all() first once + +5. Setup a "collection" of sockets to supervise when your socket +callback is called. + +6. Use curl_multi_timeout() to figure out how long to wait for action + +7. Wait for action on any of libcurl's sockets + +8, When action happens, call curl_multi_socket() for the socket(s) that got +action. + +9. Go back to step 6. .SH AVAILABILITY This function was added in libcurl 7.16.0 .SH "SEE ALSO" -- cgit v1.2.1 From 4c35a40858db71daa0f6be4111c620fb201f245a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 15 Jan 2006 23:55:53 +0000 Subject: Bryan Henderson turned the 'initialized' variable for curl_global_init() into a counter, and thus you can now do multiple curl_global_init() and you are then supposed to do the same amount of calls to curl_global_cleanup(). Bryan also updated the docs accordingly. --- docs/libcurl/curl_easy_init.3 | 15 ++++-- docs/libcurl/curl_global_cleanup.3 | 19 +++++-- docs/libcurl/curl_global_init.3 | 34 +++++++----- docs/libcurl/libcurl.3 | 106 +++++++++++++++++++++++++++++++++++-- 4 files changed, 148 insertions(+), 26 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index a9fbe792a..083633627 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -14,12 +14,17 @@ handle that you must use as input to other easy-functions. curl_easy_init initializes curl and this call \fBMUST\fP have a corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is complete. -If you did not already call \fIcurl_global_init(3)\fP, it will be done -automatically with a default setup when you call \fIcurl_easy_init(3)\fP. +If you did not already call \fIcurl_global_init(3)\fP, +\fIcurl_easy_init(3)\fP does it automatically. This may be lethal in multi-threaded cases, since \fIcurl_global_init(3)\fP is -not thread-safe and must not be called more than once (or from more than one -thread). You are strongly adviced to not rely on this automatic behaviour, but -call \fIcurl_global_init(3)\fP yourself properly. +not thread-safe, and it may result in resource problems because there is +no corresponding cleanup. + +You are strongly advised to not allow this automatic behaviour, by +calling \fIcurl_global_init(3)\fP yourself properly. +See the description in \fBlibcurl\fP(3) of global environment +requirements for details of how to use this function. + .SH RETURN VALUE If this function returns NULL, something went wrong and you cannot use the other curl functions. diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3 index 566b110e0..3c7724d34 100644 --- a/docs/libcurl/curl_global_cleanup.3 +++ b/docs/libcurl/curl_global_cleanup.3 @@ -11,13 +11,22 @@ curl_global_cleanup - global libcurl cleanup .BI "void curl_global_cleanup(void);" .ad .SH DESCRIPTION -curl_global_cleanup must be called once (no matter how many threads or libcurl -sessions that'll be used) by every application that uses libcurl, after all -uses of libcurl is complete. +This function releases resources acquired by \fBcurl_global_init\fP. -This is the opposite of \fIcurl_global_init(3)\fP. +You should call \fIcurl_global_cleanup()\fP once for each call you make +to \fIcurl_global_init\fP, after you are done using libcurl. + +\fBThis function is not thread safe.\fP You must not call it when any +other thread in the program (i.e. a thread sharing the same memory) is +running. This doesn't just mean no other thread that is using +libcurl. Because \fBcurl_global_cleanup()\fP calls functions of other +libraries that are similarly thread unsafe, it could conflict with any +other thread that uses these other libraries. + +See the description in \fBlibcurl\fP(3) of global environment +requirements for details of how to use this function. -Not calling this function may result in memory leaks. .SH "SEE ALSO" .BR curl_global_init "(3), " +.BR libcurl "(3), " diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index 8e8ec09f4..0729ef787 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -11,22 +11,31 @@ curl_global_init - Global libcurl initialisation .BI "CURLcode curl_global_init(long " flags ");" .ad .SH DESCRIPTION -This function should only be called once (no matter how many threads or -libcurl sessions that'll be used) by every application that uses libcurl. +This function sets up the program environment that libcurl needs. Think +of it as an extension of the library loader. -If this function hasn't been invoked when \fIcurl_easy_init(3)\fP is called, -it will be done automatically by libcurl. It is adviced that you do not rely -on this automatic call, but instead call \fIcurl_global_init(3)\fP properly. +This function must be called at least once within a program (a program is +all the code that shares a memory space) before the program calls any other +function in libcurl. The environment it sets up is constant for the life +of the program and is the same for every program, so multiple calls have +the same effect as one call. -The flags option is a bit pattern that tells libcurl exact what features to +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 libcurl. -You must however \fBalways\fP use the \fIcurl_global_cleanup(3)\fP function, -as that cannot be called automatically for you by libcurl. +\fBThis function is not thread safe.\fP You must not call it when any +other thread in the program (i.e. a thread sharing the same memory) is +running. This doesn't just mean no other thread that is using +libcurl. Because \fIcurl_global_init()\fP calls functions of other +libraries that are similarly thread unsafe, it could conflict with any +other thread that uses these other libraries. + +See the description in \fBlibcurl\fP(3) of global environment +requirements for details of how to use this function. -Calling this function more than once will cause unpredictable results. If that -is not enough, calling this function from more than one thread may also cause -unpredictable results. .SH FLAGS .TP 5 .B CURL_GLOBAL_ALL @@ -46,4 +55,5 @@ other curl functions. .SH "SEE ALSO" .BR curl_global_init_mem "(3), " .BR curl_global_cleanup "(3), " -.BR curl_easy_init "(3) " \ No newline at end of file +.BR curl_easy_init "(3) " +.BR libcurl "(3) " diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index c9eee4e30..6d18e1fd1 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -13,10 +13,11 @@ in-depth understanding on how to program with libcurl. There are more than a twenty custom bindings available that bring libcurl access to your favourite language. Look elsewhere for documentation on those. -All applications that use libcurl should call \fIcurl_global_init(3)\fP -exactly once before any libcurl function can be used. After all usage of -libcurl is complete, it \fBmust\fP call \fIcurl_global_cleanup(3)\fP. In -between those two calls, you can use libcurl as described below. +libcurl has a global constant environment that you must set up and +maintain while using libcurl. This essentially means you call +\fIcurl_global_init(3)\fP at the start of your program and +\fIcurl_global_cleanup(3)\fP at the end. See GLOBAL CONSTANTS below +for details. To transfer files, you always set up an "easy handle" using \fIcurl_easy_init(3)\fP, but when you want the file(s) transferred you have @@ -86,6 +87,10 @@ Never ever call curl-functions simultaneously using the same handle from several threads. libcurl is thread-safe and can be used in any number of threads, but you must use separate curl handles if you want to use libcurl in more than one thread simultaneously. + +The global environment functions are not thread-safe. See GLOBAL CONSTANTS +below for details. + .SH "PERSISTENT CONNECTIONS" Persistent connections means that libcurl can re-use the same connection for several transfers, if the conditions are right. @@ -103,3 +108,96 @@ libcurl will be closed and forgotten. Note that the options set with \fIcurl_easy_setopt(3)\fP will be used in on every repeated \fIcurl_easy_perform(3)\fP call. + +.SH "GLOBAL CONSTANTS" +There are a variety of constants that libcurl uses, mainly through its +internal use of other libraries, which are too complicated for the +library loader to set up. Therefore, a program must call a library +function after the program is loaded and running to finish setting up +the library code. For example, when libcurl is built for SSL +capability via the GNU TLS library, there is an elaborate tree inside +that library that describes the SSL protocol. + +\fIcurl_global_init()\fP is the function that you must call. This may +allocate resources (e.g. the memory for the GNU TLS tree mentioned +above), so the companion function \fIcurl_global_cleanup()\fP releases +them. + +The basic rule for constructing a program that uses libcurl is this: +Call \fIcurl_global_init()\fP, with a \fICURL_GLOBAL_ALL\fP argument, +immediately after the program starts, while it is still only one +thread and before it uses libcurl at all. Call +\fIcurl_global_cleanup()\fP immediately before the program exits, when +the program is again only one thread and after its last use of +libcurl. + +You can call both of these multiple times, as long as all calls meet +these requirements and the number of calls to each is the same. + +It isn't actually required that the functions be called at the beginning +and end of the program -- that's just usually the easiest way to do it. +It \fIis\fP required that the functions be called when no other thread +in the program is running. + +These global constant functions are \fInot thread safe\fP, so you must +not call them when any other thread in the program is running. It +isn't good enough that no other thread is using libcurl at the time, +because these functions internally call similar functions of other +libraries, and those functions are similarly thread-unsafe. You can't +generally know what these libraries are, or whether other threads are +using them. + +The global constant situation merits special consideration when the +code you are writing to use libcurl is not the main program, but rather +a modular piece of a program, e.g. another library. As a module, +your code doesn't know about other parts of the program -- it doesn't +know whether they use libcurl or not. And its code doesn't necessarily +run at the start and end of the whole program. + +A module like this must have global constant functions of its own, +just like \fIcurl_global_init()\fP and \fIcurl_global_cleanup()\fP. +The module thus has control at the beginning and end of the program +and has a place to call the libcurl functions. Note that if multiple +modules in the program use libcurl, they all will separately call the +libcurl functions, and that's OK because only the first +\fIcurl_global_init()\fP and the last \fIcurl_global_cleanup()\fP in a +program changes anything. (libcurl uses a reference count in static +memory). + +In a C++ module, it is common to deal with the global constant +situation by defining a special class that represents the global +constant environment of the module. A program always has exactly one +object of the class, in static storage. That way, the program +automatically calls the constructor of the object as the program +starts up and the destructor as it terminates. As the author of this +libcurl-using module, you can make the constructor call +\fIcurl_global_init()\fP and the destructor call +\fIcurl_global_cleanup()\fP and satisfy libcurl's requirements without +your user having to think about it. + +\fIcurl_global_init()\fP has an argument that tells what particular +parts of the global constant environment to set up. In order to +successfully use any value except \fICURL_GLOBAL_ALL\fP (which says to +set up the whole thing), you must have specific knowledge of internal +workings of libcurl and all other parts of the program of which it is +part. + +A special part of the global constant environment is the identity of +the memory allocator. \fIcurl_global_init()\fP selects the system +default memory allocator, but you can use \fIcurl_global_init_mem()\fP +to supply one of your own. However, there is no way to use +\fIcurl_global_init_mem()\fP in a modular program -- all modules in +the program that might use libcurl would have to agree on one +allocator. + +There is a failsafe in libcurl that makes it usable in simple +situations without you having to worry about the global constant +environment at all: \fIcurl_easy_init()\fP sets up the environment +itself if it hasn't been done yet. The resources it acquires to do so +get released by the operating system automatically when the program +exits. + +This failsafe feature exists mainly for backward compatibility because +there was a time when the global functions didn't exist. Because it +is sufficient only in the simplest of programs, it is not recommended +for any program to rely on it. -- cgit v1.2.1 From 67a83c1b3465c44b249eaa44fdc492952e59b31f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 16 Jan 2006 22:14:37 +0000 Subject: David Shaw finally removed all traces of Gopher and we are now officially not supporting it. It hasn't been functioning for years anyway, so this is just finally stating what already was true. And a cleanup at the same time. --- docs/libcurl/libcurl.m4 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 882770924..c6fba644e 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -46,7 +46,6 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], AH_TEMPLATE([LIBCURL_PROTOCOL_HTTPS],[Defined if libcurl supports HTTPS]) AH_TEMPLATE([LIBCURL_PROTOCOL_FTP],[Defined if libcurl supports FTP]) AH_TEMPLATE([LIBCURL_PROTOCOL_FTPS],[Defined if libcurl supports FTPS]) - AH_TEMPLATE([LIBCURL_PROTOCOL_GOPHER],[Defined if libcurl supports GOPHER]) AH_TEMPLATE([LIBCURL_PROTOCOL_FILE],[Defined if libcurl supports FILE]) AH_TEMPLATE([LIBCURL_PROTOCOL_TELNET],[Defined if libcurl supports TELNET]) AH_TEMPLATE([LIBCURL_PROTOCOL_LDAP],[Defined if libcurl supports LDAP]) @@ -188,7 +187,7 @@ x=CURLOPT_VERBOSE; # We don't have --protocols, so just assume that all # protocols are available - _libcurl_protocols="HTTP FTP GOPHER FILE TELNET LDAP DICT" + _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT" if test x$libcurl_feature_SSL = xyes ; then _libcurl_protocols="$_libcurl_protocols HTTPS" -- cgit v1.2.1 From 8971f656b4bb1a178b59aa730da67a8e5aeabaee Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 17 Jan 2006 17:39:39 +0000 Subject: David Shaw: Here is the latest libcurl.m4 autoconf tests. It is updated with the latest features and protocols that libcurl supports and has a minor fix to better deal with the obscure case where someone has more than one libcurl installed at the same time. --- docs/libcurl/libcurl.m4 | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index c6fba644e..798427c14 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -1,7 +1,7 @@ # LIBCURL_CHECK_CONFIG ([DEFAULT-ACTION], [MINIMUM-VERSION], # [ACTION-IF-YES], [ACTION-IF-NO]) # ---------------------------------------------------------- -# David Shaw Jun-21-2005 +# David Shaw Jan-17-2006 # # Checks for libcurl. DEFAULT-ACTION is the string yes or no to # specify whether to default to --with-libcurl or --without-libcurl. @@ -13,10 +13,10 @@ # ACTION-IF-NO is a list of shell commands that are run otherwise. # Note that using --without-libcurl does run ACTION-IF-NO. # -# This macro defines HAVE_LIBCURL if a working libcurl setup is found, -# and sets @LIBCURL@ and @LIBCURL_CPPFLAGS@ to the necessary values. -# Other useful defines are LIBCURL_FEATURE_xxx where xxx are the -# various features supported by libcurl, and LIBCURL_PROTOCOL_yyy +# This macro #defines HAVE_LIBCURL if a working libcurl setup is +# found, and sets @LIBCURL@ and @LIBCURL_CPPFLAGS@ to the necessary +# values. Other useful defines are LIBCURL_FEATURE_xxx where xxx are +# the various features supported by libcurl, and LIBCURL_PROTOCOL_yyy # where yyy are the various protocols supported by libcurl. Both xxx # and yyy are capitalized. See the list of AH_TEMPLATEs at the top of # the macro for the complete list of possible defines. Shell @@ -32,7 +32,8 @@ # found is after version 7.7.2, the first version that included the # curl-config script. Note that it is very important for people # packaging binary versions of libcurl to include this script! -# Without curl-config, we can only guess what protocols are available. +# Without curl-config, we can only guess what protocols are available, +# or use curl_version_info to figure it out at runtime. AC_DEFUN([LIBCURL_CHECK_CONFIG], [ @@ -41,6 +42,9 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], AH_TEMPLATE([LIBCURL_FEATURE_IPV6],[Defined if libcurl supports IPv6]) AH_TEMPLATE([LIBCURL_FEATURE_LIBZ],[Defined if libcurl supports libz]) AH_TEMPLATE([LIBCURL_FEATURE_ASYNCHDNS],[Defined if libcurl supports AsynchDNS]) + AH_TEMPLATE([LIBCURL_FEATURE_IDN],[Defined if libcurl supports IDN]) + AH_TEMPLATE([LIBCURL_FEATURE_SSPI],[Defined if libcurl supports SSPI]) + AH_TEMPLATE([LIBCURL_FEATURE_NTLM],[Defined if libcurl supports NTLM]) AH_TEMPLATE([LIBCURL_PROTOCOL_HTTP],[Defined if libcurl supports HTTP]) AH_TEMPLATE([LIBCURL_PROTOCOL_HTTPS],[Defined if libcurl supports HTTPS]) @@ -50,6 +54,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], AH_TEMPLATE([LIBCURL_PROTOCOL_TELNET],[Defined if libcurl supports TELNET]) AH_TEMPLATE([LIBCURL_PROTOCOL_LDAP],[Defined if libcurl supports LDAP]) AH_TEMPLATE([LIBCURL_PROTOCOL_DICT],[Defined if libcurl supports DICT]) + AH_TEMPLATE([LIBCURL_PROTOCOL_TFTP],[Defined if libcurl supports TFTP]) AC_ARG_WITH(libcurl, AC_HELP_STRING([--with-libcurl=DIR],[look for the curl library in DIR]), @@ -64,12 +69,13 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], _libcurl_try_link=yes if test -d "$_libcurl_with" ; then - CPPFLAGS="${CPPFLAGS} -I$withval/include" - LDFLAGS="${LDFLAGS} -L$withval/lib" + LIBCURL_CPPFLAGS="-I$withval/include" + _libcurl_ldflags="-L$withval/lib" + AC_PATH_PROG([_libcurl_config],["$withval/bin/curl-config"]) + else + AC_PATH_PROG([_libcurl_config],[curl-config]) fi - AC_PATH_PROG([_libcurl_config],[curl-config]) - if test x$_libcurl_config != "x" ; then AC_CACHE_CHECK([for the version of libcurl], [libcurl_cv_lib_curl_version], @@ -125,15 +131,15 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], # we didn't find curl-config, so let's see if the user-supplied # link line (or failing that, "-lcurl") is enough. - LIBCURL=${LIBCURL-"-lcurl"} + LIBCURL=${LIBCURL-"$_libcurl_ldflags -lcurl"} AC_CACHE_CHECK([whether libcurl is usable], [libcurl_cv_lib_curl_usable], [ _libcurl_save_cppflags=$CPPFLAGS - CPPFLAGS="$CPPFLAGS $LIBCURL_CPPFLAGS" + CPPFLAGS="$LIBCURL_CPPFLAGS $CPPFLAGS" _libcurl_save_libs=$LIBS - LIBS="$LIBS $LIBCURL" + LIBS="$LIBCURL $LIBS" AC_LINK_IFELSE(AC_LANG_PROGRAM([#include ],[ /* Try and use a few common options to force a failure if we are @@ -215,6 +221,7 @@ x=CURLOPT_VERBOSE; unset _libcurl_protocol unset _libcurl_protocols unset _libcurl_version + unset _libcurl_ldflags fi if test x$_libcurl_with = xno || test x$libcurl_cv_lib_curl_usable != xyes ; then -- cgit v1.2.1 From b55b780d7beab89bd51d376b4281be1e413b34c0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 27 Jan 2006 15:01:10 +0000 Subject: Cyrill Osterwalder pointed out that sending "" as data in a header is in fact equal to a blank one according to the spec. --- docs/libcurl/curl_easy_setopt.3 | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9db26d7d5..60068f661 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -620,15 +620,17 @@ 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 internally used header will get disabled. Thus, using this option you can add -new headers, replace internal headers and remove internal headers. 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 you specified. - -The first line in a request (usually containing a GET or POST) is not a header -and cannot be replaced using this option. Only the lines following the -request-line are headers. +new headers, replace internal headers and remove internal headers. To add a +header with no contents, make the contents 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 +you specified. + +The first line in a request (containing the method, usually a GET or POST) is +not a header and cannot be replaced using this option. Only the lines +following the request-line are headers. Adding this method line in this list +of headers will only cause your request to send an invalid header. Pass a NULL to this to reset back to no custom headers. -- cgit v1.2.1 From 2aed209efa6f9fe5b43a529c80273f2a3c247e12 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 27 Jan 2006 21:23:04 +0000 Subject: typo pointed out by Mike Griffiths --- docs/libcurl/libcurl-errors.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 596d0e0b1..03c243bf7 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -38,9 +38,9 @@ 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 back. -This error code implies that it god a strange or bad reply. The given remote -server is probably not an OK FTP server. +After connecting to an 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_FTP_ACCESS_DENIED (9)" We were denied access when trying to login to an FTP server or when trying to change working directory to the one given in the URL. -- cgit v1.2.1 From 2fbf94b0f309de9bd9153274bb475abc744afb0a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 30 Jan 2006 08:24:07 +0000 Subject: Added CURLOPT_LOCALPORT and CURLOPT_LOCALPORTRANGE to libcurl. Set with the curl tool with --local-port. Plain and simply set the range of ports to bind the local end of connections to. Implemented on to popular demand. Not extensively tested. Please let me know how it works. --- docs/libcurl/curl_easy_setopt.3 | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 60068f661..25e7e7707 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "27 Oct 2005" "libcurl 7.14.2" "libcurl Manual" +.TH curl_easy_setopt 3 "28 Jan 2006" "libcurl 7.15.2" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -335,6 +335,19 @@ don't want this tunneling option. 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 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) +.IP CURLOPT_LOCALPORTRANGE +Pass a long. This is the number of attempts libcurl should do 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 value to 1 or below +will make libcurl do only one try for exact port number. Note that port +numbers by nature is a scarce resource that will be busy at times so setting +this value to something too low might cause unnecessary connection setup +failures. (Added in 7.15.2) .IP CURLOPT_DNS_CACHE_TIMEOUT Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero (0) to completely disable -- cgit v1.2.1 From 7725729d908527cdf1eb94dbafad1315f52937aa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 7 Feb 2006 14:03:17 +0000 Subject: Rene Bernhardt found this typo --- docs/libcurl/libcurl-tutorial.3 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 0a0a5f095..0045cfe26 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -887,12 +887,12 @@ data size is unknown. There's only one aspect left in the HTTP requests that we haven't yet mentioned how to modify: the version field. 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 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: +version number to tell the server which version we support. libcurl speak 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: - curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURLHTTP_VERSION_1_0); + curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0); .IP "FTP Custom Commands" -- cgit v1.2.1 From 3b19c7d0d9933b9e75577b0f2e6e58d26f28f1bf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 9 Feb 2006 22:25:41 +0000 Subject: CURLOPT_NOSIGNAL might be a MUST to make threaded use work, like on AIX 5.2 due to the use of the static variable for sigsetjmp() --- docs/libcurl/libcurl-tutorial.3 | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 0045cfe26..63b834148 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2005, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -267,11 +267,13 @@ GnuTLS http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html -When using multiple threads you should set the CURLOPT_NOSIGNAL option to -TRUE for all handles. Everything will work fine except that timeouts are not -honored during the DNS lookup - which you can work around by building libcurl -with c-ares support. c-ares is a library that provides asynchronous name -resolves. Unfortunately, c-ares does not yet support IPv6. +When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE +for all handles. Everything will or might work fine except that timeouts are +not honored during the DNS lookup - which you can work around by building +libcurl with c-ares support. c-ares is a library that provides asynchronous +name resolves. Unfortunately, c-ares does not yet fully support IPv6. On some +platforms, libcurl simply will not function properly multi-threaded unless +this option is set. Also, note that CURLOPT_DNS_USE_GLOBAL_CACHE is not thread-safe. -- cgit v1.2.1 From 87bcb6f3775a437579c7526d0972c714c2e5d31d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 11 Feb 2006 22:35:16 +0000 Subject: Karl M added the CURLOPT_CONNECT_ONLY and CURLINFO_LASTSOCKET options that an app can use to let libcurl only connect to a remote host and then extract the socket from libcurl. libcurl will then not attempt to do any transfer at all after the connect is done. --- docs/libcurl/curl_easy_getinfo.3 | 6 ++++++ docs/libcurl/curl_easy_setopt.3 | 8 ++++++++ 2 files changed, 14 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index bc4f2063b..2119ea211 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -141,6 +141,12 @@ cookies cURL knows (expired ones, too). Don't forget to cookies (cookies for the handle have not been enabled or simply none have been received) 'struct curl_slist *' will be set to point to NULL. (Added in 7.14.1) +.IP CURLINFO_LASTSOCKET +Pass a pointer to a long to receive the last socket used by this curl +session. If the socket is no longer valid, -1 is returned. When you finish +working with the socket, you must call curl_easy_cleanup() as usual and let +libcurl close the socket and cleanup other resources associated with the +handle. (Added in 7.15.2) .SH TIMES .NF An overview of the six time values available from curl_easy_getinfo() diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 25e7e7707..8a152947c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1044,6 +1044,14 @@ Resolve to ipv4 addresses. .IP CURL_IPRESOLVE_V6 Resolve to ipv6 addresses. .RE +.SH CURLOPT_CONNECT_ONLY +Pass a long. A non-zero parameter tells the library to perform any required +proxy authentication and connection setup, but no data transfer. + +This option is useful with the \fICURLINFO_LASTSOCKET\fP option to +\fIcurl_easy_getinfo(3)\fP. The library can set up the connection and then the +application can obtain the most recently used socket for special data +transfers. (Added in 7.15.2) .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be -- cgit v1.2.1 From dcee24191fc8818425d5091471907a0cf95dbc86 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 11 Feb 2006 22:36:29 +0000 Subject: mention the CURLOPT_CONNECT_ONLY connection --- docs/libcurl/curl_easy_getinfo.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 2119ea211..1713eff4f 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -146,7 +146,8 @@ Pass a pointer to a long to receive the last socket used by this curl session. If the socket is no longer valid, -1 is returned. When you finish working with the socket, you must call curl_easy_cleanup() as usual and let libcurl close the socket and cleanup other resources associated with the -handle. (Added in 7.15.2) +handle. This is typically used in combination with \fICURLOPT_CONNECT_ONLY\fP. +(Added in 7.15.2) .SH TIMES .NF An overview of the six time values available from curl_easy_getinfo() -- cgit v1.2.1 From 98180b5cc7981fe7ec93abfeb90513d6165f561f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 17 Feb 2006 13:31:49 +0000 Subject: fixed formatting --- docs/libcurl/curl_global_cleanup.3 | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3 index 3c7724d34..4cb13a7da 100644 --- a/docs/libcurl/curl_global_cleanup.3 +++ b/docs/libcurl/curl_global_cleanup.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_global_cleanup 3 "28 May 2001" "libcurl 7.8" "libcurl Manual" +.TH curl_global_cleanup 3 "17 Feb 2006" "libcurl 7.8" "libcurl Manual" .SH NAME curl_global_cleanup - global libcurl cleanup .SH SYNOPSIS @@ -11,20 +11,20 @@ curl_global_cleanup - global libcurl cleanup .BI "void curl_global_cleanup(void);" .ad .SH DESCRIPTION -This function releases resources acquired by \fBcurl_global_init\fP. +This function releases resources acquired by \fBcurl_global_init(3)\fP. -You should call \fIcurl_global_cleanup()\fP once for each call you make -to \fIcurl_global_init\fP, after you are done using libcurl. +You should call \fIcurl_global_cleanup(3)\fP once for each call you make to +\fIcurl_global_init(3)\fP, after you are done using libcurl. -\fBThis function is not thread safe.\fP You must not call it when any -other thread in the program (i.e. a thread sharing the same memory) is -running. This doesn't just mean no other thread that is using -libcurl. Because \fBcurl_global_cleanup()\fP calls functions of other -libraries that are similarly thread unsafe, it could conflict with any -other thread that uses these other libraries. +\fBThis function is not thread safe.\fP You must not call it when any other +thread in the program (i.e. a thread sharing the same memory) is running. +This doesn't just mean no other thread that is using libcurl. Because +\fBcurl_global_cleanup(3)\fP calls functions of other libraries that are +similarly thread unsafe, it could conflict with any other thread that uses +these other libraries. -See the description in \fBlibcurl\fP(3) of global environment -requirements for details of how to use this function. +See the description in \fBlibcurl(3)\fP of global environment requirements for +details of how to use this function. .SH "SEE ALSO" .BR curl_global_init "(3), " -- cgit v1.2.1 From a15d107dde68f6173cfb1a590320cb108d4dd0f5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 21 Feb 2006 07:46:41 +0000 Subject: Peter Su added support for SOCKS4 proxies. Enable this by setting the proxy type to the already provided type CURLPROXY_SOCKS4. I added a --socks4 option that works like the current --socks5 option but instead use the socks4 protocol. --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8a152947c..5db673eb2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "28 Jan 2006" "libcurl 7.15.2" "libcurl Manual" +.TH curl_easy_setopt 3 "21 Feb 2006" "libcurl 7.15.2" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -324,8 +324,8 @@ Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. .IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for -this are \fICURLPROXY_HTTP\fP and \fICURLPROXY_SOCKS5\fP, with the HTTP one -being default. (Added in 7.10) +this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2) +\fICURLPROXY_SOCKS5\fP. The HTTP type is default. (Added in 7.10) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy -- cgit v1.2.1 From aa50a00898495b2f3a4334ecbe4d81efa6dd6b6b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 2 Mar 2006 22:09:30 +0000 Subject: point out that CAINFO points out a file name by default --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5db673eb2..d2d809741 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1142,6 +1142,9 @@ certificates to verify the peer with. This makes sense only when used in combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If \fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAINFO\fP need not 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. .IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate -- cgit v1.2.1 From 3f22901a43448af4ab2c1c690c1c6f391bca2abc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 13 Mar 2006 19:44:36 +0000 Subject: Scott Worley's typo fixes --- docs/libcurl/curl_easy_getinfo.3 | 2 +- docs/libcurl/libcurl-tutorial.3 | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 1713eff4f..d16f6c6e9 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -152,7 +152,7 @@ handle. This is typically used in combination with \fICURLOPT_CONNECT_ONLY\fP. .NF An overview of the six time values available from curl_easy_getinfo() -curk_easy_perform() +curl_easy_perform() | |--NT |--|--CT diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 63b834148..f23d52968 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -133,10 +133,11 @@ Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP should be avoided. They should only be called once each. .SH "Features libcurl Provides" -It is considered best-practice to determine libcurl features run-time rather -than build-time (if possible of course). By calling curl_version_info() and -checking tout he details of the returned struct, your program can figure out -exactly what the currently running libcurl supports. +It is considered best-practice to determine libcurl features at run-time +rather than at build-time (if possible of course). By calling +\fIcurl_version_info(3)\fP and checking out the details of the returned +struct, your program can figure out exactly what the currently running libcurl +supports. .SH "Handle the Easy libcurl" libcurl first introduced the so called easy interface. All operations in the -- cgit v1.2.1 From bac52f3969738c81c90a8cb09805d38509ca3297 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 14 Mar 2006 00:05:15 +0000 Subject: --ftp-method and CURLOPT_FTP_FILEMETHOD are now documented and usable --- docs/libcurl/curl_easy_setopt.3 | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d2d809741..14eee0cff 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -858,6 +858,23 @@ Exactly like \fICURLOPT_POSTQUOTE\fP, but for the source host. Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in 7.13.0) +.IP CURLOPT_FTP_FILEMETHOD +Pass a long that should have one of the following values. This option controls +what method libcurl should use to reach a file on a FTP(S) server. The +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 +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 +full path to the server for all these commands. This is the fastest behavior. +.IP CURLFTPMETHOD_SINGLECWD +libcurl does one CWD with the full target directory and then operates on the +file \&"normally" (like in the multicwd case). This is somewhat more standards +compliant than 'nocwd' but without the full penalty of 'multicwd'. +.RE .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A non-zero parameter tells the library to use ASCII mode for ftp transfers, -- cgit v1.2.1 From 38295e8a75c5189fbb382c0bcb5720e47778e61a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 17 Mar 2006 08:22:50 +0000 Subject: slight rewording based on debian bug report #357388 by Justin Pryzby --- docs/libcurl/curl_getenv.3 | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index fab2e5e73..37a5979a7 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -18,10 +18,9 @@ will instead be made "available" by source code access only, and then as curlx_getenv(). .SH RETURN VALUE If successful, curl_getenv() returns a pointer to the value of the specified -environment. The memory it refers to is malloc()ed why the application must -free() this when the data has completed to serve its purpose. When -.I curl_getenv(3) -fails to find the specified name, it returns a null pointer. +environment. The memory it refers to is malloc()ed so the application must +free() this when the data is no longer needed. When \fIcurl_getenv(3)\fP fails +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 -- cgit v1.2.1 From 598ffeea891c4cdd644b48477d54ae714cce0291 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 21 Mar 2006 22:30:03 +0000 Subject: David McCreedy added CURLINFO_FTP_ENTRY_PATH to export the FTP entry path --- docs/libcurl/curl_easy_getinfo.3 | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index d16f6c6e9..f1d74b698 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -1,8 +1,27 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** .\" -.TH curl_easy_getinfo 3 "6 Oct 2005" "libcurl 7.12.3" "libcurl Manual" +.TH curl_easy_getinfo 3 "21 Mar 2006" "libcurl 7.15.4" "libcurl Manual" .SH NAME curl_easy_getinfo - extract information from a curl handle .SH SYNOPSIS @@ -148,6 +167,11 @@ working with the socket, you must call curl_easy_cleanup() as usual and let libcurl close the socket and cleanup other resources associated with the handle. This is typically used in combination with \fICURLOPT_CONNECT_ONLY\fP. (Added in 7.15.2) +.IP CURLINFO_FTP_ENTRY_PATH +Pass a pointer to a 'char *' to receive a pointer to a string holding the path +of the entry path. That is the initial path libcurl ended up in when logging +on to the remote FTP server. This stores a NULL as pointer if something is +wrong. (Added in 7.15.4) .SH TIMES .NF An overview of the six time values available from curl_easy_getinfo() -- cgit v1.2.1 From 5a4b43848ac21b3d831f00ce11136e20f820f0a0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 7 Apr 2006 21:50:47 +0000 Subject: First commit of David McCreedy's EBCDIC and TPF changes. --- docs/libcurl/Makefile.am | 7 +++--- docs/libcurl/curl_easy_escape.3 | 47 ++++++++++++++++++++++++++++++++++++++ docs/libcurl/curl_easy_unescape.3 | 48 +++++++++++++++++++++++++++++++++++++++ docs/libcurl/curl_escape.3 | 5 ++++ docs/libcurl/curl_unescape.3 | 7 +++++- 5 files changed, 110 insertions(+), 4 deletions(-) create mode 100644 docs/libcurl/curl_easy_escape.3 create mode 100644 docs/libcurl/curl_easy_unescape.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index caea9b9aa..77d2f87d3 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -16,7 +16,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_share_init.3 curl_share_setopt.3 libcurl.3 libcurl-easy.3 \ libcurl-multi.3 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3 \ curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ - libcurl-tutorial.3 curl_easy_reset.3 + libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 curl_easy_unescape.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -32,7 +32,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ curl_share_strerror.html curl_global_init_mem.html \ - libcurl-tutorial.html curl_easy_reset.html + libcurl-tutorial.html curl_easy_reset.html curl_easy_escape.html \ + curl_easy_unescape.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ @@ -48,7 +49,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ - curl_easy_reset.pdf + curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3 new file mode 100644 index 000000000..73c09b4f1 --- /dev/null +++ b/docs/libcurl/curl_easy_escape.3 @@ -0,0 +1,47 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** +.\" +.TH curl_easy_escape 3 "7 April 2006" "libcurl 7.15.4" "libcurl Manual" +.SH NAME +curl_easy_escape - URL encodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_easy_escape( CURL *" curl ", char *" url ", int "length " );" +.ad +.SH DESCRIPTION +This function converts the given input string to an URL encoded string and +returns that as a new allocated string. All input characters that are not a-z, +A-Z or 0-9 are converted to their "URL escaped" version (%NN where NN is a +two-digit hexadecimal number). + +If the \fBlength\fP argument is set to 0 (zero), curl_easy_escape() uses +strlen() on the input \fBurl\fP to find out the size. + +You must \fIcurl_free(3)\fP the returned string when you're done with it. +.SH AVAILABILITY +Added in 7.15.4 and replaces the old curl_escape() function. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.BR curl_easy_unescape "(3), " curl_free "(3), " RFC 2396 diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3 new file mode 100644 index 000000000..6b0e6b5fa --- /dev/null +++ b/docs/libcurl/curl_easy_unescape.3 @@ -0,0 +1,48 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** +.\" +.TH curl_easy_unescape 3 "7 April 2006" "libcurl 7.15.4" "libcurl Manual" +.SH NAME +curl_easy_unescape - URL decodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_easy_unescape( CURL *" curl ", char *" url ", int "inlength +.BI ", int *" outlength " );" +.ad +.SH DESCRIPTION +This function converts the given URL encoded input string to a "plain string" +and returns that in an allocated memory area. All input characters that are +URL encoded (%XX where XX is a two-digit hexadecimal number) are converted to +their binary versions. + +If the \fBlength\fP argument is set to 0 (zero), curl_easy_unescape() will use +strlen() on the input \fIurl\fP string to find out the size. + +You must \fIcurl_free(3)\fP the returned string when you're done with it. +.SH AVAILABILITY +Added in 7.15.4 and replaces the old curl_unescape() function. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.I curl_easy_escape(3), curl_free(3), RFC 2396 diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 66eba1477..2007d69ef 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -11,6 +11,8 @@ curl_escape - URL encodes the given string .BI "char *curl_escape( char *" url ", int "length " );" .ad .SH DESCRIPTION +Obsolete function. Use \fIcurl_easy_escape(3)\fP instead! + This function will convert the given input string to an URL encoded string and return that as a new allocated string. All input characters that are not a-z, A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a @@ -20,6 +22,9 @@ If the 'length' argument is set to 0, curl_escape() will use strlen() on the input 'url' string to find out the size. You must curl_free() the returned string when you're done with it. +.SH AVAILABILITY +Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function will +be removed in a future release. .SH RETURN VALUE A pointer to a zero terminated string or NULL if it failed. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index 1d2b059fc..d4c5797b0 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -11,6 +11,8 @@ curl_unescape - URL decodes the given string .BI "char *curl_unescape( char *" url ", int "length " );" .ad .SH DESCRIPTION +Obsolete function. Use \fIcurl_easy_unescape(3)\fP instead! + This function will convert the given URL encoded input string to a "plain string" and return that as a new allocated string. All input characters that are URL encoded (%XX where XX is a two-digit hexadecimal number) will be @@ -20,7 +22,10 @@ If the 'length' argument is set to 0, curl_unescape() will use strlen() on the input 'url' string to find out the size. You must curl_free() the returned string when you're done with it. +.SH AVAILABILITY +Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function will +be removed in a future release. .SH RETURN VALUE A pointer to a zero terminated string or NULL if it failed. .SH "SEE ALSO" -.I curl_escape(3), curl_free(3), RFC 2396 +.I curl_easy_escape(3), curl_easy_unescape(3), curl_free(3), RFC 2396 -- cgit v1.2.1 From 09e569f83d440a6901ee9a4ae1cce39b48d8a545 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 8 Apr 2006 21:29:01 +0000 Subject: mention the outlength argument --- docs/libcurl/curl_easy_unescape.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3 index 6b0e6b5fa..8870daeab 100644 --- a/docs/libcurl/curl_easy_unescape.3 +++ b/docs/libcurl/curl_easy_unescape.3 @@ -39,6 +39,10 @@ their binary versions. If the \fBlength\fP argument is set to 0 (zero), curl_easy_unescape() will use strlen() on the input \fIurl\fP string to find out the size. +If \fBoutlength\fP is non-NULL, the function will write the length of the +returned string in the integer it points to. This allows an escaped string +containing %00 to still get used properly after unescaping. + You must \fIcurl_free(3)\fP the returned string when you're done with it. .SH AVAILABILITY Added in 7.15.4 and replaces the old curl_unescape() function. -- cgit v1.2.1 From 260b88c197645a3d2548c2938ff8097bdd69fb88 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 9 Apr 2006 22:40:49 +0000 Subject: mention RFC 2396 for URL syntax spec --- docs/libcurl/curl_easy_setopt.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 14eee0cff..18718efb0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -295,7 +295,10 @@ given protocol of the set URL is not supported, libcurl will return on error \fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed info on which protocols that are supported. -\fICURLOPT_URL\fP is the only option that must be set before +The string given to CURLOPT_URL must be url-encoded and following the RFC 2396 +(http://curl.haxx.se/rfc/rfc2396.txt). + +\fICURLOPT_URL\fP is the only option that \fBmust\fP be set before \fIcurl_easy_perform(3)\fP is called. .IP CURLOPT_PROXY Set HTTP proxy to use. The parameter should be a char * to a zero terminated -- cgit v1.2.1 From a21a77d2308157dc6058f4356b2d29008e5bc155 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 9 Apr 2006 22:41:22 +0000 Subject: CURLE_FTP_USER_PASSWORD_INCORRECT is not returned by libcurl anymore! --- docs/libcurl/libcurl-errors.3 | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 03c243bf7..fdf632663 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -30,7 +30,7 @@ or problem. .IP "CURLE_URL_MALFORMAT (3)" The URL was not properly formatted. .IP "CURLE_URL_MALFORMAT_USER (4)" -URL user malformatted. The user-part of the URL syntax was not correct. +This is never returned by current libcurl. .IP "CURLE_COULDNT_RESOLVE_PROXY (5)" Couldn't resolve proxy. The given proxy host could not be resolved. .IP "CURLE_COULDNT_RESOLVE_HOST (6)" @@ -45,9 +45,7 @@ remote server is probably not an OK FTP server. We were denied access when trying to login to an FTP server or when trying to change working directory to the one given in the URL. .IP "CURLE_FTP_USER_PASSWORD_INCORRECT (10)" -The FTP server rejected access to the server after the password was sent to -it. It might be because the username and/or the password were incorrect or -just that the server is not allowing you access for the moment etc. +This is never returned by current libcurl. .IP "CURLE_FTP_WEIRD_PASS_REPLY (11)" After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. @@ -87,7 +85,7 @@ returns an error code that is >= 400. An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback. .IP "CURLE_MALFORMAT_USER (24)" -Malformat user. User name badly specified. *Not currently used* +This is never returned by current libcurl. .IP "CURLE_FTP_COULDNT_STOR_FILE (25)" FTP couldn't STOR file. The server denied the STOR operation. The error buffer usually contains the server's explanation to this. @@ -138,15 +136,13 @@ Aborted by callback. A callback returned "abort" to libcurl. .IP "CURLE_BAD_FUNCTION_ARGUMENT (43)" Internal error. A function was called with a bad parameter. .IP "CURLE_BAD_CALLING_ORDER (44)" -Internal error. A function was called in a bad order. +This is never returned by current libcurl. .IP "CURLE_HTTP_PORT_FAILED (45)" Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections' source IP address with CURLOPT_INTERFACE. .IP "CURLE_BAD_PASSWORD_ENTERED (46)" -Bad password entered. An error was signaled when the password was -entered. This can also be the result of a "bad password" returned from a -specified password callback. +This is never returned by current libcurl. .IP "CURLE_TOO_MANY_REDIRECTS (47)" Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS. -- cgit v1.2.1 From b0e4debaab914d5afabea781c378b2cc7833aaca Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 10 Apr 2006 21:55:48 +0000 Subject: adding the new man pages to the package --- docs/libcurl/Makefile.am | 90 +++++++++++++++++++++++++----------------------- 1 file changed, 46 insertions(+), 44 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 77d2f87d3..85dd281eb 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -4,52 +4,54 @@ AUTOMAKE_OPTIONS = foreign no-dependencies -man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ - curl_easy_perform.3 curl_easy_setopt.3 curl_easy_duphandle.3 \ - curl_formadd.3 curl_formfree.3 curl_getdate.3 curl_getenv.3 \ - curl_slist_append.3 curl_slist_free_all.3 curl_version.3 \ - curl_version_info.3 curl_escape.3 curl_unescape.3 curl_free.3 \ - curl_strequal.3 curl_mprintf.3 curl_global_init.3 \ - curl_global_cleanup.3 curl_multi_add_handle.3 curl_multi_cleanup.3 \ - curl_multi_fdset.3 curl_multi_info_read.3 curl_multi_init.3 \ - curl_multi_perform.3 curl_multi_remove_handle.3 curl_share_cleanup.3 \ - curl_share_init.3 curl_share_setopt.3 libcurl.3 libcurl-easy.3 \ - libcurl-multi.3 libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3 \ - curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ - libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 curl_easy_unescape.3 +man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ + curl_easy_perform.3 curl_easy_setopt.3 curl_easy_duphandle.3 \ + curl_formadd.3 curl_formfree.3 curl_getdate.3 curl_getenv.3 \ + curl_slist_append.3 curl_slist_free_all.3 curl_version.3 \ + curl_version_info.3 curl_escape.3 curl_unescape.3 curl_free.3 \ + curl_strequal.3 curl_mprintf.3 curl_global_init.3 curl_global_cleanup.3 \ + curl_multi_add_handle.3 curl_multi_cleanup.3 curl_multi_fdset.3 \ + curl_multi_info_read.3 curl_multi_init.3 curl_multi_perform.3 \ + curl_multi_remove_handle.3 curl_share_cleanup.3 curl_share_init.3 \ + curl_share_setopt.3 libcurl.3 libcurl-easy.3 libcurl-multi.3 \ + libcurl-share.3 libcurl-errors.3 curl_easy_strerror.3 \ + curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ + libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \ + curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ + curl_multi_timeout.3 -HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ - curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ - curl_easy_duphandle.html curl_formadd.html curl_formfree.html \ - curl_getdate.html curl_getenv.html curl_slist_append.html \ - curl_slist_free_all.html curl_version.html curl_version_info.html \ - curl_escape.html curl_unescape.html curl_free.html curl_strequal.html \ - curl_mprintf.html curl_global_init.html curl_global_cleanup.html \ - curl_multi_add_handle.html curl_multi_cleanup.html \ - curl_multi_fdset.html curl_multi_info_read.html curl_multi_init.html \ - curl_multi_perform.html curl_multi_remove_handle.html \ - curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ - libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ - libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ - curl_share_strerror.html curl_global_init_mem.html \ - libcurl-tutorial.html curl_easy_reset.html curl_easy_escape.html \ - curl_easy_unescape.html +HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ + curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ + curl_easy_duphandle.html curl_formadd.html curl_formfree.html \ + curl_getdate.html curl_getenv.html curl_slist_append.html \ + curl_slist_free_all.html curl_version.html curl_version_info.html \ + curl_escape.html curl_unescape.html curl_free.html curl_strequal.html \ + curl_mprintf.html curl_global_init.html curl_global_cleanup.html \ + curl_multi_add_handle.html curl_multi_cleanup.html curl_multi_fdset.html \ + curl_multi_info_read.html curl_multi_init.html curl_multi_perform.html \ + curl_multi_remove_handle.html curl_share_cleanup.html \ + curl_share_init.html curl_share_setopt.html libcurl.html \ + libcurl-multi.html libcurl-easy.html libcurl-share.html \ + libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ + curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \ + curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \ + curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html -PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ - curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ - curl_easy_duphandle.pdf curl_formadd.pdf curl_formfree.pdf \ - curl_getdate.pdf curl_getenv.pdf curl_slist_append.pdf \ - curl_slist_free_all.pdf curl_version.pdf curl_version_info.pdf \ - curl_escape.pdf curl_unescape.pdf curl_free.pdf curl_strequal.pdf \ - curl_mprintf.pdf curl_global_init.pdf curl_global_cleanup.pdf \ - curl_multi_add_handle.pdf curl_multi_cleanup.pdf curl_multi_fdset.pdf \ - curl_multi_info_read.pdf curl_multi_init.pdf curl_multi_perform.pdf \ - curl_multi_remove_handle.pdf curl_share_cleanup.pdf \ - curl_share_init.pdf curl_share_setopt.pdf libcurl.pdf \ - libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ - libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ - curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ - curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf +PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ + curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \ + curl_formadd.pdf curl_formfree.pdf curl_getdate.pdf curl_getenv.pdf \ + curl_slist_append.pdf curl_slist_free_all.pdf curl_version.pdf \ + curl_version_info.pdf curl_escape.pdf curl_unescape.pdf curl_free.pdf \ + curl_strequal.pdf curl_mprintf.pdf curl_global_init.pdf \ + curl_global_cleanup.pdf curl_multi_add_handle.pdf curl_multi_cleanup.pdf \ + curl_multi_fdset.pdf curl_multi_info_read.pdf curl_multi_init.pdf \ + curl_multi_perform.pdf curl_multi_remove_handle.pdf \ + curl_share_cleanup.pdf curl_share_init.pdf curl_share_setopt.pdf \ + libcurl.pdf libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ + libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ + curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ + curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \ + curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -- cgit v1.2.1 From fede784fa2ca73f8efaca013a4e488736986bf13 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 19 Apr 2006 09:08:15 +0000 Subject: the new conversion stuff documented (mostly by David McCreedy) --- docs/libcurl/curl_easy_setopt.3 | 47 +++++++++++++++++++++++++++++++++++++++- docs/libcurl/curl_version_info.3 | 28 ++++++++++++++++++++++-- 2 files changed, 72 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 18718efb0..69fa8b3cf 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "21 Feb 2006" "libcurl 7.15.2" "libcurl Manual" +.TH curl_easy_setopt 3 "19 Apr 2006" "libcurl 7.15.4" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -263,6 +263,51 @@ and trust file settings. Data pointer to pass to the ssl context callback set by the option \fICURLOPT_SSL_CTX_FUNCTION\fP, this is the pointer you'll get as third parameter, otherwise \fBNULL\fP. (Added in 7.11.0) +.IP CURLOPT_CONV_TO_NETWORK_FUNCTION +.IP CURLOPT_CONV_FROM_NETWORK_FUNCTION +.IP CURLOPT_CONV_FROM_UTF8_FUNCTION +Function pointers that should match the following prototype: CURLcode +function(char *ptr, size_t length); + +These three options apply to non-ASCII platforms only. They are available +only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. When +this is the case, \fIcurl_version_info(3)\fP will return the CURL_VERSION_CONV +feature bit set. + +The data to be converted is in a buffer pointed to by the ptr parameter. The +amount of data to convert is indicated by the length parameter. The converted +data overlays the input data in the buffer pointed to by the ptr parameter. +CURLE_OK should be returned upon successful conversion. A CURLcode return +value defined by curl.h, such as CURLE_CONV_FAILED, should be returned if an +error was encountered. + +\fBCURLOPT_CONV_TO_NETWORK_FUNCTION\fP and +\fBCURLOPT_CONV_FROM_NETWORK_FUNCTION\fP convert between the host encoding and +the network encoding. They are used when commands or ASCII data are +sent/received over the network. + +\fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP is called to convert from UTF8 into the +host encoding. It is required only for SSL processing. + +If you set a callback pointer to NULL, or don't set it at all, the built-in +libcurl iconv functions will be used. If HAVE_ICONV was not defined when +libcurl was built, and no callback has been established, conversion will +return the CURLE_CONV_REQD error code. + +If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. +For example: + + \&#define CURL_ICONV_CODESET_OF_HOST "IBM-1047" + +The iconv code in libcurl will default the network and UTF8 codeset names as +follows: + + \&#define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" + + \&#define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" + +You will need to override these definitions if they are different on your +system. .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 80653fb3c..a9fd55d59 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -1,6 +1,27 @@ -.\" $Id$ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** .\" -.TH curl_version_info 3 "11 Mar 2005" "libcurl 7.13.2" "libcurl Manual" +.TH curl_version_info 3 "19 Apr 2006" "libcurl 7.15.4" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -98,6 +119,9 @@ libcurl was built with support for SSPI. This is only available on Windows and makes libcurl use Windows-provided functions for NTLM authentication. It also 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) .RE \fIssl_version\fP is an ascii string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. -- cgit v1.2.1 From 6ef7a81a3b1405ee97519980225aec53240981f2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 26 Apr 2006 13:00:45 +0000 Subject: updated with more error codes --- docs/libcurl/libcurl-errors.3 | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index fdf632663..6fe9971dd 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -190,6 +190,24 @@ rewinding operation 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 +.IP "CURLE_TFTP_PERM (69" +Permission problem on TFTP server +.IP "CURLE_TFTP_DISKFULL (70)" +Out of disk space on TFTP server +.IP "CURLE_TFTP_ILLEGAL (71)" +Illegal TFTP operation +.IP "CURLE_TFTP_UNKNOWNID (72)" +Unknown TFTP transfer ID +.IP "CURLE_TFTP_EXISTS (73)" +TFTP File already exists +.IP "CURLE_TFTP_NOSUCHUSER (74)" +No such TFTP user +.IP "CURLE_CONV_FAILED (75)" +Character conversion failed +.IP "CURLE_CONV_REQD (76)" +Caller must register conversion callbacks .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. Also consider \fIcurl_multi_strerror(3)\fP. -- cgit v1.2.1 From 77475f2ad02ca03b52255b39e1255e048f449f07 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 May 2006 12:56:35 +0000 Subject: Andreas Ntaflos reported a bug in libcurl.m4: When configuring my GNU autotools project, which optionally (default=yes) uses libcurl on a system without a (usable) libcurl installation, but not specifying `--without-libcurl', configure determines correctly that no libcurl is available, however, the LIBCURL variable gets expanded to `LIBCURL = -lcurl' in the resulting Makefiles. David Shaw fixed the flaw. --- docs/libcurl/libcurl.m4 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 798427c14..a9bfa2e23 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -1,7 +1,7 @@ # LIBCURL_CHECK_CONFIG ([DEFAULT-ACTION], [MINIMUM-VERSION], # [ACTION-IF-YES], [ACTION-IF-NO]) # ---------------------------------------------------------- -# David Shaw Jan-17-2006 +# David Shaw May-09-2006 # # Checks for libcurl. DEFAULT-ACTION is the string yes or no to # specify whether to default to --with-libcurl or --without-libcurl. @@ -210,6 +210,9 @@ x=CURLOPT_VERBOSE; AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_protocol_$_libcurl_protocol),[1]) eval AS_TR_SH(libcurl_protocol_$_libcurl_protocol)=yes done + else + unset LIBCURL + unset LIBCURL_CPPFLAGS fi fi -- cgit v1.2.1 From 606562aa7ea28ee0fdd5bf2cd6febada9594ad19 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 24 May 2006 22:46:38 +0000 Subject: Michael Wallner provided a patch that allows "SESS" to be set with CURLOPT_COOKIELIST, which then makes all session cookies get cleared. (slightly edited by me, and the re-indent in cookie.c was also done by me) --- docs/libcurl/curl_easy_setopt.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 69fa8b3cf..5e5afddc6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -762,6 +762,8 @@ Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL cookie engine was not enabled it will enable its cookie engine. Passing a magic string \&"ALL" will erase all cookies known by cURL. (Added in 7.14.1) +Passing the special string \&"SESS" will only erase all session cookies known +by cURL. (Added in 7.15.4) .IP CURLOPT_HTTPGET Pass a long. If the long is non-zero, this forces the HTTP request to get back to GET. usable if a POST, HEAD, PUT or a custom request have been used -- cgit v1.2.1 From 6a151c1312d9dfd6805ea672716b5b6e57e9534d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 8 Jun 2006 11:06:26 +0000 Subject: corrected the CURLINFO_TOTAL_TIME description --- docs/libcurl/curl_easy_getinfo.3 | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index f1d74b698..31f14fe29 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -63,10 +63,8 @@ information before the transfer is made, by using the CURLOPT_FILETIME option to \fIcurl_easy_setopt(3)\fP or you will unconditionally get a -1 back. (Added in 7.5) .IP CURLINFO_TOTAL_TIME -Pass a pointer to a double to receive the total transaction time in seconds -for the previous transfer. This time does not include the connect time, so if -you want the complete operation time, you should add the -CURLINFO_CONNECT_TIME. +Pass a pointer to a double to receive the total time in seconds for the +previous transfer, including name resolving, TCP connect etc. .IP CURLINFO_NAMELOOKUP_TIME Pass a pointer to a double to receive the time, in seconds, it took from the start until the name resolving was completed. @@ -182,7 +180,7 @@ curl_easy_perform() |--|--CT |--|--|--PT |--|--|--|--ST - |--|--|--TT + |--|--|--|--|--TT |--|--|--|--|--RT .FI .IP NT @@ -199,9 +197,7 @@ and negotiations that are specific to the particular protocol(s) involved. \fICURLINFO_STARTTRANSFER_TIME\fP. The time it took from the start until the first byte is just about to be transferred. .IP TT -\fICURLINFO_TOTAL_TIME\fP. Time of the previous transfer. This time does not -include the connect time (CT), so if you want the complete operation time, you -should add that. +\fICURLINFO_TOTAL_TIME\fP. Total time of the previous request. .IP RT \fICURLINFO_REDIRECT_TIME\fP. The time it took for all redirection steps include name lookup, connect, pretransfer and transfer before final -- cgit v1.2.1 From 4cb30a3057bbc79c5b1910c7123d5d2ea148e40f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 20 Jun 2006 07:03:29 +0000 Subject: bad syntax --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5e5afddc6..0183da44c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1111,7 +1111,7 @@ Resolve to ipv4 addresses. .IP CURL_IPRESOLVE_V6 Resolve to ipv6 addresses. .RE -.SH CURLOPT_CONNECT_ONLY +.IP CURLOPT_CONNECT_ONLY Pass a long. A non-zero parameter tells the library to perform any required proxy authentication and connection setup, but no data transfer. -- cgit v1.2.1 From 3e5dcc8bcd4aaa7b6d7f8432327cbdd5487113e4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 21 Jun 2006 17:34:29 +0000 Subject: minor language edits bug reports 1510080 1510098 --- docs/libcurl/libcurl-tutorial.3 | 2 +- docs/libcurl/libcurl.3 | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index f23d52968..8f1625150 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -212,7 +212,7 @@ opened for writing with the \fICURLOPT_WRITEDATA\fP option. Now, we need to take a step back and have a deep breath. Here's one of those rare platform-dependent nitpicks. Did you spot it? On some platforms[2], libcurl won't be able to operate on files opened by the program. Thus, if you -use the default callback and pass in a an open file with +use the default callback and pass in an open file with \fICURLOPT_WRITEDATA\fP, it will crash. You should therefore avoid this to make your program run fine virtually everywhere. diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 6d18e1fd1..9c48f7405 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -10,8 +10,8 @@ specific man pages for each function mentioned in here. There are also the \fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for in-depth understanding on how to program with libcurl. -There are more than a twenty custom bindings available that bring libcurl -access to your favourite language. Look elsewhere for documentation on those. +There are more than thirty custom bindings available that bring libcurl access +to your favourite language. Look elsewhere for documentation on those. libcurl has a global constant environment that you must set up and maintain while using libcurl. This essentially means you call -- cgit v1.2.1 From dfe1884c2529d728750d0824f73055627673cd72 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Jun 2006 21:36:53 +0000 Subject: Peter Silva introduced CURLOPT_MAX_SEND_SPEED_LARGE and CURLOPT_MAX_RECV_SPEED_LARGE that limit tha maximum rate libcurl is allowed to send or receive data. This kind of adds the the command line tool's option --limit-rate to the library. The rate limiting logic in the curl app is now removed and is instead provided by libcurl itself. Transfer rate limiting will now also work for -d and -F, which it didn't before. --- docs/libcurl/curl_easy_setopt.3 | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0183da44c..c4b969577 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1051,6 +1051,14 @@ for the library to consider it too slow and abort. Pass a long as parameter. It contains the time in seconds that the transfer should be below the \fICURLOPT_LOW_SPEED_LIMIT\fP for the library to consider it too slow and abort. +.IP CURLOPT_MAX_SEND_SPEED_LARGE +Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative +average during the transfer, the transfer will pause to keep the average rate +less than or equal to the parameter value. (default: 0, unlimited) +.IP CURLOPT_MAX_RECV_SPEED_LARGE +Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative +average during the transfer, the transfer will pause to keep the average rate +less than or equal to the parameter value. (default: 0, unlimited) .IP CURLOPT_MAXCONNECTS 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 -- cgit v1.2.1 From 37f4877e569cdd0d1afa6bb0d7cd3a463ee75ac9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 24 Jun 2006 21:46:41 +0000 Subject: Michael Wallner added curl_formget(), which allows an application to extract (serialise) a previously built formpost (as with curl_formadd()). --- docs/libcurl/Makefile.am | 8 +++++--- docs/libcurl/curl_formget.3 | 49 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 docs/libcurl/curl_formget.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 85dd281eb..e43a0b67c 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -18,7 +18,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ - curl_multi_timeout.3 + curl_multi_timeout.3 curl_formget.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -35,7 +35,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \ curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \ - curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html + curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \ + curl_formget.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \ @@ -51,7 +52,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \ - curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf + curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \ + curl_formget.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 new file mode 100644 index 000000000..b0aad3670 --- /dev/null +++ b/docs/libcurl/curl_formget.3 @@ -0,0 +1,49 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.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 +.SH SYNOPSIS +.B #include +.sp +.BI "void curl_formget(struct curl_httppost *" form, " void *" arg, +.BI " curl_formget_callback " append); +.ad +.SH DESCRIPTION +curl_formget() is used to serialize data previously built/appended with +\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument which will be +passed to the curl_formget_callback function. + +.B "typedef size_t (*curl_formget_callback)(void *" arg, " const char *" buf, +.B " size_t " len); +.nf + +The curl_formget_callback will be executed for each part of the httppost +struct. The void *arg pointer will be the one passed as second argument to +curl_formget(). The character buffer passed to it must not be freed. The +callback should return the buffer length passed to it on success. +.SH RETURN VALUE +0 means everything was ok, non-zero means an error occurred +.SH EXAMPLE +.nf + + size_t print_httppost_callback(void *arg, const char *buf, size_t len) + { + fwrite(buf, len, 1, stdout); + (*(size_t *) arg) += len; + return len; + } + size_t print_httppost(struct curl_httppost *post) + { + size_t total_size = 0; + if(curl_formget(post, &total_size, out)) { + return (size_t) -1; + } + return total_size; + } +.SH AVAILABILITY +This function was added in libcurl 7.15.5 +.SH "SEE ALSO" +.BR curl_formadd "(3) " -- cgit v1.2.1 From 00a41ab29673b834ea89cdfc70864f99df442c61 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 24 Jun 2006 21:49:40 +0000 Subject: corrected introduction version number --- docs/libcurl/curl_multi_setopt.3 | 2 +- docs/libcurl/curl_multi_socket.3 | 2 +- docs/libcurl/curl_multi_timeout.3 | 2 +- docs/libcurl/libcurl-errors.3 | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 6f88b989b..623daa53f 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -36,7 +36,7 @@ The standard CURLMcode for multi interface error codes. Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl doesn't know of. .SH AVAILABILITY -This function was added in libcurl 7.16.0 +This function was added in libcurl 7.15.4. .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_socket "(3), " curl_multi_info_read "(3)" diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 12082ff3f..e5312c840 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -90,7 +90,7 @@ action. 9. Go back to step 6. .SH AVAILABILITY -This function was added in libcurl 7.16.0 +This function was added in libcurl 7.15.4, although not deemed stable yet. .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index a06bffbdc..b04acf890 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -30,7 +30,7 @@ Call \fBcurl_multi_timeout(3)\fP, then wait for action on the sockets. You figure out which sockets to wait for by calling \fBcurl_multi_fdset(3)\fP or by a previous call to \fBcurl_multi_socket(3)\fP. .SH AVAILABILITY -This function was added in libcurl 7.16.0 +This function was added in libcurl 7.15.4, although not deemed stable yet. .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 6fe9971dd..baa9bc5fd 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -226,7 +226,7 @@ You are doomed. This can only be returned if libcurl bugs. Please report it to us! .IP "CURLM_BAD_SOCKET (5)" The passed-in socket is not a valid one that libcurl already knows about. -(Added in 7.16.0) +(Added in 7.15.4) .SH "CURLSHcode" The "share" interface will return a CURLSHcode to indicate when an error has occurred. Also consider \fIcurl_share_strerror(3)\fP. -- cgit v1.2.1 From eb6d40475302046be6664436cf5687db79f2ba2b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 24 Jun 2006 23:11:36 +0000 Subject: Wallner's update --- docs/libcurl/curl_formget.3 | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index b0aad3670..4350af352 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -9,20 +9,20 @@ curl_formget - serialize a previously build multipart/formdata HTTP POST chain .B #include .sp .BI "void curl_formget(struct curl_httppost *" form, " void *" arg, -.BI " curl_formget_callback " append); +.BI " curl_formget_callback " append ");" .ad .SH DESCRIPTION curl_formget() is used to serialize data previously built/appended with \fIcurl_formadd(3)\fP. Accepts a void pointer as second argument which will be passed to the curl_formget_callback function. -.B "typedef size_t (*curl_formget_callback)(void *" arg, " const char *" buf, -.B " size_t " len); +.BI "typedef size_t (*curl_formget_callback)(void *" arg, " const char *" buf, +.BI " size_t " len ");" .nf -The curl_formget_callback will be executed for each part of the httppost -struct. The void *arg pointer will be the one passed as second argument to -curl_formget(). The character buffer passed to it must not be freed. The +The curl_formget_callback will be executed for each part of the HTTP POST +chain. The void *arg pointer will be the one passed as second argument to +curl_formget(). The character buffer passed to it must not be freed. The callback should return the buffer length passed to it on success. .SH RETURN VALUE 0 means everything was ok, non-zero means an error occurred @@ -38,7 +38,7 @@ callback should return the buffer length passed to it on success. size_t print_httppost(struct curl_httppost *post) { size_t total_size = 0; - if(curl_formget(post, &total_size, out)) { + if(curl_formget(post, &total_size, print_httppost_callback)) { return (size_t) -1; } return total_size; -- cgit v1.2.1 From 01f5f0be5aa534564a61fa3ea976dd72de7d2c0d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Jun 2006 06:43:45 +0000 Subject: changed wording slightly, and added standard boiler-plate header --- docs/libcurl/libcurl-multi.3 | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 955063a34..b6d95b1d7 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -1,6 +1,25 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** .\" .TH libcurl-multi 3 "13 Oct 2001" "libcurl 7.10.1" "libcurl multi interface" .SH NAME @@ -14,8 +33,8 @@ for an overview of the libcurl easy interface. All functions in the multi interface are prefixed with curl_multi. .SH "OBJECTIVES" -The multi interface introduces several new abilities that the easy interface -refuses to offer. They are mainly: +The multi interface offers several abilities that the easy interface doesn't. +They are mainly: 1. Enable a "pull" interface. The application that uses libcurl decides where and when to ask libcurl to get/send data. @@ -23,8 +42,8 @@ and when to ask libcurl to get/send data. 2. Enable multiple simultaneous transfers in the same thread without making it complicated for the application. -3. Enable the application to select() on its own file descriptors and curl's -file descriptors simultaneous easily. +3. Enable the application to wait for action on its own file descriptors and +curl's file descriptors simultaneous easily. .SH "ONE MULTI HANDLE MANY EASY HANDLES" To use the multi interface, you must first create a 'multi handle' with \fIcurl_multi_init(3)\fP. This handle is then used as input to all further -- cgit v1.2.1 From a09a8164db637b35de52bdea757e8ea930f28eaf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 7 Jul 2006 22:07:10 +0000 Subject: mention the by-default "sharing" --- docs/libcurl/curl_share_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index e53946534..e6be1b4ee 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -42,7 +42,9 @@ be set to one of the values described below. Cookie data will be shared across the easy handles using this shared object. .IP CURL_LOCK_DATA_DNS Cached DNS hosts will be shared across the easy handles using this shared -object. +object. Note that when you use the multi interface, all easy handles added to +the same multi handle will share DNS cache by default without this having to +be used! .RE .IP CURLSHOPT_UNSHARE This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that -- cgit v1.2.1 From ee8112b42f0114eda71fe07d9a6f5f202910acc4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 7 Jul 2006 23:08:03 +0000 Subject: mention the shared DNS stuff --- docs/libcurl/curl_multi_add_handle.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index 11e530b98..3ce9f78ea 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -15,6 +15,11 @@ this \fImulti_handle\fP control the specified \fIeasy_handle\fP. When an easy handle has been added to a multi stack, you can not and you must not use \fIcurl_easy_perform(3)\fP on that handle! +If the easy handle is not set to use a shared (CURLOPT_SHARE) or global DNS +cache (CURLOPT_DNS_USE_GLOBAL_CACHE), it will be made to use the DNS cache +that is shared between all easy handles within the multi handle when +\fIcurl_multi_add_handle(3)\fP is called. + The easy handle will remain added until you remove it again with \fIcurl_multi_remove_handle(3)\fP. You should remove the easy handle from the multi stack before you terminate first the easy handle and then the multi -- cgit v1.2.1 From 2527b5301946539363754a390974cdd3a3d34485 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 25 Jul 2006 22:45:21 +0000 Subject: Dan Nelson added the CURLOPT_FTP_ALTERNATIVE_TO_USER libcurl option and curl tool option named --ftp-alternative-to-user. It provides a mean to send a particular command if the normal USER/PASS approach fails. --- docs/libcurl/curl_easy_setopt.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c4b969577..6ac538a7a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -859,6 +859,12 @@ waiting for a response, this value overrides \fICURLOPT_TIMEOUT\fP. It is recommended that if used in conjunction with \fICURLOPT_TIMEOUT\fP, you set \fICURLOPT_FTP_RESPONSE_TIMEOUT\fP to a value smaller than \fICURLOPT_TIMEOUT\fP. (Added in 7.10.8) +.IP CURLOPT_FTP_ALTERNATIVE_TO_USER +Pass a char * as parameter, pointing to a string which will be used to +authenticate if the usual FTP "USER user" and "PASS password" negotiation +fails. This is currently only known to be required when connecting to +Tumbleweed's Secure Transport FTPS server using client certificates for +authentication. (Added in 7.15.5) .IP CURLOPT_FTP_SKIP_PASV_IP Pass a long. If set to a non-zero value, it instructs libcurl to not use the IP address the server suggests in its 227-response to libcurl's PASV command -- cgit v1.2.1 From 6f6b93da02019141812b81bfdbb6bcda430c3b4d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 26 Jul 2006 22:19:42 +0000 Subject: [Hiper-related work] Added a function called curl_multi_assign() that will set a private pointer added to the internal libcurl hash table for the particular socket passed in to this function. --- docs/libcurl/Makefile.am | 10 ++++----- docs/libcurl/curl_global_init.3 | 34 ++++++++++++++-------------- docs/libcurl/curl_multi_assign.3 | 44 ++++++++++++++++++++++++++++++++++++ docs/libcurl/curl_multi_setopt.3 | 5 +++-- docs/libcurl/curl_multi_socket.3 | 48 +++++++++++++++++++++++++++------------- 5 files changed, 102 insertions(+), 39 deletions(-) create mode 100644 docs/libcurl/curl_multi_assign.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index e43a0b67c..ea96cea1d 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -18,7 +18,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ - curl_multi_timeout.3 curl_formget.3 + curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -35,8 +35,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \ curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \ - curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \ - curl_formget.html + curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \ + curl_formget.html curl_multi_assign.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \ @@ -52,8 +52,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \ - curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \ - curl_formget.pdf + curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \ + curl_formget.pdf curl_multi_assign.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index 0729ef787..ba15ad4e0 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -11,30 +11,30 @@ curl_global_init - Global libcurl initialisation .BI "CURLcode curl_global_init(long " flags ");" .ad .SH DESCRIPTION -This function sets up the program environment that libcurl needs. Think -of it as an extension of the library loader. +This function sets up the program environment that libcurl needs. Think of it +as an extension of the library loader. -This function must be called at least once within a program (a program is -all the code that shares a memory space) before the program calls any other -function in libcurl. The environment it sets up is constant for the life -of the program and is the same for every program, so multiple calls have -the same effect as one call. +This function must be called at least once within a program (a program is all +the code that shares a memory space) before the program calls any other +function in libcurl. The environment it sets up is constant for the life of +the program and is the same for every program, so multiple calls have the same +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 libcurl. +value unless you are familiar with and mean to control internal operations of +libcurl. -\fBThis function is not thread safe.\fP You must not call it when any -other thread in the program (i.e. a thread sharing the same memory) is -running. This doesn't just mean no other thread that is using -libcurl. Because \fIcurl_global_init()\fP calls functions of other -libraries that are similarly thread unsafe, it could conflict with any -other thread that uses these other libraries. +\fBThis function is not thread safe.\fP You must not call it when any other +thread in the program (i.e. a thread sharing the same memory) is running. +This doesn't just mean no other thread that is using libcurl. Because +\fIcurl_global_init()\fP calls functions of other libraries that are similarly +thread unsafe, it could conflict with any other thread that uses these other +libraries. -See the description in \fBlibcurl\fP(3) of global environment -requirements for details of how to use this function. +See the description in \fBlibcurl\fP(3) of global environment requirements for +details of how to use this function. .SH FLAGS .TP 5 diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3 new file mode 100644 index 000000000..cb47a5e25 --- /dev/null +++ b/docs/libcurl/curl_multi_assign.3 @@ -0,0 +1,44 @@ +.\" $Id$ +.\" +.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 +.SH SYNOPSIS +#include + +CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd, + void *sockptr); +.SH DESCRIPTION +This function assigns an association in the multi handle between the given +socket and a private pointer of the application. This is (only) useful for +\fIcurl_multi_socket(3)\fP uses. + +When set, the \fIsockptr\fP pointer will be passed to all future socket +callbacks for the specific \fIsockfd\fP socket. + +If the given \fIsockfd\fP isn't already in use by libcurl, this function will +return an error. + +libcurl only keeps one single pointer associated with a socket, so calling +this function several times for the same socket will make the last set pointer +get used. + +The idea here being that this association (socket to private pointer) is +something that just about every application that uses this API will need and +then libcurl can just as well do it since it already has an internal hash +table lookup for this. +.SH "RETURN VALUE" +The standard CURLMcode for multi interface error codes. +.SH "TYPICAL USAGE" +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 +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. +.SH AVAILABILITY +This function was added in libcurl 7.15.5, although not deemed stable yet. +.SH "SEE ALSO" +.BR curl_multi_setopt "(3), " curl_multi_socket "(3) " diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 623daa53f..0228e3d64 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -25,8 +25,9 @@ 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 is NULL, no callback will -be called. Set the callback's fourth argument with \fICURLMOPT_SOCKETDATA\fP. -See \fIcurl_multi_socket(3)\fP for more callback details. +be called. Set the callback's \fBuserp\fP argument with +\fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more callback +details. .IP CURLMOPT_SOCKETDATA Pass a pointer to whatever you want passed to the curl_socket_callback's forth argument, the userp pointer. This is not used by libcurl but only passed-thru diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index e5312c840..0c5ba7345 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_socket 3 "21 Dec 2005" "libcurl 7.16.0" "libcurl Manual" +.TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_socket \- reads/writes available data .SH SYNOPSIS @@ -19,32 +19,41 @@ application has detected action on a socket handled by libcurl, it should call with the action. These functions inform the application about updates in the socket (file -descriptor) status by doing none, one or multiple calls to the -curl_socket_callback given with the CURLMOPT_SOCKETFUNCTION option to +descriptor) status by doing none, one or multiple calls to the callback +function set with the CURLMOPT_SOCKETFUNCTION option to \fIcurl_multi_setopt(3)\fP. They update the status with changes since the previous time this function was called. -If you want to force libcurl to (re-)check all its internal sockets and -transfers instead of just a single one, you call -\fBcurl_multi_socket_all(3)\fP instead. +To force libcurl to (re-)check all its internal sockets and transfers instead +of just a single one, you call \fBcurl_multi_socket_all(3)\fP. -An application should call \fBcurl_multi_timeout(3)\fP to figure out how long -it should wait for socket actions \- at most \- before doing the timeout -action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP -argument set to CURL_SOCKET_TIMEOUT. +Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to +wait for socket actions \- at most \- before doing the timeout action: call +the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to +CURL_SOCKET_TIMEOUT. + +.SH "CALLBACK DETAILS" The socket \fBcallback\fP function uses a prototype like this .nf - int curl_socket_callback(CURL *easy, /* easy handle */ - curl_socket_t s, /* socket */ - int action, /* see values below */ - void *userp); /* "private" pointer */ + int curl_socket_callback(CURL *easy, /* easy handle */ + curl_socket_t s, /* socket */ + int action, /* see values below */ + void *userp, /* private callback pointer */ + void *socketp); /* private socket pointer */ .fi The callback MUST return 0. -The \fIaction\fP (third) argument to the callback has one of five values: +The \fIeasy\fP argument is a pointer to the easy handle that deals with this +particular socket. Note that a single handle may work with several sockets +simultaneously. + +The \fIs\fP argument is the actual socket value as you use it within your +system. + +The \fIaction\fP argument to the callback has one of five values: .RS .IP "CURL_POLL_NONE (0)" register, not interested in readiness (yet) @@ -57,6 +66,15 @@ register, interested in both read and write readiness .IP "CURL_POLL_REMOVE (4)" deregister .RE + +The \fIsocketp\fP argument is a private pointer you have previously set with +\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no +pointer has been set, socketp will be NULL. This argument is of course a +service to applications that want to keep certain data or structs that are +strictly associated to the given socket. + +The \fIuserp\fP argument is a private pointer you have previously set with +\fIcurl_multi_setopt(3)\fP and the CURLMOPT_SOCKETDATA option. .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. -- cgit v1.2.1 From 825a5267897f62d558cf299af83d8087b473cc41 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 1 Aug 2006 08:57:32 +0000 Subject: updated docs with the new parameter --- docs/libcurl/curl_multi_socket.3 | 40 ++++++++++++++++++++++++++-------------- 1 file changed, 26 insertions(+), 14 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 0c5ba7345..9ad8257f1 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -6,26 +6,38 @@ curl_multi_socket \- reads/writes available data .SH SYNOPSIS #include -CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd); +CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, + int *running_handles); -CURLMcode curl_multi_socket_all(CURLM *multi_handle); +CURLMcode curl_multi_socket_all(CURLM *multi_handle, + int *running_handles); .SH DESCRIPTION -Alternative versions of \fIcurl_multi_perform()\fP that allows the application -to pass in one of the file descriptors/sockets that have been detected to have -\&"action" on them and let libcurl perform. This allows libcurl to not have to -scan through all possible file descriptors to check for action. When the -application has detected action on a socket handled by libcurl, it should call -\fIcurl_multi_perform()\fP with the \fBsockfd\fP argument set to the socket -with the action. - -These functions inform the application about updates in the socket (file -descriptor) status by doing none, one or multiple calls to the callback -function set with the CURLMOPT_SOCKETFUNCTION option to +Alternative versions of \fIcurl_multi_perform(3)\fP that allows the +application to pass in one of the file descriptors/sockets that have been +detected to have \&"action" on them and let libcurl perform. This allows +libcurl to not have to scan through all possible file descriptors to check for +action. When the application has detected action on a socket handled by +libcurl, it should call \fIcurl_multi_socket(3)\fP with the \fBsockfd\fP +argument set to the socket with the action. + +At return, the int \fBrunning_handles\fP points to will contain the number of +still running easy handles within the multi handle. When this number reaches +zero, all transfers are complete/done. Note that when you call +\fIcurl_multi_socket(3)\fP on a specific socket and the counter decreases by +one, it DOES NOT necessarily mean that this exact socket/transfer is the one +that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy +handle that completed. + +The curl_multi_socket functions inform the application about 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 this function was called. To force libcurl to (re-)check all its internal sockets and transfers instead -of just a single one, you call \fBcurl_multi_socket_all(3)\fP. +of just a single one, you call \fBcurl_multi_socket_all(3)\fP. This is +typically done as the first function call before the application has any +knowledge about what sockets libcurl uses. Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to wait for socket actions \- at most \- before doing the timeout action: call -- cgit v1.2.1 From fbcdc192d58ee0ffada26a7ea42feade87a81ecb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 2 Aug 2006 09:33:32 +0000 Subject: a CURLOPT_PROGRESSFUNCTION clarification --- docs/libcurl/curl_easy_setopt.3 | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6ac538a7a..6be387d11 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -169,11 +169,12 @@ added in 7.12.3) .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of -its internal equivalent with a frequent interval during data transfer (roughly -once per second). Unknown/unused argument values pass to the callback will be -set to zero (like if you only download data, the upload size will remain -0). Returning a non-zero value from this callback will cause libcurl to abort -the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. +its internal equivalent with a frequent interval during operation (roughly +once per second) no matter if data is being transfered or not. Unknown/unused +argument values passed to the callback will be set to zero (like if you only +download data, the upload size will remain 0). Returning a non-zero value from +this callback will cause libcurl to abort the transfer and return +\fICURLE_ABORTED_BY_CALLBACK\fP. If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl -- cgit v1.2.1 From 1eedad27a23e2158d5939deda66182f97cfe2212 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 8 Aug 2006 22:56:46 +0000 Subject: Armel Asselin made the CURLOPT_PREQUOTE option work fine even when CURLOPT_NOBODY is set true. PREQUOTE is then run roughly at the same place in the command sequence as it would have run if there would've been a transfer. --- docs/libcurl/curl_easy_setopt.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6be387d11..ea0cd165a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -821,7 +821,8 @@ Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. 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. +option. Before version 7.15.6, if you also set \fICURLOPT_NOBODY\fP non-zero, +this option didn't work. .IP CURLOPT_FTPLISTONLY A non-zero parameter tells the library to just list the names of an ftp directory, instead of doing a full directory listing that would include file -- cgit v1.2.1 From b04cbebf868f3e651e2f9fd85ff3a56b01004ac5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 9 Aug 2006 20:54:17 +0000 Subject: option name spell fix --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ea0cd165a..7bab361fb 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -999,9 +999,9 @@ libcurl what the expected size of the infile is. This value should be passed as a curl_off_t. (Added in 7.11.0) .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The -\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZEE\fP or -\fICURLOPT_INFILESIZE_LARGE\fP are also interesting for uploads. If the -protocol is HTTP, uploading means using the PUT request unless you tell +\fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP or +\fICURLOPT_INFILESIZE_LARGE\fP options are also interesting for uploads. If +the protocol is HTTP, uploading means using the PUT request unless you tell libcurl otherwise. Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. -- cgit v1.2.1 From da48a6ba87f76f64287bb14bcae37b1aa00a0a0a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 23 Aug 2006 21:49:44 +0000 Subject: clarify the string syntax support in the CURLOPT_PROXY section --- docs/libcurl/curl_easy_setopt.3 | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7bab361fb..0fce61a98 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -365,9 +365,10 @@ 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 does however override any possibly set environment variables. -Starting with 7.14.1, the proxy host string can be specified the exact same -way as the proxy environment variables, include protocol prefix (http://) and -embedded user + password. +Starting with 7.14.1, the proxy host string given in environment variables can +be specified the exact same way as the proxy can be set with +\fICURLOPT_PROXY\fP, include protocol prefix (http://) and embedded user + +password. .IP CURLOPT_PROXYPORT Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. -- cgit v1.2.1 From 5acadc9cd7a1ff40ffa8d57214c90d8c788b2b03 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 29 Aug 2006 14:39:33 +0000 Subject: David McCreedy added CURLOPT_SOCKOPTFUNCTION and CURLOPT_SOCKOPTDATA to allow applications to set their own socket options. --- docs/libcurl/curl_easy_setopt.3 | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0fce61a98..98abd417d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -160,12 +160,28 @@ found in \fI\fP. This function gets called by libcurl when something special I/O-related needs to be done that the library can't do by itself. For now, rewinding the read data stream is the only action it can request. The rewinding of the read data stream may be necessary when doing a -HTTP PUT or POST with a multi-pass authentication method. (Opion added in +HTTP PUT or POST with a multi-pass authentication method. (Option added in 7.12.3) .IP CURLOPT_IOCTLDATA Pass a pointer that will be untouched by libcurl and passed as the 3rd argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP. (Option added in 7.12.3) +.IP CURLOPT_SOCKOPTFUNCTION +Function pointer that should match the \fIcurl_sockopt_callback\fP prototype +found in \fI\fP. This function gets called by libcurl after the +socket() call but before the connect() call. The callback's \fIpurpose\fP +argument identifies the exact purpose for this particular socket, and +currently only one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the +primary connection (meaning the control connection in the FTP case). Future +versions of libcurl may support more purposes. It passes the newly created +socket descriptor so additional setsockopt() calls can be done at the user's +discretion. A non-zero return code from the callback function will signal an +unrecoverable error to the library and it will close the socket and return +\fICURLE_COULDNT_CONNECT\fP. (Option added in 7.15.6.) +.IP CURLOPT_SOCKOPTDATA +Pass a pointer that will be untouched by libcurl and passed as the first +argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. +(Option added in 7.15.6.) .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of -- cgit v1.2.1 From 1e9be353c27a6351d96183acf23167db6394d611 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 3 Sep 2006 22:12:57 +0000 Subject: Mohun Biswas' improvements and clarifications about the options and how to use them. --- docs/libcurl/curl_formadd.3 | 108 ++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 50 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 3a45f006e..a94dd506f 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -23,88 +23,96 @@ After the \fIlastitem\fP pointer follow the real arguments. The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to NULL in the first call to this function. All list-data will be allocated by -the function itself. You must call \fIcurl_formfree\fP after the form post has -been done to free the resources again. +the function itself. You must call \fIcurl_formfree(3)\fP after the form post +has been done to free the resources. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. First, there are some basics you need to understand about multipart/formdata posts. Each part consists of at least a NAME and a CONTENTS part. If the part -is made for file upload, there are also a stored CONTENT-TYPE and a -FILENAME. Below here, we'll discuss on what options you use to set these -properties in the parts you want to add to your post. +is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. +Below, we'll discuss what options you use to set these properties in the +parts you want to add to your post. + +The options listed first are for making normal parts. The options from +\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload +parts. + .SH OPTIONS + .IP CURLFORM_COPYNAME -followed by string is used to set the name of this part. libcurl copies the -given data, so your application doesn't need to keep it around after this -function call. If the name isn't zero terminated properly, or if you'd like it -to contain zero bytes, you need to set the length of the name with -\fBCURLFORM_NAMELENGTH\fP. +followed by a string which provides the \fIname\fP of this part. libcurl +copies the string so your application doesn't need to keep it around after +this function call. If the name isn't null terminated, or if you'd +like it to contain zero bytes, you must set its length with +\fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by +\fIcurl_formfree(3)\fP. .IP CURLFORM_PTRNAME -followed by a string is used for the name of this part. libcurl will use the -pointer and refer to the data in your application, you must make sure it -remains until curl no longer needs it. If the name isn't zero terminated -properly, or if you'd like it to contain zero bytes, you need to set the -length of the name with \fBCURLFORM_NAMELENGTH\fP. +followed by a string which provides the \fIname\fP of this part. libcurl +will use the pointer and refer to the data in your application, so you +must make sure it remains until curl no longer needs it. If the name +isn't null terminated, or if you'd like it to contain zero +bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. .IP CURLFORM_COPYCONTENTS -followed by a string is used for the contents of this part, the actual data to -send away. libcurl copies the given data, so your application doesn't need to -keep it around after this function call. If the data isn't zero terminated -properly, or if you'd like it to contain zero bytes, you need to set the -length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. +followed by a pointer to the contents of this part, the actual data +to send away. libcurl copies the provided data, so your application doesn't +need to keep it around after this function call. If the data isn't null +terminated, or if you'd like it to contain zero bytes, you must +set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied +data will be freed by \fIcurl_formfree(3)\fP. .IP CURLFORM_PTRCONTENTS -followed by a string is used for the contents of this part, the actual data to -send away. libcurl will use the pointer and refer to the data in your -application, you must make sure it remains until curl no longer needs it. If -the data isn't zero terminated properly, or if you'd like it to contain zero -bytes, you need to set the length of the name with -\fBCURLFORM_CONTENTSLENGTH\fP. +followed by a pointer to the contents of this part, the actual data +to send away. libcurl will use the pointer and refer to the data in your +application, so you must make sure it remains until curl no longer needs it. +If the data isn't null terminated, or if you'd like it to contain zero bytes, +you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. .IP CURLFORM_CONTENTSLENGTH -followed by a long setting the length of the contents. +followed by a long giving the length of the contents. .IP CURLFORM_FILECONTENT -followed by a file name, makes that file read and the contents will be used in -as data in this part. +followed by a filename, causes that file to be read and its contents used +as data in this part. This part does \fInot\fP automatically become a file +upload part simply because its data was read from a file. .IP CURLFORM_FILE -followed by a file name, makes this part a file upload part. It sets the file -name field to the actual file name used here, it gets the contents of the file -and passes as data and sets the content-type if the given file match one of -the new internally known file extension. For \fBCURLFORM_FILE\fP the user may -send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP -arguments each followed by the filename (and each CURLFORM_FILE is allowed to -have a CURLFORM_CONTENTTYPE). +followed by a filename, makes this part a file upload part. It sets the +\fIfilename\fP field to the basename of the provided filename, it reads the +contents of the file and passes them as data and sets the content-type if the +given file match one of the internally known file extensions. For +\fBCURLFORM_FILE\fP the user may send one or more files in one part by +providing multiple \fBCURLFORM_FILE\fP arguments each followed by the +filename (and each CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE). .IP CURLFORM_CONTENTTYPE -followed by a pointer to a string with a content-type will make curl use this -given content-type for this file upload part, possibly instead of an +is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a +string which provides the content-type for this part, possibly instead of an internally chosen one. .IP CURLFORM_FILENAME -followed by a pointer to a string to a name, will make libcurl use the given -name in the file upload part, instead of the actual file name given to -\fICURLFORM_FILE\fP. +is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a +string, it tells libcurl to use the given string as the \fIfilename\fP in the +file upload part instead of the actual file name. .IP CURLFORM_BUFFER -followed by a string, tells libcurl that a buffer is to be used to upload data -instead of using a file. The given string is used as the value of the file -name field in the content header. +is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It +tells libcurl that the file contents are already present in a buffer. The +parameter is a string which provides the \fIfilename\fP field in the content +header. .IP CURLFORM_BUFFERPTR -followed by a pointer to a data area, tells libcurl the address of the buffer -containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The -buffer containing this data must not be freed until after +is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer +to the buffer to be uploaded. This buffer must not be freed until after \fIcurl_easy_cleanup(3)\fP is called. You must also use -\fICURLFORM_BUFFERLENGTH\fP to set the length of the given buffer area. +\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. .IP CURLFORM_BUFFERLENGTH -followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area, -tells libcurl the length of the buffer to upload. +is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a +long which gives the length of the buffer. .IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the -- cgit v1.2.1 From b7eeb6e67fca686f840eacd6b8394edb58b07482 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 Sep 2006 21:49:20 +0000 Subject: Major overhaul introducing http pipelining support and shared connection cache within the multi handle. --- docs/libcurl/curl_multi_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 0228e3d64..5279055ce 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -32,6 +32,13 @@ details. Pass a pointer to whatever you want passed to the curl_socket_callback's forth argument, the userp pointer. This is not used by libcurl but only passed-thru as-is. Set the callback pointer with \fICURLMOPT_SOCKETFUNCTION\fP. +.IP CURLMOPT_PIPELINING +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 +7.16.0) .SH RETURNS The standard CURLMcode for multi interface error codes. Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl -- cgit v1.2.1 From 9cc3795f1af9f84fa214ef2eefb1a4e6ff698620 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 8 Sep 2006 12:46:41 +0000 Subject: Mention that CURLOPT_MAX_RECV/SEND* were added in 7.15.5 --- docs/libcurl/curl_easy_setopt.3 | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 98abd417d..b4a128508 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1077,13 +1077,15 @@ Pass a long as parameter. It contains the time in seconds that the transfer should be below the \fICURLOPT_LOW_SPEED_LIMIT\fP for the library to consider it too slow and abort. .IP CURLOPT_MAX_SEND_SPEED_LARGE -Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative -average during the transfer, the transfer will pause to keep the average rate -less than or equal to the parameter value. (default: 0, unlimited) +Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative +average during the transfer, the transfer will pause to keep the average rate +less than or equal to the parameter value. Defaults to unlimited +speed. (Added in 7.15.5) .IP CURLOPT_MAX_RECV_SPEED_LARGE -Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative -average during the transfer, the transfer will pause to keep the average rate -less than or equal to the parameter value. (default: 0, unlimited) +Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative +average during the transfer, the transfer will pause to keep the average rate +less than or equal to the parameter value. Defaults to unlimited speed. (Added +in 7.15.5) .IP CURLOPT_MAXCONNECTS 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 -- cgit v1.2.1 From 29dc39fce1126265d8526be15beec3e3fdc1c11d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 Sep 2006 17:18:18 +0000 Subject: - Fixed my breakage from earlier today so that doing curl_easy_cleanup() on a handle that is part of a multi handle first removes the handle from the stack. - Added CURLOPT_SSL_SESSIONID_CACHE and --no-sessionid to disable SSL session-ID re-use on demand since there obviously are broken servers out there that misbehave with session-IDs used. --- docs/libcurl/curl_easy_setopt.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b4a128508..5e11cf38c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1302,6 +1302,12 @@ compile OpenSSL. You'll find more details about cipher lists on this URL: \fIhttp://www.openssl.org/docs/apps/ciphers.html\fP +.IP CURLOPT_SSL_SESSIONID_CACHE +Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set +this to 1 to enable it. By default all transfers are done using the +cache. Note that while nothing ever should get hurt by attempting to reuse SSL +session-IDs, there seem to be broken SSL implementations in the wild that may +require you to disable this in order for you to succeed. (Added in 7.16.0) .IP CURLOPT_KRB4LEVEL Pass a char * as parameter. Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or -- cgit v1.2.1 From c2404f77e9eb34b4bb49767d9239dc1f45b76c00 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Sep 2006 11:09:54 +0000 Subject: Extended the explanation for CURLM_CALL_MULTI_PERFORM somewhat. --- docs/libcurl/curl_multi_perform.3 | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 51d3a3c34..9baa77c6c 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -30,11 +30,15 @@ If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you should call \fIcurl_multi_perform\fP again, before you select() on more 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". +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 +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 -function returns OK. +function returns \fICURLM_OK\fP. .SH "TYPICAL USAGE" Most applications will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's file descriptors, then it'll wait for action on them using \fBselect(3)\fP and @@ -42,4 +46,5 @@ as soon as one or more of them are ready, \fIcurl_multi_perform(3)\fP gets called. .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " -.BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" +.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " +.BR libcurl-errors "(3)" -- cgit v1.2.1 From d569693f24886d1d76884ae26da8f644114e9882 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 26 Sep 2006 10:38:24 +0000 Subject: Armel Asselin's fix for the RESUME_FROM docu --- docs/libcurl/curl_easy_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5e11cf38c..ad0582746 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -973,7 +973,9 @@ techniques). Pass a NULL to this option to disable the use of ranges. .IP CURLOPT_RESUME_FROM Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. Set this option to 0 to make the transfer -start from the beginning (effectively disabling resume). +start from the beginning (effectively disabling resume). For FTP, set this +option to -1 to make the transfer start from the end of the target file +(useful to continue an interrupted upload). .IP CURLOPT_RESUME_FROM_LARGE Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) -- cgit v1.2.1 From b9f8a4a477a74781fddc28ba2fe9d0713de0acf9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 27 Sep 2006 21:15:36 +0000 Subject: added more explanations --- docs/libcurl/curl_multi_info_read.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 304be87b5..5bd934a7c 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -37,6 +37,12 @@ present in that struct and can thus be used in subsequent regular CURLcode result; /* return code for transfer */ } data; }; + +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. .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 -- cgit v1.2.1 From 5e0d9aea322ba3abfc05c937f91b5751768f2310 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 30 Sep 2006 20:31:11 +0000 Subject: Support for FTP third party transfers is now dropped --- docs/libcurl/curl_easy_setopt.3 | 12 ------------ 1 file changed, 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ad0582746..141323cf6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -917,18 +917,6 @@ 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" .RE -.IP CURLOPT_SOURCE_URL -When set, it enables a FTP third party transfer, using the set URL as source, -while \fICURLOPT_URL\fP is the target. -.IP CURLOPT_SOURCE_USERPWD -Set "username:password" to use for the source connection when doing FTP third -party transfers. -.IP CURLOPT_SOURCE_QUOTE -Exactly like \fICURLOPT_QUOTE\fP, but for the source host. -.IP CURLOPT_SOURCE_PREQUOTE -Exactly like \fICURLOPT_PREQUOTE\fP, but for the source host. -.IP CURLOPT_SOURCE_POSTQUOTE -Exactly like \fICURLOPT_POSTQUOTE\fP, but for the source host. .IP CURLOPT_FTP_ACCOUNT Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, -- cgit v1.2.1 From 77db81d661435a0b026ec6b16c35bd398ee1056e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 8 Oct 2006 21:41:22 +0000 Subject: clarified more --- docs/libcurl/curl_multi_info_read.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 5bd934a7c..018310ea8 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -20,6 +20,11 @@ NULL is returned as a signal that there is no more to get at this point. The integer pointed to with \fImsgs_in_queue\fP will contain the number of remaining messages after this function was called. +When you fetch a message using this function, it is removed from the internal +queue so calling this function again will not return the same message +again. It will instead return new messages at each new invoke until the queue +is emptied. + The data the returned pointer points to will not survive calling \fIcurl_multi_cleanup(3)\fP or \fIcurl_multi_remove_handle(3)\fP. -- cgit v1.2.1 From b61c06384ab88baf4b3231e84386c4a70126d888 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 12 Oct 2006 08:36:47 +0000 Subject: Jeff Pohlmeyer has been working with the hiperfifo.c example source code, and while doing so it became apparent that the current timeout system for the socket API really was a bit awkward since it become quite some work to be sure we have the correct timeout set. Jeff then provided the new CURLMOPT_TIMERFUNCTION that is yet another callback the app can set to get to know when the general timeout time changes and thus for an application like hiperfifo.c it makes everything a lot easier and nicer. There's a CURLMOPT_TIMERDATA option too of course in good old libcurl tradition. --- docs/libcurl/curl_multi_setopt.3 | 45 +++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 14 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 5279055ce..5ba81b952 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_setopt 3 "8 Jan 2006" "libcurl 7.16.0" "libcurl Manual" +.TH curl_multi_setopt 3 "10 Oct 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_setopt \- set options for a curl multi handle .SH SYNOPSIS @@ -9,7 +9,7 @@ curl_multi_setopt \- set options for a curl multi handle CURLMcode curl_multi_setopt(CURLM * multi_handle, CURLMoption option, param); .SH DESCRIPTION curl_multi_setopt() is used to tell a libcurl multi handle how to behave. By -using the appropriate options to \fIcurl_multi_setopt\fP, you can change +using the appropriate options to \fIcurl_multi_setopt(3)\fP, you can change libcurl's behaviour when using that multi handle. All options are set with the \fIoption\fP followed by the parameter \fIparam\fP. That parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a @@ -19,19 +19,20 @@ You can only set one option in each function call. .SH OPTIONS .IP CURLMOPT_SOCKETFUNCTION -Pass a pointer to a function matching the curl_socket_callback prototype. The -\fIcurl_multi_socket(3)\fP functions inform the application 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 is NULL, no callback will -be called. Set the callback's \fBuserp\fP argument with -\fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more callback -details. +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 +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 +is NULL, no callback will be called. Set the callback's \fBuserp\fP argument +with \fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more +callback details. .IP CURLMOPT_SOCKETDATA -Pass a pointer to whatever you want passed to the curl_socket_callback's forth -argument, the userp pointer. This is not used by libcurl but only passed-thru -as-is. Set the callback pointer with \fICURLMOPT_SOCKETFUNCTION\fP. +Pass a pointer to whatever you want passed to the \fBcurl_socket_callback\fP's +forth argument, the userp pointer. This is not used by libcurl but only +passed-thru as-is. Set the callback pointer with +\fICURLMOPT_SOCKETFUNCTION\fP. .IP CURLMOPT_PIPELINING 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 @@ -39,6 +40,22 @@ 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 7.16.0) +.IP CURLMOPT_TIMERFUNCTION +Pass a pointer to a function matching the \fBcurl_multi_timer_callback\fP +prototype. This function will then be called when the timeout value +changes. The timeout value is at what latest time the application should call +one of the \&"performing" functions of the multi interface +(\fIcurl_multi_socket(3)\fP, \fIcurl_multi_socket_all(3)\fP and +\fIcurl_multi_perform(3)\fP) - to allow libcurl to keep timeouts and retries +etc to work. Libcurl attempts to limit calling this only when the fixed future +timeout time actually change. See also \fICURLMOPT_TIMERDATA\fP. This callback +can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP. (Added +in 7.16.0) +.IP CURLMOPT_TIMERDATA +Pass a pointer to whatever you want passed to the +\fBcurl_multi_timer_callback\fP's third argument, the userp pointer. This is +not used by libcurl but only passed-thru as-is. Set the callback pointer with +\fICURLMOPT_TIMERFUNCTION\fP. (Added in 7.16.0) .SH RETURNS The standard CURLMcode for multi interface error codes. Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl -- cgit v1.2.1 From ab60a124654dc0326d97271ebd30bb0984f78d8b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 12 Oct 2006 14:30:47 +0000 Subject: Starting now, adding an easy handle to a multi stack that was already added to a multi stack will cause CURLM_BAD_EASY_HANDLE to get returned. --- docs/libcurl/libcurl-errors.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index baa9bc5fd..1d6936002 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -219,7 +219,9 @@ Things are fine. .IP "CURLM_BAD_HANDLE (1)" The passed-in handle is not a valid CURLM handle. .IP "CURLM_BAD_EASY_HANDLE (2)" -An easy handle was not good/valid. +An easy handle was not good/valid. It could mean that it isn't an easy handle +at all, or possibly that the handle already is in used by this or another +multi handle. .IP "CURLM_OUT_OF_MEMORY (3)" You are doomed. .IP "CURLM_INTERNAL_ERROR (4)" -- cgit v1.2.1 From 95c3fa836b50f1b83bdc325c108cf220673c99e4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 12 Oct 2006 14:35:20 +0000 Subject: clarify more --- docs/libcurl/curl_easy_cleanup.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index 84c0a6d1e..2eda26e92 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_easy_cleanup 3 "13 Nov 2002" "libcurl 7.7" "libcurl Manual" +.TH curl_easy_cleanup 3 "12 Oct 2006" "libcurl 7.7" "libcurl Manual" .SH NAME curl_easy_cleanup - End a libcurl easy session .SH SYNOPSIS @@ -21,6 +21,9 @@ more files. When you've called this, you can safely remove all the strings you've previously told libcurl to use, as it won't use them anymore now. + +Any uses of the \fBhandle\fP after this function has been called are +illegal. This kills the handle and all memory associated with it! .SH RETURN VALUE None .SH "SEE ALSO" -- cgit v1.2.1 From 4e717cdb300adeff3b259b3619b29a944c2960a8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 21 Oct 2006 11:32:05 +0000 Subject: Armel Asselin separated CA cert verification problems from problems with reading the (local) CA cert file to let users easier pinpoint the actual problem. CURLE_SSL_CACERT_BADFILE (77) is the new libcurl error code. --- docs/libcurl/libcurl-errors.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 1d6936002..062bf83de 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -174,7 +174,7 @@ problem with the local client certificate .IP "CURLE_SSL_CIPHER (59)" couldn't use specified cipher .IP "CURLE_SSL_CACERT (60)" -problem with the CA cert (path? access rights?) +peer certificate cannot be authenticated with known CA certificates .IP "CURLE_BAD_CONTENT_ENCODING (61)" Unrecognized transfer encoding .IP "CURLE_LDAP_INVALID_URL (62)" @@ -208,6 +208,8 @@ No such TFTP user Character conversion failed .IP "CURLE_CONV_REQD (76)" Caller must register conversion callbacks +.IP "CURLE_SSL_CACERT_BADFILE (77)" +Problem with reading the SSL CA cert (path? access rights?) .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. Also consider \fIcurl_multi_strerror(3)\fP. -- cgit v1.2.1 From cde5e35d9b046b224c64936c432d67c9de8bcc9e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 Oct 2006 20:40:14 +0000 Subject: Fixed CURLOPT_FAILONERROR to return CURLE_HTTP_RETURNED_ERROR even for the case when 401 or 407 are returned, *IF* no auth credentials have been given. The CURLOPT_FAILONERROR option is not possible to make fool-proof for 401 and 407 cases when auth credentials is given, but we've now covered this somewhat more. 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 POST/PUT and a 401 or 407 is received immediately afterwards. Added test 281 to verify this change. --- docs/libcurl/curl_easy_setopt.3 | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 141323cf6..40ec28826 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -344,6 +344,14 @@ when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data. A non-zero parameter tells the library to fail silently if the HTTP code returned is equal to or larger than 400. The default action would be to return the page normally, ignoring that code. + +This method is not fail-safe and there are occasions where non-succesful +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 +POST/PUT and a 401 or 407 is received immediately afterwards. .SH NETWORK OPTIONS .IP CURLOPT_URL The actual URL to deal with. The parameter should be a char * to a zero -- cgit v1.2.1 From 2147284cad624325f5b0034c2f394db62086d9e6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 2 Nov 2006 21:56:40 +0000 Subject: James Housley brought support for SCP transfers --- docs/libcurl/curl_version_info.3 | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index a9fd55d59..21f72aebe 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_version_info 3 "19 Apr 2006" "libcurl 7.15.4" "libcurl Manual" +.TH curl_version_info 3 "2 Nov 2006" "libcurl 7.16.1" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -66,6 +66,11 @@ typedef struct { /* when 'age' is 2 or higher, the member below also exists: */ const char *libidn; /* human readable string */ + /* when 'age' is 3 or higher, the members below also exist: */ + int iconv_ver_num; /* '_libiconv_version' if iconv support enabled */ + + const char *libssh_version; /* human readable string */ + } curl_version_info_data; .fi -- cgit v1.2.1 From 675f6a8901cc1668af30d6c5e6b428eeb1984498 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 2 Nov 2006 22:10:18 +0000 Subject: mention the new options --- docs/libcurl/curl_easy_setopt.3 | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 40ec28826..8c172ca90 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "19 Apr 2006" "libcurl 7.15.4" "libcurl Manual" +.TH curl_easy_setopt 3 "2 Nov 2006" "libcurl 7.16.1" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -1312,6 +1312,17 @@ krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or \&'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos4. The kerberos support only works for FTP. +.SH SSH OPTIONS +.IP CURLOPT_SSH_AUTH_TYPES +Pass a long set to a bitmask consisting of one or more of +CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, +CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. +.IP CURLOPT_SSH_PUBLIC_KEYFILE +Pass a char * pointing to a file name for your public key. If not used, +libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP. +.IP CURLOPT_SSH_PRIVATE_KEYFILE +Pass a char * pointing to a file name for your private key. If not used, +libcurl defaults to using \fB~/.ssh/id_dsa\fP. .SH OTHER OPTIONS .IP CURLOPT_PRIVATE Pass a char * as parameter, pointing to data that should be associated with -- cgit v1.2.1 From ae76ebe2d1202a09b009c9294f63c2a1bc228bd8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Dec 2006 16:04:01 +0000 Subject: Sh Diao reported that CURLOPT_CLOSEPOLICY doesn't work, and indeed, there is no code present in the library that receives the option. Since it was not possible to use, we know that no current users exist and thus we simply removed it from the docs and made the code always use the default path of the code. --- docs/libcurl/curl_easy_setopt.3 | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8c172ca90..ca4c8af65 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1092,23 +1092,14 @@ value unless you are perfectly aware of how this work and changes libcurl's behaviour. This concerns connection using any of the protocols that support persistent connections. -When reaching the maximum limit, curl uses the \fICURLOPT_CLOSEPOLICY\fP to -figure out which of the existing connections to close to prevent the number of -open connections to increase. +When reaching the maximum limit, curl closes the oldest one in the cache to +prevent the number of open connections to increase. If you already have performed transfers with this curl handle, setting a smaller MAXCONNECTS than before may cause open connections to get closed unnecessarily. .IP CURLOPT_CLOSEPOLICY -Pass a long. This option sets what policy libcurl should use when the -connection cache is filled and one of the open connections has to be closed to -make room for a new connection. This must be one of the CURLCLOSEPOLICY_* -defines. Use \fICURLCLOSEPOLICY_LEAST_RECENTLY_USED\fP to make libcurl close -the connection that was least recently used, that connection is also least -likely to be capable of re-use. Use \fICURLCLOSEPOLICY_OLDEST\fP to make -libcurl close the oldest connection, the one that was created first among the -ones in the connection cache. The other close policies are not support -yet. +(Obsolete) This option does nothing. .IP CURLOPT_FRESH_CONNECT Pass a long. Set to non-zero to make the next transfer use a new (fresh) connection by force. If the connection cache is full before this connection, -- cgit v1.2.1 From 439b84c78222706c54a878cbc4238a2580a228b1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Dec 2006 09:36:03 +0000 Subject: CURLOPT_CAPATH is OpenSSL-only --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ca4c8af65..4893c0e24 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1237,14 +1237,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. .IP CURLOPT_CAPATH -Pass a char * to a zero terminated string naming a directory holding -multiple CA certificates to verify the peer with. The certificate -directory must be prepared using the openssl c_rehash utility. This -makes sense only when used in combination with the -\fICURLOPT_SSL_VERIFYPEER\fP option. If \fICURLOPT_SSL_VERIFYPEER\fP -is zero, \fICURLOPT_CAPATH\fP need not even indicate an accessible -path. The \fICURLOPT_CAPATH\fP function apparently does not work in -Windows due to some limitation in openssl. (Added in 7.9.8) +Pass a char * to a zero terminated string naming a directory holding multiple +CA certificates to verify the peer with. The certificate directory must be +prepared using the openssl c_rehash utility. This makes sense only when used +in combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If +\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAPATH\fP need not even +indicate an accessible path. The \fICURLOPT_CAPATH\fP function apparently +does not work in Windows due to some limitation in openssl. This option is +OpenSSL-specific and does nothing if libcurl is built to use GnuTLS. .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, -- cgit v1.2.1 From 8500397cf170b19458c413a8cf0a9f11a738e558 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 31 Dec 2006 13:53:19 +0000 Subject: curl_easy_cleanup kills this memory too --- docs/libcurl/curl_multi_info_read.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 018310ea8..414a2a610 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -26,7 +26,8 @@ again. It will instead return new messages at each new invoke until the queue is emptied. The data the returned pointer points to will not survive calling -\fIcurl_multi_cleanup(3)\fP or \fIcurl_multi_remove_handle(3)\fP. +\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. If more involved information is wanted, the particular "easy handle" in -- cgit v1.2.1 From 4750e6f3c5fd42e19998242ddb63d7d5506b9fd9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 5 Jan 2007 23:11:14 +0000 Subject: - Linus Nielsen Feltzing introduced the --ftp-ssl-ccc command line option to curl that uses the new CURLOPT_FTP_SSL_CCC option in libcurl. If enabled, it will make libcurl shutdown SSL/TLS after the authentication is done on a FTP-SSL operation. --- docs/libcurl/curl_easy_setopt.3 | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4893c0e24..55f4353bc 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -925,6 +925,12 @@ 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" .RE +.IP CURLOPT_FTP_SSL_CCC +Pass a long that is set to 0 to disable and 1 to enable. If enabled, this +option makes libcurl use CCC (Clear Command Channel). It shuts down the +SSL/TLS layer after authenticating. The rest of the control channel +communication will be unencrypted. This allows NAT routers to follow the FTP +transaction. (Added in 7.16.1) .IP CURLOPT_FTP_ACCOUNT Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, -- cgit v1.2.1 From 75899741b91730b6f48ca80aedbe5fcf31f69ac2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Jan 2007 18:58:16 +0000 Subject: corrected example --- docs/libcurl/curl_slist_append.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 index 8a61366f1..a20d2f9a4 100644 --- a/docs/libcurl/curl_slist_append.3 +++ b/docs/libcurl/curl_slist_append.3 @@ -24,8 +24,9 @@ The list should be freed again (after usage) with A null pointer is returned if anything went wrong, otherwise the new list pointer is returned. .SH EXAMPLE +.nf CURL handle; - curl_slist *slist=NULL; + struct curl_slist *slist=NULL; slist = curl_slist_append(slist, "pragma:"); curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); @@ -33,5 +34,6 @@ pointer is returned. curl_easy_perform(handle); curl_slist_free_all(slist); /* free the list again */ +.fi .SH "SEE ALSO" .BR curl_slist_free_all "(3), " -- cgit v1.2.1 From 0b4bdcf18f8b438303d591a38923da64fb64c2c2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 17 Jan 2007 08:57:20 +0000 Subject: clarify the INFILESIZE option(s) --- docs/libcurl/curl_easy_setopt.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 55f4353bc..08e7405e2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1014,10 +1014,16 @@ to POST with \fICURLOPT_POST\fP etc. When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. + +Note that this option does not limit how much data libcurl will actually send, +as that is controlled entirely by what the read callback returns. .IP CURLOPT_INFILESIZE_LARGE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a curl_off_t. (Added in 7.11.0) + +Note that this option does not limit how much data libcurl will actually send, +as that is controlled entirely by what the read callback returns. .IP CURLOPT_UPLOAD A non-zero parameter tells the library to prepare for an upload. The \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP or -- cgit v1.2.1 From 8f87c15bdac63b1128a56c89a85fd3d03828b8c6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 3 Feb 2007 21:35:11 +0000 Subject: some additional info --- docs/libcurl/libcurl-multi.3 | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index b6d95b1d7..a3e579cbb 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-multi 3 "13 Oct 2001" "libcurl 7.10.1" "libcurl multi interface" +.TH libcurl-multi 3 "3 Feb 2007" "libcurl 7.16.0" "libcurl multi interface" .SH NAME libcurl-multi \- how to use the multi interface .SH DESCRIPTION @@ -112,3 +112,22 @@ to clean them up properly. If you want to re-use an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it 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 +for applications using large numbers of simultaneous connections. + +\fIcurl_multi_socket(3)\fP (and \fIcurl_multi_socket_all(3)\fP) is then used +instead of \fIcurl_multi_perform(3)\fP. +.SH "BLOCKING" +A few areas in the code are still using blocking code, even when used from the +multi interface. While we certainly want and intend for these to get fixed in +the future, you should be aware of the following current restrictions: + + - Name resolves on non-windows unless c-ares is used + - GnuTLS SSL connections + - Active FTP connections + - HTTP proxy CONNECT operations + - SCP and SFTP connections + - SFTP transfers -- cgit v1.2.1 From 91386937ff120d11f7bf24dc487f00751362a61c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Feb 2007 22:51:32 +0000 Subject: - Michael Wallner provided a patch that adds support for CURLOPT_TIMEOUT_MS and CURLOPT_CONNECTTIMEOUT_MS that, as their names should hint, do the timeouts with millisecond resolution instead. The only restriction to that is the alarm() (sometimes) used to abort name resolves as that uses full seconds. I fixed the FTP response timeout part of the patch. Internally we now count and keep the timeouts in milliseconds but it also means we multiply set timeouts with 1000. The effect of this is that no timeout can be set to more than 2^31 milliseconds (on 32 bit systems), which equals 24.86 days. We probably couldn't before either since the code did *1000 on the timeout values on several places already. --- docs/libcurl/curl_easy_setopt.3 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 08e7405e2..23d012de9 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "2 Nov 2006" "libcurl 7.16.1" "libcurl Manual" +.TH curl_easy_setopt 3 "5 Feb 2007" "libcurl 7.16.2" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -1078,6 +1078,10 @@ SIGALRM to enable time-outing system calls. In unix-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL\fP is set. +.IP CURLOPT_TIMEOUT_MS +Like \fICURLOPT_TIMEOUT\fP but takes number of milliseconds instead. If +libcurl is built to use the standard system name resolver, that part will +still use full-second resolution for timeouts. (Added in 7.16.2) .IP CURLOPT_LOW_SPEED_LIMIT Pass a long as parameter. It contains the transfer speed in bytes per second that the transfer should be below during \fICURLOPT_LOW_SPEED_TIME\fP seconds @@ -1135,6 +1139,10 @@ timeouts). See also the \fICURLOPT_TIMEOUT\fP option. In unix-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL\fP is set. +.IP CURLOPT_CONNECTTIMEOUT_MS +Like \fICURLOPT_CONNECTTIMEOUT\fP but takes number of milliseconds instead. If +libcurl is built to use the standard system name resolver, that part will +still use full-second resolution for timeouts. (Added in 7.16.2) .IP CURLOPT_IPRESOLVE Allows an application to select what kind of IP addresses to use when resolving host names. This is only interesting when using host names that -- cgit v1.2.1 From 61f19c6ca3b8fa75eeef5b32f9d7be64e1965f19 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 10 Feb 2007 12:07:46 +0000 Subject: file:// transfers are blocking --- docs/libcurl/libcurl-multi.3 | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index a3e579cbb..c9ef3c056 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -131,3 +131,4 @@ the future, you should be aware of the following current restrictions: - HTTP proxy CONNECT operations - SCP and SFTP connections - SFTP transfers + - file:// transfers -- cgit v1.2.1 From 28b932fb4ef14b8b9ebda6823c98fbedad6be4b2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 Feb 2007 21:13:47 +0000 Subject: - Shmulik Regev fixed so that the final CRLF of HTTP response headers are sent to the debug callback. - Shmulik Regev added CURLOPT_HTTP_CONTENT_DECODING and CURLOPT_HTTP_TRANSFER_DECODING that if set to zero will disable libcurl's internal decoding of content or transfer encoded content. This may be preferable in cases where you use libcurl for proxy purposes or similar. The command line tool got a --raw option to disable both at once. --- docs/libcurl/curl_easy_setopt.3 | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 23d012de9..0c55e1400 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "5 Feb 2007" "libcurl 7.16.2" "libcurl Manual" +.TH curl_easy_setopt 3 "12 Feb 2007" "libcurl 7.16.2" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -815,6 +815,16 @@ servers) which will report incorrect content length for files over 2 gigabytes. If this option is used, curl will not be able to accurately report progress, and will simply stop the download when the server ends the connection. (added in 7.14.1) +.IP CURLOPT_HTTP_CONTENT_DECODING +Pass a long to tell libcurl how to act on content decoding. If set to zero, +content decoding will be disabled. If set to 1 it is enabled. Note however +that libcurl has no default content decoding but requires you to use +\fICURLOPT_ENCODING\fP for that. (added in 7.16.2) +.IP CURLOPT_HTTP_TRANSFER_DECODING +Pass a long to tell libcurl how to act on transfer decoding. If set to zero, +transfer decoding will be disabled, if set to 1 it is enabled +(default). libcurl does chunked transfer decoding by default unless this +option is set to zero. (added in 7.16.2) .RE .SH FTP OPTIONS .IP CURLOPT_FTPPORT -- cgit v1.2.1 From 7f70dbcad58eb7183d129860192d6968dd7063a1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 Feb 2007 22:32:37 +0000 Subject: Rob Crittenden added support for NSS (Network Security Service) for the SSL/TLS layer. http://www.mozilla.org/projects/security/pki/nss/ --- docs/libcurl/curl_easy_setopt.3 | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0c55e1400..66ca11f34 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1178,6 +1178,9 @@ transfers. (Added in 7.15.2) Pass a pointer to a zero terminated string as parameter. The string should be the file name of your certificate. The default format is "PEM" and can be changed with \fICURLOPT_SSLCERTTYPE\fP. + +With NSS this is the nickname of the certificate you wish to authenticate +with. .IP CURLOPT_SSLCERTTYPE Pass a pointer to a zero terminated string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER". (Added @@ -1222,8 +1225,8 @@ Pass a long as parameter to control what version of SSL/TLS to attempt to use. The available options are: .RS .IP CURL_SSLVERSION_DEFAULT -The default action. When libcurl built with OpenSSL, this will attempt to -figure out the remote SSL protocol version. Unfortunately there are a lot of +The default action. When libcurl built with OpenSSL or NSS, this will attempt +to figure out the remote SSL protocol version. Unfortunately there are a lot of ancient and broken servers in use which cannot handle this technique and will fail to connect. When libcurl is built with GnuTLS, this will mean SSLv3. .IP CURL_SSLVERSION_TLSv1 @@ -1266,6 +1269,9 @@ 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 +database resides in. .IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate directory must be @@ -1315,12 +1321,23 @@ 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, it consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, \!, \- and \+ can -be used as operators. Valid examples of cipher lists include 'RC4-SHA', +be used as operators. + +For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', \'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you 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', +\'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. + +You'll find more details about the NSS cipher lists on this URL: +\fIhttp://directory.fedora.redhat.com/docs/mod_nss.html#Directives\fP + .IP CURLOPT_SSL_SESSIONID_CACHE Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set this to 1 to enable it. By default all transfers are done using the -- cgit v1.2.1 From 1297c54b2627db727184b4bec5ea3d696d8a1c10 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 19 Feb 2007 12:37:04 +0000 Subject: Ian Turner fixed the libcurl.m4 macro's support for --with-libcurl. AC_PATH_PROG was not used properly. --- docs/libcurl/libcurl.m4 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index a9bfa2e23..f54a5f2d1 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -71,7 +71,8 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], if test -d "$_libcurl_with" ; then LIBCURL_CPPFLAGS="-I$withval/include" _libcurl_ldflags="-L$withval/lib" - AC_PATH_PROG([_libcurl_config],["$withval/bin/curl-config"]) + AC_PATH_PROG([_libcurl_config],[curl-config],["$withval/bin"], + ["$withval/bin"]) else AC_PATH_PROG([_libcurl_config],[curl-config]) fi -- cgit v1.2.1 From 2f5e99ca02b6716fdac59c299ab7738a2077743d Mon Sep 17 00:00:00 2001 From: Linus Nielsen Feltzing Date: Tue, 20 Feb 2007 22:02:11 +0000 Subject: New FTP CCC functionality - adds passive and active mode to accomodate for different server behaviour --- docs/libcurl/curl_easy_setopt.3 | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 66ca11f34..9e32f13aa 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -936,11 +936,20 @@ Try "AUTH SSL" first, and only if that fails try "AUTH TLS" Try "AUTH TLS" first, and only if that fails try "AUTH SSL" .RE .IP CURLOPT_FTP_SSL_CCC -Pass a long that is set to 0 to disable and 1 to enable. If enabled, this -option makes libcurl use CCC (Clear Command Channel). It shuts down the -SSL/TLS layer after authenticating. The rest of the control channel -communication will be unencrypted. This allows NAT routers to follow the FTP -transaction. (Added in 7.16.1) +If enabled, this option makes libcurl use CCC (Clear Command Channel). It +shuts down the SSL/TLS layer after authenticating. The rest of the +control channel communication will be unencrypted. This allows NAT routers +to follow the FTP transaction. Pass a long using one of the values below. +(Added in 7.16.1) +.RS +.IP CURLFTPSSL_CCC_NONE +Don't attempt to use CCC. +.IP CURLFTPSSL_CCC_PASSIVE +Do not initiate the shutdown, but wait for the server to do it. Do not send +a reply. +.IP CURLFTPSSL_CCC_ACTIVE +Initiate the shutdown and wait for a reply. +.RE .IP CURLOPT_FTP_ACCOUNT Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, -- cgit v1.2.1 From 8b5295d00338b56cafec2a8fb142e60851a6eea1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 22 Feb 2007 21:21:05 +0000 Subject: setting CURLOPT_PROXY to "" explicitly disables the use of a proxy (even if there is an environment variable set) --- docs/libcurl/curl_easy_setopt.3 | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9e32f13aa..a5aa25b8c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "12 Feb 2007" "libcurl 7.16.2" "libcurl Manual" +.TH curl_easy_setopt 3 "22 Feb 2007" "libcurl 7.16.2" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -389,10 +389,12 @@ 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 does however override any possibly set environment variables. -Starting with 7.14.1, the proxy host string given in environment variables can -be specified the exact same way as the proxy can be set with -\fICURLOPT_PROXY\fP, include protocol prefix (http://) and embedded user + -password. +Setting the proxy string to "" (an empty string) will explicitly disable the +use of a proxy, even if there is an environment variable set for it. + +Since 7.14.1, the proxy host string given in environment variables can be +specified the exact same way as the proxy can be set with \fICURLOPT_PROXY\fP, +include protocol prefix (http://) and embedded user + password. .IP CURLOPT_PROXYPORT Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. -- cgit v1.2.1 From fa31335926f1a543ccb88471dc57e41110f09ebb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 27 Feb 2007 12:44:14 +0000 Subject: Somewhat updated, changes include: I tried to be more agnostic about the specific SSL library that might be used, and I cut out the closepolicy stuff that we no longer support --- docs/libcurl/libcurl-tutorial.3 | 121 ++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 61 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 8f1625150..070aa5465 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-tutorial 3 "9 May 2005" "libcurl" "libcurl programming" +.TH libcurl-tutorial 3 "27 Feb 2007" "libcurl" "libcurl programming" .SH NAME libcurl-tutorial \- libcurl programming tutorial .SH "Objective" @@ -64,10 +64,10 @@ $ curl-config --libs .IP "SSL or Not" libcurl can be built and customized in many ways. One of the things that varies from different libraries and builds is the support for SSL-based -transfers, like HTTPS and FTPS. If OpenSSL was detected properly at -build-time, libcurl will be built with SSL support. To figure out if an -installed libcurl has been built with SSL support enabled, use 'curl-config' -like this: +transfers, like HTTPS and FTPS. If a supported SSL library was detected +properly at build-time, libcurl will be built with SSL support. To figure out +if an installed libcurl has been built with SSL support enabled, use +\&'curl-config' like this: $ curl-config --feature @@ -111,11 +111,10 @@ sockets properly. You should only do this once for each application, so if your program already does this or of another library in use does it, you 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 OpenSSL -properly for this application. This is only needed to do once for each -application so if your program or another library already does this, this -bit should not be needed. +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 +program or another library already does this, this bit should not be needed. .RE libcurl has a default protection mechanism that detects if @@ -256,18 +255,27 @@ handlers. Signals are used timeouting name resolves (during DNS lookup) - 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 OpenSSL/GnuTLS multi-threaded and those libs have their -own requirements on this issue. Basically, you need to provide one or two -functions to allow it to function properly. For all details, see this: +then of course using the underlying SSL library multi-threaded and those libs +might have their own requirements on this issue. Basically, you need to +provide one or two functions to allow it to function properly. For all +details, see this: OpenSSL - http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION + http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION GnuTLS http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html +NSS + + is claimed to be thread-safe already without anything required + +yassl + + Required actions unknown + When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE for all handles. Everything will or might work fine except that timeouts are not honored during the DNS lookup - which you can work around by building @@ -614,22 +622,26 @@ What "proxy" means according to Merriam-Webster: "a person authorized to act for another" but also "the agency, function, or office of a deputy who acts as a substitute for another". -Proxies are exceedingly common these days. Companies often only offer -Internet access to employees through their HTTP proxies. Network clients or -user-agents ask the proxy for documents, the proxy does the actual request -and then it returns them. +Proxies are exceedingly common these days. Companies often only offer Internet +access to employees through their proxies. Network clients or user-agents ask +the proxy for documents, the proxy does the actual request and then it returns +them. + +libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl +will ask the proxy for it instead of trying to connect to the actual host +identified in the URL. -libcurl has full support for HTTP proxies, so when a given URL is wanted, -libcurl will ask the proxy for it instead of trying to connect to the actual -host identified in the URL. +If you're using a SOCKS proxy, you may find that libcurl doesn't quite support +all operations through it. -The fact that the proxy is a HTTP proxy puts certain 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 can't invoke your own -custom FTP commands or even proper FTP directory listings. +For HTTP proxies: the fact that the proxy is a HTTP proxy puts certain +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 +can't invoke your own custom FTP commands or even proper FTP directory +listings. .IP "Proxy Options" @@ -645,6 +657,11 @@ pass that information similar to this: If you want to, you can specify the host name only in the CURLOPT_PROXY option, and set the port number separately with CURLOPT_PROXYPORT. +Tell libcurl what kind of proxy it is with CURLOPT_PROXYTYPE (if not, it will +default to assume a HTTP proxy): + + curl_easy_setopt(easyhandle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); + .IP "Environment Variables" libcurl automatically checks and uses a set of environment variables to @@ -669,6 +686,8 @@ for any URL in case the protocol specific variable wasn't set, and variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all hosts. +To explicitly disable libcurl's checking for and using the proxy environment +variables, set the proxy name to "" - an empty string - with CURLOPT_PROXY. .IP "SSL and Proxies" SSL is for secure point-to-point connections. This involves strong encryption @@ -768,26 +787,6 @@ with the CURLOPT_MAXCONNECTS option. Default is 5. It 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. -When the connection cache gets filled, libcurl must close an existing -connection in order to get room for the new one. To know which connection to -close, libcurl uses a "close policy" that you can affect with the -CURLOPT_CLOSEPOLICY option. There's only two polices implemented as of this -writing (libcurl 7.9.4) and they are: - -.RS -.IP CURLCLOSEPOLICY_LEAST_RECENTLY_USED -simply close the one that hasn't been used for the longest time. This is the -default behavior. -.IP CURLCLOSEPOLICY_OLDEST -closes the oldest connection, the one that was created the longest time ago. -.RE - -There are, or at least were, plans to support a close policy that would call -a user-specified callback to let the user be able to decide which connection -to dump when this is necessary and therefor is the CURLOPT_CLOSEFUNCTION an -existing option still today. Nothing ever uses this though and this will not -be used within the foreseeable future either. - To force your upcoming request to not use an already existing connection (it will even close one first if there happens to be one alive to the same host you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT @@ -797,7 +796,8 @@ CURLOPT_FORBID_REUSE to TRUE. .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. +automatically. It might be good for you to know and understand these ones. You +can replace or remove them by using the CURLOPT_HTTPHEADER option. .IP "Host" This header is required by HTTP 1.1 and even many 1.0 servers and should be @@ -811,10 +811,11 @@ fetch a fresh one. .IP "Accept" \&"*/*". -.IP "Expect:" -When doing multi-part formposts, libcurl will set this header to -\&"100-continue" to ask the server for an "OK" message before it proceeds with -sending the data part of the post. +.IP "Expect" +When doing POST requests, libcurl sets this header to \&"100-continue" to ask +the server for an "OK" message before it proceeds with sending the data part +of the post. If the POSTed data amount is deemed "small", libcurl will not use +this header. .SH "Customizing Operations" There is an ongoing development today where more and more protocols are built @@ -888,12 +889,10 @@ data size is unknown. .IP "HTTP Version" -There's only one aspect left in the HTTP requests that we haven't yet -mentioned how to modify: the version field. 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 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: +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 +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: curl_easy_setopt(easyhandle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0); @@ -1051,7 +1050,7 @@ The headers are passed to the callback function one by one, and you can depend on that fact. It makes it easier for you to add custom header parsers etc. -"Headers" for FTP transfers equal all the FTP server responses. They aren't +\&"Headers" for FTP transfers equal all the FTP server responses. They aren't actually true headers, but in this case we pretend they are! ;-) .SH "Post Transfer Information" -- cgit v1.2.1 From dbaf4f93615b0ad1f34b38ec9def0b30496658d7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 10 Mar 2007 12:11:21 +0000 Subject: - Bryan Henderson introduces two things: 1) the progress callback gets called more frequently (at times) 2) libcurl *might* call the callback when it receives a signal --- docs/libcurl/curl_easy_setopt.3 | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a5aa25b8c..e949f2109 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -67,8 +67,9 @@ A non-zero parameter tells the library to include the header in the body output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). .IP CURLOPT_NOPROGRESS -A non-zero parameter tells the library to shut off the built-in progress meter -completely. +A non-zero parameter tells the library not to call your progress callback +(see \fICURLOPT_PROGRESSFUNCTION\fP) +and to shut off the built-in progress meter completely. Future versions of libcurl is likely to not have any built-in progress meter at all. @@ -185,23 +186,45 @@ argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of -its internal equivalent with a frequent interval during operation (roughly +its internal equivalent frequently during operation (roughly once per second) no matter if data is being transfered or not. Unknown/unused argument values passed to the callback will be set to zero (like if you only -download data, the upload size will remain 0). Returning a non-zero value from -this callback will cause libcurl to abort the transfer and return -\fICURLE_ABORTED_BY_CALLBACK\fP. +download data, the upload size will remain 0). + +The callback serves two purposes: 1) updates you on the progress of +the transfer; 2) gives you an opportunity to abort the transfer. If +the callback returns a non-zero value, libcurl aborts the transfer and +returns \fICURLE_ABORTED_BY_CALLBACK\fP. + +libcurl calls the progress callback at least once a second, and +sometimes when the process receives and catches a signal. Ideally, it +would get called every time the process receives and catches a signal, +but in the current implementation, libcurl may fail to recognize a signal +during name resolution, during the wait for a TCP connection, and during +some tiny windows other times. + +If you want a signal to interrupt your call to libcurl, install a signal +handler for it. Have that signal handler set a flag indicating that the +signal was received. Set up a libcurl progress callback that checks that +flag and, if it is set, returns a nonzero return code. + +Two common kinds of signals you might want to allow to interrupt +libcurl are: 1) SIGINT, the signal that typically results from a user +typing control-C; 2) SIGALRM, a signal indicating a timeout. (libcurl +also has specific timeout facilities, but SIGALRM can be from a master +timeout established at a higher layer of your program). If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers. Usage of the \fBCURLOPT_PROGRESSFUNCTION\fP callback is not recommended when using the multi interface. -\fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually -get called. +This callback gets called only if you set \fICURLOPT_NOPROGRESS\fP to FALSE. + .IP CURLOPT_PROGRESSDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. + .IP CURLOPT_HEADERFUNCTION Function pointer that should match the following prototype: \fIsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This -- cgit v1.2.1 From c8cd13337efcd45e918fab824b226e4ae6338ea0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 11 Mar 2007 09:11:29 +0000 Subject: reverted the pselect patch => http://curl.haxx.se/mail/lib-2007-03/0100.html --- docs/libcurl/curl_easy_setopt.3 | 39 ++++++++------------------------------- 1 file changed, 8 insertions(+), 31 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e949f2109..a5aa25b8c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -67,9 +67,8 @@ A non-zero parameter tells the library to include the header in the body output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). .IP CURLOPT_NOPROGRESS -A non-zero parameter tells the library not to call your progress callback -(see \fICURLOPT_PROGRESSFUNCTION\fP) -and to shut off the built-in progress meter completely. +A non-zero parameter 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 at all. @@ -186,45 +185,23 @@ argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of -its internal equivalent frequently during operation (roughly +its internal equivalent with a frequent interval during operation (roughly once per second) no matter if data is being transfered or not. Unknown/unused argument values passed to the callback will be set to zero (like if you only -download data, the upload size will remain 0). - -The callback serves two purposes: 1) updates you on the progress of -the transfer; 2) gives you an opportunity to abort the transfer. If -the callback returns a non-zero value, libcurl aborts the transfer and -returns \fICURLE_ABORTED_BY_CALLBACK\fP. - -libcurl calls the progress callback at least once a second, and -sometimes when the process receives and catches a signal. Ideally, it -would get called every time the process receives and catches a signal, -but in the current implementation, libcurl may fail to recognize a signal -during name resolution, during the wait for a TCP connection, and during -some tiny windows other times. - -If you want a signal to interrupt your call to libcurl, install a signal -handler for it. Have that signal handler set a flag indicating that the -signal was received. Set up a libcurl progress callback that checks that -flag and, if it is set, returns a nonzero return code. - -Two common kinds of signals you might want to allow to interrupt -libcurl are: 1) SIGINT, the signal that typically results from a user -typing control-C; 2) SIGALRM, a signal indicating a timeout. (libcurl -also has specific timeout facilities, but SIGALRM can be from a master -timeout established at a higher layer of your program). +download data, the upload size will remain 0). Returning a non-zero value from +this callback will cause libcurl to abort the transfer and return +\fICURLE_ABORTED_BY_CALLBACK\fP. If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers. Usage of the \fBCURLOPT_PROGRESSFUNCTION\fP callback is not recommended when using the multi interface. -This callback gets called only if you set \fICURLOPT_NOPROGRESS\fP to FALSE. - +\fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually +get called. .IP CURLOPT_PROGRESSDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. - .IP CURLOPT_HEADERFUNCTION Function pointer that should match the following prototype: \fIsize_t function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This -- cgit v1.2.1 From d76a73404347d7c1112dded81ce9a1172ce07884 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 Mar 2007 13:20:39 +0000 Subject: RECV is for download --- docs/libcurl/curl_easy_setopt.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a5aa25b8c..ac26b7237 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1117,10 +1117,10 @@ average during the transfer, the transfer will pause to keep the average rate less than or equal to the parameter value. Defaults to unlimited speed. (Added in 7.15.5) .IP CURLOPT_MAX_RECV_SPEED_LARGE -Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative -average during the transfer, the transfer will pause to keep the average rate -less than or equal to the parameter value. Defaults to unlimited speed. (Added -in 7.15.5) +Pass a curl_off_t as parameter. If a download exceeds this speed on +cumulative average during the transfer, the transfer will pause to keep the +average rate less than or equal to the parameter value. Defaults to unlimited +speed. (Added in 7.15.5) .IP CURLOPT_MAXCONNECTS 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 -- cgit v1.2.1 From 0043e870145d167003931cda2fd90b5e13b0b7f8 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 23 Mar 2007 17:59:40 +0000 Subject: Added --pubkey option to curl and made --key also work for SCP/SFTP, plus made --pass work on an SSH private key as well. --- docs/libcurl/curl_easy_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ac26b7237..970600859 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1217,7 +1217,8 @@ engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE\fP. \&"DER" format key file currently does not work because of a bug in OpenSSL. .IP CURLOPT_SSLKEYPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as -the password required to use the \fICURLOPT_SSLKEY\fP private key. +the password required to use the \fICURLOPT_SSLKEY\fP or +\fICURLOPT_SSH_PRIVATE_KEYFILE\fP private key. .IP CURLOPT_SSLENGINE Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private @@ -1372,6 +1373,7 @@ libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP. .IP CURLOPT_SSH_PRIVATE_KEYFILE Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to using \fB~/.ssh/id_dsa\fP. +If the file is password-protected, set the password with \fICURLOPT_SSLKEYPASSWD\fP. .SH OTHER OPTIONS .IP CURLOPT_PRIVATE Pass a char * as parameter, pointing to data that should be associated with -- cgit v1.2.1 From 453e9b0dcec46262e163c6cd24094a900d1cdb46 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 31 Mar 2007 20:19:02 +0000 Subject: add units to a few info --- docs/libcurl/curl_easy_getinfo.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 31f14fe29..fbb182ebf 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -98,13 +98,13 @@ downloaded. The amount is only for the latest transfer and will be reset again for each new transfer. .IP CURLINFO_SPEED_DOWNLOAD Pass a pointer to a double to receive the average download speed that curl -measured for the complete download. +measured for the complete download. Measured in bytes/second. .IP CURLINFO_SPEED_UPLOAD Pass a pointer to a double to receive the average upload speed that curl -measured for the complete upload. +measured for the complete upload. Measured in bytes/second. .IP CURLINFO_HEADER_SIZE Pass a pointer to a long to receive the total size of all the headers -received. +received. Measured in number of bytes. .IP CURLINFO_REQUEST_SIZE Pass a pointer to a long to receive the total size of the issued requests. This is so far only for HTTP requests. Note that this may be more -- cgit v1.2.1 From 76627b322e369c209c60863b9e1f05e3ce02953d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 16 Apr 2007 16:34:08 +0000 Subject: - Robert Iakobashvil added curl_multi_socket_action() to libcurl, which is a function that deprecates the curl_multi_socket() function. Using the new function the application tell libcurl what action that was found in the socket that it passes in. This gives a significant performance boost as it allows libcurl to avoid a call to poll()/select() for every call to curl_multi_socket*(). --- docs/libcurl/curl_multi_socket.3 | 42 ++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 9ad8257f1..3cfd20b40 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -4,29 +4,40 @@ .SH NAME curl_multi_socket \- reads/writes available data .SH SYNOPSIS +.nf #include +CURLMcode curl_multi_socket_action(CURLM * multi_handle, + curl_socket_t sockfd, int ev_bitmask, + int *running_handles); + CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, int *running_handles); CURLMcode curl_multi_socket_all(CURLM *multi_handle, int *running_handles); +.fi .SH DESCRIPTION Alternative versions of \fIcurl_multi_perform(3)\fP that allows the -application to pass in one of the file descriptors/sockets that have been -detected to have \&"action" on them and let libcurl perform. This allows -libcurl to not have to scan through all possible file descriptors to check for -action. When the application has detected action on a socket handled by -libcurl, it should call \fIcurl_multi_socket(3)\fP with the \fBsockfd\fP -argument set to the socket with the action. +application to pass in the file descriptor/socket that has been detected to +have \&"action" on it and let libcurl perform. This allows libcurl to not have +to scan through all possible file descriptors to check for action. When the +application has detected action on a socket handled by libcurl, it should call +\fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument set to the +socket with the action. When the events on a socket are known, they can be +passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP +to 0, and then adding using bitwise OR (|) any combination of events to be +choosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the +events on a socket are unknown, pass 0 instead, and libcurl will test the +descriptor internally. At return, the int \fBrunning_handles\fP points to will contain the number of still running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. Note that when you call -\fIcurl_multi_socket(3)\fP on a specific socket and the counter decreases by -one, it DOES NOT necessarily mean that this exact socket/transfer is the one -that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy -handle that completed. +\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter +decreases by one, it DOES NOT necessarily mean that this exact socket/transfer +is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out +which easy handle that completed. The curl_multi_socket functions inform the application about updates in the socket (file descriptor) status by doing none, one or multiple calls to the @@ -44,6 +55,10 @@ wait for socket actions \- at most \- before doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. +Usage of \fIcurl_multi_socket(3)\fP is depricated, whereas the function is +equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set +to 0. + .SH "CALLBACK DETAILS" The socket \fBcallback\fP function uses a prototype like this @@ -115,12 +130,15 @@ callback is called. 7. Wait for action on any of libcurl's sockets -8, When action happens, call curl_multi_socket() for the socket(s) that got +8, When action happens, call curl_multi_socket_action() for the socket(s) that got action. 9. Go back to step 6. .SH AVAILABILITY -This function was added in libcurl 7.15.4, although not deemed stable yet. +This function was added in libcurl 7.15.4, although deemed stablesince 7.16.0. + +\fIcurl_multi_socket(3)\fP is deprecated, use +\fIcurl_multi_socket_action(3)\fP instead! .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" -- cgit v1.2.1 From 92980376397236a7ca375b7054e831cd86e9a6a9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 3 May 2007 12:30:33 +0000 Subject: document the new 200alias behaviour --- docs/libcurl/curl_easy_setopt.3 | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 970600859..cdcdd1b76 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -736,10 +736,9 @@ The linked list should be a fully valid list of struct curl_slist structs, and be 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. -The alias itself is not parsed for any version strings. So if your alias is -\&"MYHTTP/9.9", Libcurl will not treat the server as responding with HTTP -version 9.9. Instead Libcurl will use the value set by option -\fICURLOPT_HTTP_VERSION\fP. +The alias itself is not parsed for any version strings. Before libcurl 7.16.3, +Libcurl used the value set by option \fICURLOPT_HTTP_VERSION\fP, but starting +wiht 7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matched. .IP CURLOPT_COOKIE Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be -- cgit v1.2.1 From 0b67ee7bad9476cd877ce90da8e9a6fd407bdc52 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 3 May 2007 19:12:45 +0000 Subject: Fixed a few typos. --- docs/libcurl/curl_easy_getinfo.3 | 2 +- docs/libcurl/curl_easy_setopt.3 | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index fbb182ebf..fe13f07c9 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -39,7 +39,7 @@ this function AFTER a performed transfer if you want to get transfer- oriented data. You should not free the memory returned by this function unless it is -explictly mentioned below. +explicitly mentioned below. .SH AVAILABLE INFORMATION The following information can be extracted: .IP CURLINFO_EFFECTIVE_URL diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index cdcdd1b76..78c58885a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -345,7 +345,7 @@ A non-zero parameter tells the library to fail silently if the HTTP code returned is equal to or larger than 400. The default action would be to return the page normally, ignoring that code. -This method is not fail-safe and there are occasions where non-succesful +This method is not fail-safe and there are occasions where non-successful response codes will slip through, especially when authentication is involved (response codes 401 and 407). @@ -445,7 +445,7 @@ not an order. You cannot be guaranteed to actually get the given size. (Added in 7.10) This size is by default set as big as possible (CURL_MAX_WRITE_SIZE), so it -only makse sense to use this option if you want it smaller. +only makes sense to use this option if you want it smaller. .IP CURLOPT_PORT Pass a long specifying what remote port number to connect to, instead of the one specified in the URL or the default port for the used protocol. @@ -649,7 +649,7 @@ When setting \fICURLOPT_POST\fP to a non-zero value, it will automatically set \fICURLOPT_NOBODY\fP to 0 (since 7.14.1). If you issue a POST request and then want to make a HEAD or GET using the same -re-used handle, you must explictly set the new request type using +re-used handle, you must explicitly set the new request type using \fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. .IP CURLOPT_POSTFIELDS Pass a char * as parameter, which should be the full data to post in an HTTP @@ -738,7 +738,7 @@ be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and The alias itself is not parsed for any version strings. Before libcurl 7.16.3, Libcurl used the value set by option \fICURLOPT_HTTP_VERSION\fP, but starting -wiht 7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matched. +with 7.16.3 the protocol is assumed to match HTTP 1.0 when an alias matched. .IP CURLOPT_COOKIE Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be @@ -1359,7 +1359,7 @@ require you to disable this in order for you to succeed. (Added in 7.16.0) Pass a char * as parameter. Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or \&'private'. If the string is set but doesn't match one of these, 'private' -will be used. Set the string to NULL to disable kerberos4. The kerberos +will be used. Set the string to NULL to disable Kerberos4. The Kerberos support only works for FTP. .SH SSH OPTIONS .IP CURLOPT_SSH_AUTH_TYPES -- cgit v1.2.1 From 1b7f00b2a68b59249181dac6557630e20f394ea6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 8 May 2007 11:34:31 +0000 Subject: CURLE_FTP_COULDNT_STOR_FILE is now known as CURLE_UPLOAD_FAILED. This is because I just made SCP uploads return this value if the file size of the upload file isn't given with CURLOPT_INFILESIZE*. Docs updated to reflect this news, and a define for the old name was added to the public header file. --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ docs/libcurl/libcurl-errors.3 | 34 +++++++++++++++++++++++++++------- 2 files changed, 32 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 78c58885a..3c8c4596e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1035,6 +1035,9 @@ When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. +For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE\fP is +mandatory. + Note that this option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns. .IP CURLOPT_INFILESIZE_LARGE @@ -1042,6 +1045,8 @@ When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed as a curl_off_t. (Added in 7.11.0) +For uploading using SCP, this option or \fICURLOPT_INFILESIZE\fP is mandatory. + Note that this option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns. .IP CURLOPT_UPLOAD diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 062bf83de..a2c071cb1 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -1,8 +1,27 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** .\" -.TH libcurl-errors 3 "9 Feb 2005" "libcurl 7.13.1" "libcurl errors" +.TH libcurl-errors 3 "8 May 2007" "libcurl 7.16.3" "libcurl errors" .SH NAME libcurl-errors \- error codes in libcurl .SH DESCRIPTION @@ -86,9 +105,10 @@ An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback. .IP "CURLE_MALFORMAT_USER (24)" This is never returned by current libcurl. -.IP "CURLE_FTP_COULDNT_STOR_FILE (25)" -FTP couldn't STOR file. The server denied the STOR operation. The error buffer -usually contains the server's explanation to this. +.IP "CURLE_UPLOAD_FAILED (25)" +Failed starting the upload. For FTP, the server typcially denied the STOR +command. The error buffer usually contains the server's explanation to 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. -- cgit v1.2.1 From ea43bb013ba7c2a95d2d29b5a33fc7bd5c01d31a Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Tue, 15 May 2007 00:28:50 +0000 Subject: Added support for quote commands before a transfer using SFTP and test case 614. Allow SFTP quote commands chmod, chown, chgrp to set a value of 0. --- docs/libcurl/curl_easy_setopt.3 | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3c8c4596e..3c789dd70 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -839,19 +839,20 @@ 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 commands to pass to the server prior to -your ftp request. This will be done before any other FTP commands are issued -(even before the CWD command). The linked list should be a fully valid list of -'struct curl_slist' structs properly filled in. Use \fIcurl_slist_append(3)\fP -to append strings (commands) to the list, and clear the entire list afterwards -with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a -NULL to this option. +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 +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 +to append strings (commands) to the list, and clear the entire list +afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation +again by setting a NULL to this option. .IP CURLOPT_POSTQUOTE -Pass a pointer to a linked list of FTP commands to pass to the 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. +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 +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. .IP CURLOPT_PREQUOTE Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. The linked list should be a fully valid list of -- cgit v1.2.1 From f2eb3c1f791599fce77c0f0e6a9cab5c622fb020 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 23 May 2007 12:51:52 +0000 Subject: fix the formatting of the trailing list --- docs/libcurl/libcurl-multi.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index c9ef3c056..a7010fe4e 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -125,6 +125,7 @@ A few areas in the code are still using blocking code, even when used from the multi interface. While we certainly want and intend for these to get fixed in the future, you should be aware of the following current restrictions: +.nf - Name resolves on non-windows unless c-ares is used - GnuTLS SSL connections - Active FTP connections @@ -132,3 +133,4 @@ the future, you should be aware of the following current restrictions: - SCP and SFTP connections - SFTP transfers - file:// transfers +.fi -- cgit v1.2.1 From 380e132da3557235e4eb9aa593e79c62100156ea Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 23 May 2007 12:59:12 +0000 Subject: TFTP transfers are also blocking --- docs/libcurl/libcurl-multi.3 | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index a7010fe4e..9afb107ed 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -132,5 +132,6 @@ the future, you should be aware of the following current restrictions: - HTTP proxy CONNECT operations - SCP and SFTP connections - SFTP transfers + - TFTP transfers - file:// transfers .fi -- cgit v1.2.1 From 4702807da8243cc5dd0b361f32c603272bde187b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 26 May 2007 20:47:33 +0000 Subject: make it a WARNING since this hits people hard in their faces --- docs/libcurl/curl_multi_info_read.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 414a2a610..1d97cf9a5 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -25,8 +25,8 @@ queue so calling this function again will not return the same message again. It will instead return new messages at each new invoke until the queue is emptied. -The data the returned pointer points to will not survive calling -\fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or +\fBWARNING:\fP The data the returned pointer points to will not survive +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. -- cgit v1.2.1 From ebb5e1db4b0a3cb1061ac992d615ad0bdadf2fd7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 26 May 2007 20:50:00 +0000 Subject: Clarify a bit about the fact that easy handles remain in the multi stack when transfers are done and need to be removed and closed or re-added. --- docs/libcurl/libcurl-multi.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 9afb107ed..9b36212e1 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -104,6 +104,12 @@ get more messages until the message queue is empty. The information you receive there includes an easy handle pointer which you may use to identify which easy handle the information regards. +When a single transfer is completed, the easy handle is still left added to +the multi stack. You need to first remove the easy handle with +\fIcurl_multi_remove_handle(3)\fP and then close it with +\fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again +with \fIcurl_multi_add_handle(3)\fP to start another transfer. + When all transfers in the multi stack are done, cleanup the multi handle with \fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP invoke separate \fIcurl_easy_cleanup(3)\fP calls on every single easy handle -- cgit v1.2.1 From a49e78d9b758cad12d886df2d5c8459a34477bbb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 30 May 2007 20:04:44 +0000 Subject: Added CURLMOPT_MAXCONNECTS which is a curl_multi_setopt() option for setting the maximum size of the connection cache maximum size of the multi handle. --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++++---- docs/libcurl/curl_multi_setopt.3 | 16 ++++++++++++++++ 2 files changed, 24 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3c789dd70..a31499958 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1129,10 +1129,10 @@ speed. (Added in 7.15.5) .IP CURLOPT_MAXCONNECTS 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. 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 protocols that support -persistent connections. +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 +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. @@ -1140,6 +1140,10 @@ prevent the number of open connections to increase. 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 +the \fICURLMOPT_MAXCONNECTS\fP option. .IP CURLOPT_CLOSEPOLICY (Obsolete) This option does nothing. .IP CURLOPT_FRESH_CONNECT diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 5ba81b952..f05ba2d36 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -56,6 +56,22 @@ Pass a pointer to whatever you want passed to the \fBcurl_multi_timer_callback\fP's third argument, the userp pointer. This is not used by libcurl but only passed-thru as-is. Set the callback pointer with \fICURLMOPT_TIMERFUNCTION\fP. (Added in 7.16.0) +.IP CURLMOPT_MAXCONNECTS +Pass a long. The set number will be used as the maximum amount of +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 +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. + +This option is for the multi handle's use only, when using the easy interface +you should instead use the \fICURLOPT_MAXCONNECTS\fP option. + +(Added in 7.16.3) .SH RETURNS The standard CURLMcode for multi interface error codes. Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl -- cgit v1.2.1 From 17798ed740db1874e94faa1a9c7d80dfa4e1b68c Mon Sep 17 00:00:00 2001 From: James Housley Date: Wed, 13 Jun 2007 15:02:34 +0000 Subject: Update documentation to reflect SFTP's ability to create directories on upload. Some text provieded by Tom Regner --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a31499958..72b4cdbdd 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -890,6 +890,11 @@ If the server is an IPv6 host, this option will have no effect as of 7.12.3. Pass a long. If the value is non-zero, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working directory. (Added in 7.10.7) + +This setting also applies to SFTP-connections. curl will attempt to create +the remote directory if it can't obtain a handle to the target-location. The +creation will fail if a file of the same name as the directory to create +already exists or lack of permissions prevents creation. (Added in 7.16.3) .IP CURLOPT_FTP_RESPONSE_TIMEOUT Pass a long. Causes curl to set a timeout period (in seconds) on the amount of time that the server is allowed to take in order to generate a response -- cgit v1.2.1 From 4cd7f85410ae9590fa4dd274a9c77604b3b8d4fc Mon Sep 17 00:00:00 2001 From: James Housley Date: Wed, 27 Jun 2007 20:15:48 +0000 Subject: Add two new options for the SFTP/SCP/FILE protocols: CURLOPT_NEW_FILE_PERMS and CURLOPT_NEW_DIRECTORY_PERMS. These control the premissions for files and directories created on the remote server. CURLOPT_NEW_FILE_PERMS defaults to 0644 and CURLOPT_NEW_DIRECTORY_PERMS defaults to 0755 --- docs/libcurl/curl_easy_setopt.3 | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 72b4cdbdd..01e4dc3c0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1401,6 +1401,17 @@ this curl handle use the data from the shared handle instead of keeping the data to itself. This enables several curl handles to share data. If the curl handles are used simultaneously, you \fBMUST\fP use the locking methods in the share handle. See \fIcurl_share_setopt(3)\fP for details. +.IP CURLOPT_NEW_FILE_PERMS +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) +.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. +(Added in 7.16.4) .SH TELNET OPTIONS .IP CURLOPT_TELNETOPTIONS Provide a pointer to a curl_slist with variables to pass to the telnet -- cgit v1.2.1 From 54967d2a3ab5559631407f7b7f67ef48c2dda6dd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 1 Jul 2007 22:01:18 +0000 Subject: Thomas J. Moore provided a patch that introduces Kerberos5 support in libcurl. This also makes the options change name to --krb (from --krb4) and CURLOPT_KRBLEVEL (from CURLOPT_KRB4LEVEL) but the old names are still --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 01e4dc3c0..cbbf411a0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1370,12 +1370,12 @@ this to 1 to enable it. By default all transfers are done using the cache. Note that while nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0) -.IP CURLOPT_KRB4LEVEL -Pass a char * as parameter. Set the krb4 security level, this also enables -krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or -\&'private'. If the string is set but doesn't match one of these, 'private' -will be used. Set the string to NULL to disable Kerberos4. The Kerberos -support only works for FTP. +.IP CURLOPT_KRBLEVEL +Pass a char * as parameter. Set the kerberos security level for FTP; this +also enables kerberos awareness. This is a string, 'clear', 'safe', +'confidential' or \&'private'. If the string is set but doesn't match one +of these, 'private' will be used. Set the string to NULL to disable kerberos +support for FTP. .SH SSH OPTIONS .IP CURLOPT_SSH_AUTH_TYPES Pass a long set to a bitmask consisting of one or more of -- cgit v1.2.1 From fcfffbe2f2382ad9249b532cca17fdcf3932373c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 1 Jul 2007 22:03:47 +0000 Subject: mention the old name --- docs/libcurl/curl_easy_setopt.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index cbbf411a0..a10a30245 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1376,6 +1376,8 @@ also enables kerberos awareness. This is a string, 'clear', 'safe', 'confidential' or \&'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos support for FTP. + +(This option was known as CURLOPT_KRB4LEVEL up to 7.16.3) .SH SSH OPTIONS .IP CURLOPT_SSH_AUTH_TYPES Pass a long set to a bitmask consisting of one or more of -- cgit v1.2.1 From 55cd28283c432285469439359e48ec7410a56434 Mon Sep 17 00:00:00 2001 From: James Housley Date: Mon, 2 Jul 2007 17:22:51 +0000 Subject: Fix problem with the indenting noticed by Pavel --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a10a30245..8ee771d6d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -810,6 +810,7 @@ it thinks fit. Enforce HTTP 1.0 requests. .IP CURL_HTTP_VERSION_1_1 Enforce HTTP 1.1 requests. +.RE .IP CURLOPT_IGNORE_CONTENT_LENGTH Ignore the Content-Length header. This is useful for Apache 1.x (and similar servers) which will report incorrect content length for files over 2 @@ -826,7 +827,6 @@ Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. (added in 7.16.2) -.RE .SH FTP OPTIONS .IP CURLOPT_FTPPORT Pass a pointer to a zero terminated string as parameter. It will be used to -- cgit v1.2.1 From 5e1cd407a3238cbee8431ade5c82d4fcdbfe507a Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Wed, 11 Jul 2007 19:21:38 +0000 Subject: Added the first libcurl version to which the SSH options were added. --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8ee771d6d..648874060 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1383,13 +1383,16 @@ support for FTP. Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. +(Added in 7.16.1) .IP CURLOPT_SSH_PUBLIC_KEYFILE Pass a char * pointing to a file name for your public key. If not used, libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP. +(Added in 7.16.1) .IP CURLOPT_SSH_PRIVATE_KEYFILE Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to using \fB~/.ssh/id_dsa\fP. If the file is password-protected, set the password with \fICURLOPT_SSLKEYPASSWD\fP. +(Added in 7.16.1) .SH OTHER OPTIONS .IP CURLOPT_PRIVATE Pass a char * as parameter, pointing to data that should be associated with -- cgit v1.2.1 From aad1d3ce14eca5b319329507571fac96291f41ee Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 13 Jul 2007 20:07:22 +0000 Subject: Daniel Cater: libcurl-errors needs updating to reflect a couple of deprecated error codes --- docs/libcurl/libcurl-errors.3 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index a2c071cb1..958ff8d56 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -99,7 +99,8 @@ When sending custom "QUOTE" commands to the remote server, one of the commands returned an error code that was 400 or higher. .IP "CURLE_HTTP_RETURNED_ERROR (22)" This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server -returns an error code that is >= 400. +returns an error code that is >= 400. (This error code was formerly known as +CURLE_HTTP_NOT_FOUND.) .IP "CURLE_WRITE_ERROR (23)" An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback. @@ -157,10 +158,11 @@ Aborted by callback. A callback returned "abort" to libcurl. Internal error. A function was called with a bad parameter. .IP "CURLE_BAD_CALLING_ORDER (44)" This is never returned by current libcurl. -.IP "CURLE_HTTP_PORT_FAILED (45)" +.IP "CURLE_INTERFACE_FAILED (45)" Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections' source IP address with -CURLOPT_INTERFACE. +CURLOPT_INTERFACE. (This error code was formerly known as +CURLE_HTTP_PORT_FAILED.) .IP "CURLE_BAD_PASSWORD_ENTERED (46)" This is never returned by current libcurl. .IP "CURLE_TOO_MANY_REDIRECTS (47)" -- cgit v1.2.1 From d9b5f327bf3346c64cca2cb3c33fed2296aab220 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Wed, 18 Jul 2007 22:23:07 +0000 Subject: Added the list of sftp quote commands. --- docs/libcurl/curl_easy_setopt.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 648874060..ed6ccb855 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -847,6 +847,8 @@ properly filled in with text strings. Use \fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL to this option. +The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, +rename, rm, rmdir, symlink. (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 -- cgit v1.2.1 From 5251c45187279eb0a2915854fb608295d76668ba Mon Sep 17 00:00:00 2001 From: James Housley Date: Wed, 18 Jul 2007 23:21:32 +0000 Subject: SFTP also supports PWD --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ed6ccb855..0a64c1bef 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -848,7 +848,7 @@ to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL to this option. The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, -rename, rm, rmdir, symlink. (SFTP support added in 7.16.3) +rename, rm, rmdir, symlink, PWD. (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 -- cgit v1.2.1 From 000fdc6b99c1a30524e6ad71e3cae10c463e26cb Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 20 Jul 2007 17:29:43 +0000 Subject: Document pwd as an sftp quote command for curl(1), and show it as lower case for consistency since sftp commands are case insensitive. --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0a64c1bef..63b53f7c4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -847,8 +847,8 @@ properly filled in with text strings. Use \fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL to this option. -The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, -rename, rm, rmdir, symlink, PWD. (SFTP support added in 7.16.3) +The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, +rename, rm, rmdir, symlink. (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 -- cgit v1.2.1 From f3799462c2c887ba8c6a72b64cebd36fdf524375 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 30 Jul 2007 21:47:44 +0000 Subject: updated based on suggestion from Jeff Pohlmeyer --- docs/libcurl/curl_multi_socket.3 | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 3cfd20b40..8caa0e83c 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -123,22 +123,25 @@ function returns OK. 4. Call curl_multi_socket_all() first once -5. Setup a "collection" of sockets to supervise when your socket -callback is called. +5. Provide some means to manage the sockets libcurl is using, so you can check +them for activity. This can be done through your application code, or by way +of an external library such as libevent or glib. -6. Use curl_multi_timeout() to figure out how long to wait for action +6. Use curl_multi_timeout() to figure out how long to wait for activity -7. Wait for action on any of libcurl's sockets +7. Wait for activity on any of libcurl's sockets -8, When action happens, call curl_multi_socket_action() for the socket(s) that got -action. +8, When activity is detected, call curl_multi_socket_action() for the +socket(s) that got action. 9. Go back to step 6. .SH AVAILABILITY -This function was added in libcurl 7.15.4, although deemed stablesince 7.16.0. +This function was added in libcurl 7.15.4, although deemed stable since +7.16.0. \fIcurl_multi_socket(3)\fP is deprecated, use \fIcurl_multi_socket_action(3)\fP instead! .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " -.BR curl_multi_fdset "(3), " curl_multi_info_read "(3)" +.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " +.BR "the hiperfifo.c example" -- cgit v1.2.1 From ba5c71b79b13e6674a68bc511043b085ed156048 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 30 Jul 2007 21:47:56 +0000 Subject: less blocking these days --- docs/libcurl/libcurl-multi.3 | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 9b36212e1..6e33581d1 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -136,8 +136,6 @@ the future, you should be aware of the following current restrictions: - GnuTLS SSL connections - Active FTP connections - HTTP proxy CONNECT operations - - SCP and SFTP connections - - SFTP transfers - TFTP transfers - file:// transfers .fi -- cgit v1.2.1 From 16710a1c9bb763cc523738d61194fd40776c9fa5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 30 Jul 2007 22:01:04 +0000 Subject: users should use the CURLMOPT_TIMERFUNCTION rather than curl_multi_timeout when using the socket API --- docs/libcurl/curl_multi_socket.3 | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 8caa0e83c..f8587fdee 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -106,7 +106,7 @@ The \fIuserp\fP argument is a private pointer you have previously set with CURLMcode type, general libcurl multi interface error code. If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you -should call \fIcurl_multi_perform\fP again, before you wait for more actions +should call \fIcurl_multi_socket(3)\fP again, before you wait for more actions on libcurl's sockets. 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". @@ -119,22 +119,25 @@ function returns OK. 2. Set the socket callback with CURLMOPT_SOCKETFUNCTION -3. Add easy handles +3. Set the timeout callback with CURLMOPT_TIMERFUNCTION, to get to know what +timeout value to use when waiting for socket activities. -4. Call curl_multi_socket_all() first once +4. Add easy handles -5. Provide some means to manage the sockets libcurl is using, so you can check +5. Call curl_multi_socket_all() first once + +6. Provide some means to manage the sockets libcurl is using, so you can check them for activity. This can be done through your application code, or by way of an external library such as libevent or glib. -6. Use curl_multi_timeout() to figure out how long to wait for activity - -7. Wait for activity on any of libcurl's sockets +7. Wait for activity on any of libcurl's sockets, use the timeout value your +calback has been told 8, When activity is detected, call curl_multi_socket_action() for the -socket(s) that got action. +socket(s) that got action. If no activity is detected and the timeout expires, +call \fIcurl_multi_socket(3)\fP with \fICURL_SOCKET_TIMEOUT\fP -9. Go back to step 6. +9. Go back to step 7. .SH AVAILABILITY This function was added in libcurl 7.15.4, although deemed stable since 7.16.0. -- cgit v1.2.1 From 50c10aa5bf545eedfdbe561116656b6ec12654cd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 1 Aug 2007 21:20:01 +0000 Subject: Patrick Monnerat and I modified libcurl so that now it *copies* all strings passed to it with curl_easy_setopt()! Previously it has always just refered to the data, forcing the user to keep the data around until libcurl is done with it. That is now history and libcurl will instead clone the given strings and keep private copies. --- docs/libcurl/curl_easy_getinfo.3 | 4 +++- docs/libcurl/curl_easy_setopt.3 | 22 +++++++++++++++------- 2 files changed, 18 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index fe13f07c9..95455e3a1 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -133,7 +133,9 @@ protocol used doesn't support this. .IP CURLINFO_PRIVATE Pass a pointer to a 'char *' to receive the pointer to the private data associated with the curl handle (set with the CURLOPT_PRIVATE option to -\fIcurl_easy_setopt(3)\fP). (Added in 7.10.3) +\fIcurl_easy_setopt(3)\fP). Please note that for internal reasons, the +value is returned as a 'char *', although effectively being a 'void *'. +(Added in 7.10.3) .IP CURLINFO_HTTPAUTH_AVAIL Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available. The meaning of the bits is explained in the diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 63b53f7c4..016bb9181 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "22 Feb 2007" "libcurl 7.16.2" "libcurl Manual" +.TH curl_easy_setopt 3 "1 Aug 2007" "libcurl 7.17.0" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -44,11 +44,13 @@ between transfers, so if you want subsequent transfers with different options, you must change them between the transfers. You can optionally reset all options back to internal default with \fIcurl_easy_reset(3)\fP. -Strings passed to libcurl as 'char *' arguments, will not be copied by the -library. Instead you should keep them available until libcurl no longer needs -them. Failing to do so will cause very odd behavior or even crashes. libcurl -will need them until you call \fIcurl_easy_cleanup(3)\fP or you set the same -option again to use a different pointer. +Strings passed to libcurl as 'char *' arguments, are copied by the library; +thus the string storage associated to the pointer argument may be overwritten +after curl_easy_setopt() returns. Exceptions to this rule are described in +the option details below. + +NOTE: before 7.17.0 strings were not copied. Instead the user was forced keep +them available until libcurl no longer needed them. The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. @@ -330,6 +332,12 @@ system. Pass a char * to a buffer that the libcurl may store human readable error messages in. This may be more helpful than just the return code from \fIcurl_easy_perform\fP. The buffer must be at least CURL_ERROR_SIZE big. +Although this argument is a 'char *', it does not describe an input string. +Therefore the (probably undefined) contents of the buffer is NOT copied +by the library. You should keep the associated storage available until +libcurl no longer needs it. Failing to do so will cause very odd behavior +or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP +or you set the same option again to use a different pointer. Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better debug/trace why errors happen. @@ -1397,7 +1405,7 @@ If the file is password-protected, set the password with \fICURLOPT_SSLKEYPASSWD (Added in 7.16.1) .SH OTHER OPTIONS .IP CURLOPT_PRIVATE -Pass a char * as parameter, pointing to data that should be associated with +Pass a void * as parameter, pointing to data that should be associated with this curl handle. The pointer can subsequently be retrieved using \fIcurl_easy_getinfo(3)\fP with the CURLINFO_PRIVATE option. libcurl itself does nothing with this data. (Added in 7.10.3) -- cgit v1.2.1 From 5a6dcdc36c33e15f1b32f08bf885ec5d48b27aec Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 2 Aug 2007 13:26:06 +0000 Subject: clarify that setting POSTFIELDS to NULL or "" is not enough to make a zero byte POST --- docs/libcurl/curl_easy_setopt.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 016bb9181..62d8aa1b0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -670,6 +670,12 @@ set that Content-Type by default when this option is used), which is the most commonly used one by HTML forms. See also the \fICURLOPT_POST\fP. Using \fICURLOPT_POSTFIELDS\fP implies \fICURLOPT_POST\fP. +If you want to do a zero-byte POST, you need to set +\fICURLOPT_POSTFIELDSIZE\fP explicitly to zero, as simply setting +\fICURLOPT_POSTFIELDS\fP to NULL or "" just effectively disables the sending +of the specified string. libcurl will instead assume that you'll send the POST +data using the read callback! + Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. -- cgit v1.2.1 From c1b9356081d75c00f5907605a32e0fc3f5b8f46b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 7 Aug 2007 21:14:31 +0000 Subject: Usage of the BCURLOPT_PROGRESSFUNCTION callback is not recommended when using the multi interface, but having the comment in here caused more questions than we fixed problems so I remove it now. It still works fine. --- docs/libcurl/curl_easy_setopt.3 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 62d8aa1b0..fa2aa57f0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -196,8 +196,7 @@ this callback will cause libcurl to abort the transfer and return If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl -function that performs transfers. Usage of the \fBCURLOPT_PROGRESSFUNCTION\fP -callback is not recommended when using the multi interface. +function that performs transfers. \fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually get called. -- cgit v1.2.1 From 014f1bea9ab122c473c90a86efdb8f6711585ad8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 22 Aug 2007 11:28:26 +0000 Subject: 1) the talk about strings used by libcurl doesn't apply to libcurl >= 7.17.0 2) added nroff header --- docs/libcurl/curl_easy_cleanup.3 | 34 +++++++++++++++++++++++++++------- 1 file changed, 27 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index 2eda26e92..c19291af2 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -1,8 +1,27 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** .\" -.TH curl_easy_cleanup 3 "12 Oct 2006" "libcurl 7.7" "libcurl Manual" +.TH curl_easy_cleanup 3 "22 aug 2007" "libcurl 7.17.0" "libcurl Manual" .SH NAME curl_easy_cleanup - End a libcurl easy session .SH SYNOPSIS @@ -19,11 +38,12 @@ This will effectively close all connections this handle has used and possibly has kept open until now. Don't call this function if you intend to transfer more files. -When you've called this, you can safely remove all the strings you've -previously told libcurl to use, as it won't use them anymore now. - Any uses of the \fBhandle\fP after this function has been called are illegal. This kills the handle and all memory associated with it! + +With libcurl versions prior to 7.17.: when you've called this, you can safely +remove all the strings you've previously told libcurl to use, as it won't use +them anymore now. .SH RETURN VALUE None .SH "SEE ALSO" -- cgit v1.2.1 From 9f44a95522162c0f4a61093efe1bf1f58b087358 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 30 Aug 2007 20:34:57 +0000 Subject: Renamed several libcurl error codes and options to make them more general and allow reuse by multiple protocols. Several unused error codes were removed. In all cases, macros were added to preserve source (and binary) compatibility with the old names. These macros are subject to removal at a future date, but probably not before 2009. An application can be tested to see if it is using any obsolete code by compiling it with the CURL_NO_OLDIES macro defined. Documented some newer error codes in libcurl-error(3) --- docs/libcurl/curl_easy_setopt.3 | 42 ++++++++++--------- docs/libcurl/libcurl-errors.3 | 92 +++++++++++++++++------------------------ docs/libcurl/libcurl-tutorial.3 | 4 +- 3 files changed, 63 insertions(+), 75 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index fa2aa57f0..f3da0014a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "1 Aug 2007" "libcurl 7.17.0" "libcurl Manual" +.TH curl_easy_setopt 3 "30 Aug 2007" "libcurl 7.17.0" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -764,7 +764,7 @@ multiple cookies in one string like this: "name1=content1; name2=content2;" etc. Using this option multiple times will only make the latest string override the -previously ones. +previous ones. .IP CURLOPT_COOKIEFILE Pass a pointer to a zero terminated string as parameter. It should contain the name of your file holding cookie data to read. The cookie data may be in @@ -875,17 +875,21 @@ struct curl_slist structs properly filled in as described for \fICURLOPT_QUOTE\fP. Disable this operation again by setting a NULL to this option. Before version 7.15.6, if you also set \fICURLOPT_NOBODY\fP non-zero, this option didn't work. -.IP CURLOPT_FTPLISTONLY -A non-zero parameter tells the library to just list the names of an ftp +.IP CURLOPT_DIRLISTONLY +A non-zero parameter tells the library to just list the names of files in a directory, instead of doing a full directory listing that would include file -sizes, dates etc. +sizes, dates etc. This works for FTP and SFTP URLs. -This causes an FTP NLST command to be sent. Beware that some FTP servers list -only files in their response to NLST; they might not include subdirectories -and symbolic links. -.IP CURLOPT_FTPAPPEND +This causes an FTP NLST command to be sent on an FTP server. Beware +that some FTP servers list only files in their response to NLST; they +might not include subdirectories and symbolic links. + +(This option was known as CURLOPT_FTPLISTONLY up to 7.16.4) +.IP CURLOPT_APPEND A non-zero parameter tells the library to append to the remote file instead of 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 Pass a long. If the value is non-zero, it tells curl to use the EPRT (and LPRT) command when doing active FTP downloads (which is enabled by @@ -932,9 +936,11 @@ same IP address it already uses for the control connection. But it will use the port number 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_FTP_SSL +.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) + +(This option was known as CURLOPT_FTP_SSL up to 7.16.4) .RS .IP CURLFTPSSL_NONE Don't attempt to use SSL. @@ -1225,13 +1231,6 @@ with. Pass a pointer to a zero terminated string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER". (Added in 7.9.3) -.IP CURLOPT_SSLCERTPASSWD -Pass a pointer to a zero terminated string as parameter. It will be used as -the password required to use the \fICURLOPT_SSLCERT\fP certificate. - -This option is replaced by \fICURLOPT_SSLKEYPASSWD\fP and should only be used -for backward compatibility. You never needed a pass phrase to load a -certificate but you need one to load your private key. .IP CURLOPT_SSLKEY Pass a pointer to a zero terminated string as parameter. The string should be the file name of your private key. The default format is "PEM" and can be @@ -1244,10 +1243,15 @@ The format "ENG" enables you to load the private key from a crypto engine. In this case \fICURLOPT_SSLKEY\fP is used as an identifier passed to the engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE\fP. \&"DER" format key file currently does not work because of a bug in OpenSSL. -.IP CURLOPT_SSLKEYPASSWD +.IP CURLOPT_KEYPASSWD Pass a pointer to a zero terminated string as parameter. It will be used as the password required to use the \fICURLOPT_SSLKEY\fP or \fICURLOPT_SSH_PRIVATE_KEYFILE\fP private key. +You never needed a pass phrase to load a certificate but you need one to +load your private key. + +(This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and +CURLOPT_SSLCERTPASSWD up to 7.9.2) .IP CURLOPT_SSLENGINE Pass a pointer to a zero terminated string as parameter. It will be used as the identifier for the crypto engine you want to use for your private @@ -1406,7 +1410,7 @@ libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP. .IP CURLOPT_SSH_PRIVATE_KEYFILE Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to using \fB~/.ssh/id_dsa\fP. -If the file is password-protected, set the password with \fICURLOPT_SSLKEYPASSWD\fP. +If the file is password-protected, set the password with \fICURLOPT_KEYPASSWD\fP. (Added in 7.16.1) .SH OTHER OPTIONS .IP CURLOPT_PRIVATE diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 958ff8d56..6aaf11db7 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-errors 3 "8 May 2007" "libcurl 7.16.3" "libcurl errors" +.TH libcurl-errors 3 "30 Aug 2007" "libcurl 7.17.0" "libcurl errors" .SH NAME libcurl-errors \- error codes in libcurl .SH DESCRIPTION @@ -48,8 +48,6 @@ Very early initialization code failed. This is likely to be an internal error or problem. .IP "CURLE_URL_MALFORMAT (3)" The URL was not properly formatted. -.IP "CURLE_URL_MALFORMAT_USER (4)" -This is never returned by current libcurl. .IP "CURLE_COULDNT_RESOLVE_PROXY (5)" Couldn't resolve proxy. The given proxy host could not be resolved. .IP "CURLE_COULDNT_RESOLVE_HOST (6)" @@ -60,17 +58,12 @@ Failed to connect() to host or proxy. After connecting to an 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_FTP_ACCESS_DENIED (9)" -We were denied access when trying to login to an FTP server or when trying to -change working directory to the one given in the URL. -.IP "CURLE_FTP_USER_PASSWORD_INCORRECT (10)" -This is never returned by current libcurl. +.IP "CURLE_REMOTE_ACCESS_DENIED (9)" +We were denied access to the resource given in the URL. For FTP, this occurs +while trying to change to the remote directory. .IP "CURLE_FTP_WEIRD_PASS_REPLY (11)" After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. -.IP "CURLE_FTP_WEIRD_USER_REPLY (12)" -After having sent user name to the FTP server, libcurl expects a proper -reply. This error code indicates that an unexpected code was returned. .IP "CURLE_FTP_WEIRD_PASV_REPLY (13)" libcurl failed to get a sensible result back from the server as a response to either a PASV or a EPSV command. The server is flawed. @@ -79,11 +72,8 @@ FTP servers return a 227-line as a response to a PASV command. If libcurl 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_CANT_RECONNECT (16)" -A bad return code on either PASV or EPSV was sent by the FTP server, -preventing libcurl from being able to continue. -.IP "CURLE_FTP_COULDNT_SET_BINARY (17)" -Received an error when trying to set the transfer mode to binary. +.IP "CURLE_FTP_COULDNT_SET_TYPE (17)" +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 @@ -91,12 +81,10 @@ doesn't match the previously given size. .IP "CURLE_FTP_COULDNT_RETR_FILE (19)" This was either a weird reply to a 'RETR' command or a zero byte transfer complete. -.IP "CURLE_FTP_WRITE_ERROR (20)" -After a completed file transfer, the FTP server did not respond a proper -\"transfer successful\" code. -.IP "CURLE_FTP_QUOTE_ERROR (21)" +.IP "CURLE_QUOTE_ERROR (21)" When sending custom "QUOTE" commands to the remote server, one of the commands -returned an error code that was 400 or higher. +returned an error code that was 400 or higher (for FTP) or otherwise +indicated unsuccessful completion of the command. .IP "CURLE_HTTP_RETURNED_ERROR (22)" This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server returns an error code that is >= 400. (This error code was formerly known as @@ -104,34 +92,27 @@ CURLE_HTTP_NOT_FOUND.) .IP "CURLE_WRITE_ERROR (23)" An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback. -.IP "CURLE_MALFORMAT_USER (24)" -This is never returned by current libcurl. .IP "CURLE_UPLOAD_FAILED (25)" -Failed starting the upload. For FTP, the server typcially denied the STOR +Failed starting the upload. For FTP, the server typically denied the STOR command. The error buffer usually contains the server's explanation to 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)" -Out of memory. A memory allocation request failed. This is serious badness and +A memory allocation request failed. This is serious badness and things are severely screwed up if this ever occur. -.IP "CURLE_OPERATION_TIMEOUTED (28)" +.IP "CURLE_OPERATION_TIMEDOUT (28)" Operation timeout. The specified time-out period was reached according to the conditions. -.IP "CURLE_FTP_COULDNT_SET_ASCII (29)" -libcurl failed to set ASCII transfer type (TYPE A). .IP "CURLE_FTP_PORT_FAILED (30)" The FTP PORT command returned error. This mostly happen 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 sane. -.IP "CURLE_FTP_COULDNT_GET_SIZE (32)" -The FTP SIZE command returned error. SIZE is not a kosher FTP command, it is -an extension and not all servers support it. This is not a surprising error. -.IP "CURLE_HTTP_RANGE_ERROR (33)" -The HTTP server does not support or accept range requests. +.IP "CURLE_RANGE_ERROR (33)" +The server does not support or accept range requests. .IP "CURLE_HTTP_POST_ERROR (34)" This is an odd error that mainly occurs due to internal confusion. .IP "CURLE_SSL_CONNECT_ERROR (35)" @@ -148,23 +129,17 @@ path doesn't identify an existing file. Did you check file permissions? LDAP cannot bind. LDAP bind operation failed. .IP "CURLE_LDAP_SEARCH_FAILED (39)" LDAP search failed. -.IP "CURLE_LIBRARY_NOT_FOUND (40)" -Library not found. The LDAP library was not found. .IP "CURLE_FUNCTION_NOT_FOUND (41)" -Function not found. A required LDAP function was not found. +Function not found. A required zlib function was not found. .IP "CURLE_ABORTED_BY_CALLBACK (42)" Aborted by callback. A callback returned "abort" to libcurl. .IP "CURLE_BAD_FUNCTION_ARGUMENT (43)" Internal error. A function was called with a bad parameter. -.IP "CURLE_BAD_CALLING_ORDER (44)" -This is never returned by current libcurl. .IP "CURLE_INTERFACE_FAILED (45)" Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections' source IP address with CURLOPT_INTERFACE. (This error code was formerly known as CURLE_HTTP_PORT_FAILED.) -.IP "CURLE_BAD_PASSWORD_ENTERED (46)" -This is never returned by current libcurl. .IP "CURLE_TOO_MANY_REDIRECTS (47)" Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS. @@ -173,9 +148,6 @@ An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to the appropriate documentation. .IP "CURLE_TELNET_OPTION_SYNTAX (49)" A telnet option string was Illegally formatted. -.IP "CURLE_OBSOLETE (50)" -This is not an error. This used to be another error code in an old libcurl -version and is currently unused. .IP "CURLE_SSL_PEER_CERTIFICATE (51)" The remote server's SSL certificate was deemed not OK. .IP "CURLE_GOT_NOTHING (52)" @@ -189,14 +161,12 @@ Failed setting the selected SSL crypto engine as default! Failed sending network data. .IP "CURLE_RECV_ERROR (56)" Failure with receiving network data. -.IP "CURLE_SHARE_IN_USE (57)" -Share is in use .IP "CURLE_SSL_CERTPROBLEM (58)" 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 .IP "CURLE_LDAP_INVALID_URL (62)" @@ -214,24 +184,33 @@ Initiating the SSL Engine failed The remote server denied curl to login (Added in 7.13.1) .IP "CURLE_TFTP_NOTFOUND (68)" File not found on TFTP server -.IP "CURLE_TFTP_PERM (69" +.IP "CURLE_TFTP_PERM (69)" Permission problem on TFTP server -.IP "CURLE_TFTP_DISKFULL (70)" -Out of disk space on TFTP server +.IP "CURLE_REMOTE_DISK_FULL (70)" +Out of disk space on the server .IP "CURLE_TFTP_ILLEGAL (71)" Illegal TFTP operation .IP "CURLE_TFTP_UNKNOWNID (72)" Unknown TFTP transfer ID -.IP "CURLE_TFTP_EXISTS (73)" -TFTP File already exists +.IP "CURLE_REMOTE_FILE_EXISTS (73)" +File already exists and will not be overwritten .IP "CURLE_TFTP_NOSUCHUSER (74)" -No such TFTP user +This error should never be returned by a properly functioning TFTP server .IP "CURLE_CONV_FAILED (75)" Character conversion failed .IP "CURLE_CONV_REQD (76)" 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 +.IP "CURLE_SSH (79)" +An unspecified error occurred during the SSH session +.IP "CURLE_SSL_SHUTDOWN_FAILED (80)" +Failed to shut down the SSL connection +.IP "CURLE_OBSOLETE*" +These error codes will never be returned. They used to be 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 interface. Also consider \fIcurl_multi_strerror(3)\fP. @@ -253,6 +232,9 @@ This can only be returned if libcurl bugs. Please report it to us! .IP "CURLM_BAD_SOCKET (5)" The passed-in socket is not a valid one that libcurl already knows about. (Added in 7.15.4) +.IP "CURLM_UNKNOWN_OPTION (6)" +curl_multi_setopt() with unsupported option +(Added in 7.15.4) .SH "CURLSHcode" The "share" interface will return a CURLSHcode to indicate when an error has occurred. Also consider \fIcurl_share_strerror(3)\fP. @@ -264,4 +246,6 @@ An invalid option was passed to the function. The share object is currently in use. .IP "CURLSHE_INVALID (3)" An invalid share object was passed to the function. - +.IP "CURLSHE_NOMEM (4)" +Not enough memory was available. +(Added in 7.12.0) diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 070aa5465..0d52cf987 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -415,7 +415,7 @@ you're using an SSL private key for secure transfers. To pass the known private key password to libcurl: - curl_easy_setopt(easyhandle, CURLOPT_SSLKEYPASSWD, "keypassword"); + curl_easy_setopt(easyhandle, CURLOPT_KEYPASSWD, "keypassword"); .SH "HTTP Authentication" The previous chapter showed how to set user name and password for getting @@ -931,7 +931,7 @@ would instead be called CURLOPT_POSTQUOTE and used the exact same way. The custom FTP command will be issued to the server in the same order they are added to the list, and if a command gets an error code returned back from the server, no more commands will be issued and libcurl will bail out with an -error code (CURLE_FTP_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE to send +error code (CURLE_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE to send commands before a transfer, no transfer will actually take place when a quote command has failed. -- cgit v1.2.1 From 3fa60164af98720696cf157158e78ad4e0540aba Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 31 Aug 2007 19:36:32 +0000 Subject: Renamed the CURLE_FTP_SSL_FAILED error code to CURLE_USE_SSL_FAILED. Renamed the curl_ftpssl enum to curl_usessl and its enumerated constants, creating macros for backward compatibility. --- docs/libcurl/curl_easy_setopt.3 | 15 ++++++++------- docs/libcurl/libcurl-errors.3 | 2 +- 2 files changed, 9 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f3da0014a..0e5d6afff 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -940,16 +940,17 @@ This option has no effect if PORT, EPRT or EPSV is used instead of PASV. 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) -(This option was known as CURLOPT_FTP_SSL up to 7.16.4) +(This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants +were known as CURLFTPSSL_*) .RS -.IP CURLFTPSSL_NONE +.IP CURLUSESSL_NONE Don't attempt to use SSL. -.IP CURLFTPSSL_TRY +.IP CURLUSESSL_TRY Try using SSL, proceed as normal otherwise. -.IP CURLFTPSSL_CONTROL -Require SSL for the control connection or fail with \fICURLE_FTP_SSL_FAILED\fP. -.IP CURLFTPSSL_ALL -Require SSL for all communication or fail with \fICURLE_FTP_SSL_FAILED\fP. +.IP CURLUSESSL_CONTROL +Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. +.IP CURLUSESSL_ALL +Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. .RE .IP CURLOPT_FTPSSLAUTH Pass a long using one of the values from below, to alter how libcurl issues diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 6aaf11db7..1d8f4e88b 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -173,7 +173,7 @@ Unrecognized transfer encoding Invalid LDAP URL .IP "CURLE_FILESIZE_EXCEEDED (63)" Maximum file size exceeded -.IP "CURLE_FTP_SSL_FAILED (64)" +.IP "CURLE_USE_SSL_FAILED (64)" 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 -- cgit v1.2.1 From 0489081d3fa710ec8695d42ea93d8ef34f23cae5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Oct 2007 09:56:52 +0000 Subject: CURLOPT_POST301 section, added by Philip Langdale --- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0e5d6afff..edf7473ff 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -619,6 +619,13 @@ redirections have been followed, the next redirect will cause an error \fICURLOPT_FOLLOWLOCATION\fP is used at the same time. Added in 7.15.1: Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite number of redirects (which is the default) +.IP CURLOPT_POST301 +A non-zero parameter tells the library to respect RFC 2616/10.3.2 and not +convert POST requests into GET requests when following a 301 redirection. 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) .IP CURLOPT_PUT A non-zero parameter tells the library to use HTTP PUT to transfer data. The data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP. -- cgit v1.2.1 From 51c6a5d43b09835289a469165aa7a2bfb79dbdc6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 3 Oct 2007 08:00:42 +0000 Subject: Based on a patch brought by Johnny Luong, libcurl now offers CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 and the curl tool --hostpubmd5. They both make the SCP or SFTP connection verify the remote host's md5 checksum of the public key before doing a connect, to reduce the risk of a man-in-the-middle attack. --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index edf7473ff..ac460ae09 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1411,6 +1411,11 @@ Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. (Added in 7.16.1) +.IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 +Pass a char * pointing to a string containing 32 hexadecimal digits. The +string should be the 128 bit MD5 cheksum of the remote host's public key, and +libcurl will reject the connection to the host unless the md5sums match. This +option is only for SCP and SFTP transfers. (Added in 7.17.1) .IP CURLOPT_SSH_PUBLIC_KEYFILE Pass a char * pointing to a file name for your public key. If not used, libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP. -- cgit v1.2.1 From ce81cd21d3865270867d68935c9700dbaf5b5fcc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 3 Oct 2007 08:07:50 +0000 Subject: I renamed the CURLE_SSL_PEER_CERTIFICATE error code to CURLE_PEER_FAILED_VERIFICATION (standard CURL_NO_OLDIES style), and made this return code get used by the previous SSH MD5 fingerprint check in case it fails. --- docs/libcurl/libcurl-errors.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 1d8f4e88b..a686793f7 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -148,8 +148,8 @@ An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to the appropriate documentation. .IP "CURLE_TELNET_OPTION_SYNTAX (49)" A telnet option string was Illegally formatted. -.IP "CURLE_SSL_PEER_CERTIFICATE (51)" -The remote server's SSL certificate was deemed not OK. +.IP "CURLE_PEER_FAILED_VERIFICATION (51)" +The remote server's SSL certificate or SSH md5 fingerprint was deemed not OK. .IP "CURLE_GOT_NOTHING (52)" Nothing was returned from the server, and under the circumstances, getting nothing is considered an error. -- cgit v1.2.1 From bffa8355733160e5f0e950beecc97a75ef89c4f5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 4 Oct 2007 22:05:25 +0000 Subject: The new file docs/libcurl/ABI describes how we view ABI breakages, soname bumps and what the version number's significance to all that is. --- docs/libcurl/ABI | 51 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/libcurl/Makefile.am | 2 +- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 docs/libcurl/ABI (limited to 'docs/libcurl') diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI new file mode 100644 index 000000000..06783b569 --- /dev/null +++ b/docs/libcurl/ABI @@ -0,0 +1,51 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + + libcurl's binary interface + +ABI + + First, allow me to define the word for this context: ABI describes the + low-level interface between an application program a library. Calling + conventions, function arguments, return values, struct sizes/defines and + more. + +Upgrades + + In the vast majority of all cases, a typical libcurl upgrade does not break + the ABI at all. Your application can remain using libcurl just as before, + only with less bugs and possibly with added new features. You need to read + the release notes, and if they mention an ABI break/soname bump, you may + have to verify that your application still builds fine and uses libcurl as + it now is defined to work. + +Version Numbers + + In libcurl land, you really can't tell by the libcurl version number if that + libcurl is binary compatible or not with another libcurl version. + +Soname Bumps + + Whenever there are changes done to the library that will cause an ABI + breakage, that may require your application to get attention or possibly be + changed to adhere to new things, we will bump the soname. Then the library + will get a different output name and thus can in fact be installed in + parallell with an older installed lib (on most systems). Thus, old + applications built against the previous ABI version will remain working and + using the older lib, while newer applications build and use the newer one. + + During the first seven years of libcurl releases, there have only been four + ABI breakages. + +Downgrades + + Going to an older libcurl version from one you're currently using can be a + tricky thing. Mostly we add features and options to newer libcurls as that + won't break ABI or hamper existing applications. This has the implication + that going backwards may get you in a situation where you pick a libcurl + that doesn't support the options your application needs. Or possibly you + even downgrade so far so you cross an ABI break border and thus a different + soname, and then your application may need to adapt to the modified ABI. diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index ea96cea1d..dbc04ce57 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -57,7 +57,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI MAN2HTML= roffit --mandir=. < $< >$@ -- cgit v1.2.1 From 4449bd9b4dffc67b4c0597414d816a123e9a98e5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 5 Oct 2007 14:37:33 +0000 Subject: Michael Wallner made the CULROPT_COOKIELIST option support a new magic string: "FLUSH". Using that will cause libcurl to flush its cookies to the CURLOPT_COOKIEJAR file. --- docs/libcurl/curl_easy_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ac460ae09..05895492e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -810,7 +810,9 @@ format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL cookie engine was not enabled it will enable its cookie engine. Passing a magic string \&"ALL" will erase all cookies known by cURL. (Added in 7.14.1) Passing the special string \&"SESS" will only erase all session cookies known -by cURL. (Added in 7.15.4) +by cURL. (Added in 7.15.4) Passing the special string \&"FLUSH" will write +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 non-zero, this forces the HTTP request to get back to GET. usable if a POST, HEAD, PUT or a custom request have been used -- cgit v1.2.1 From 606af3024bed86777ce2a9fee98bf0d233127cd6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 5 Oct 2007 15:16:18 +0000 Subject: Alexey Pesternikov documented CURLOPT_OPENSOCKETDATA and CURLOPT_OPENSOCKETFUNCTION --- docs/libcurl/curl_easy_setopt.3 | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 05895492e..c39ba12e3 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -184,6 +184,30 @@ unrecoverable error to the library and it will close the socket and return Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. (Option added in 7.15.6.) +.IP CURLOPT_OPENSOCKETFUNCTION +Function pointer that should match the \fIcurl_opensocket_callback\fP +prototype found in \fI\fP. This function gets called by libcurl +instead of the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument +identifies the exact purpose for this particular socket, and currently only +one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the primary connection +(meaning the control connection in the FTP case). Future versions of libcurl +may support more purposes. It passes the resolved peer address as a +\fIaddress\fP argument so the callback can modify the address or refuse to +connect at all. The callback function should return the socket or +\fICURL_SOCKET_BAD\fP in case no connection should be established or any error +detected. Any additional \fIsetsockopt(2)\fP calls can be done on the socket +at the user's discretion. \fICURL_SOCKET_BAD\fP return value from the +callback function will signal an unrecoverable error to the library and it +will return \fICURLE_COULDNT_CONNECT\fP. This return code can be used for IP +address blacklisting. The default behavior is: +.Bd -literal -offset indent + return socket(addr->family, addr->socktype, addr->protocol); +.Ed +(Option added in 7.17.1.) +.IP CURLOPT_OPENSOCKETDATA +Pass a pointer that will be untouched by libcurl and passed as the first +argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP. +(Option added in 7.17.1.) .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of -- cgit v1.2.1 From 83f385acf39ca5f4d2f4754f85f1171f8a1249b8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 5 Oct 2007 15:18:34 +0000 Subject: add url to the wikipedia article for a longer description --- docs/libcurl/ABI | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI index 06783b569..5ed97da5a 100644 --- a/docs/libcurl/ABI +++ b/docs/libcurl/ABI @@ -6,13 +6,16 @@ libcurl's binary interface -ABI +ABI - Application Binary Interface First, allow me to define the word for this context: ABI describes the low-level interface between an application program a library. Calling conventions, function arguments, return values, struct sizes/defines and more. + For a longer descricption, see + http://en.wikipedia.org/wiki/Application_binary_interface + Upgrades In the vast majority of all cases, a typical libcurl upgrade does not break -- cgit v1.2.1 From fc70b2f916c21bb31067b2fd95fbb088e60b90f0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Oct 2007 14:53:50 +0000 Subject: Add a paragraph about CURLOPT_CUSTOMREQUEST not actually changing libcurl's behavior, it only changes the actual request method keyword and this is not always what the user/app wants. --- docs/libcurl/curl_easy_setopt.3 | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c39ba12e3..7c546d6a6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1063,12 +1063,19 @@ option to -1 to make the transfer start from the end of the target file Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST -Pass a pointer to a zero terminated string as parameter. It will be user +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 more or less obscure HTTP requests. Don't do this at will, make sure your server supports the command first. +Note that libcurl will still act and assume the keyword it would use if you +didn't set your custom one is the one in use and it will act according to +that. Thus, changing this to a HEAD when libcurl otherwise would do a GET +might cause libcurl to act funny, and similar. To switch to a proper HEAD, use +\fICURLOPT_NOBODY\fP, to switch to a proper POST, use \fICURLOPT_POST\fP or +\fICURLOPT_POSTFIELDS\fP and so on. + Restore to the internal default by setting this to NULL. Many people have wrongly used this option to replace the entire request with -- cgit v1.2.1 From a005243908803662d4a05427bc1061db42f4d057 Mon Sep 17 00:00:00 2001 From: Patrick Monnerat Date: Mon, 15 Oct 2007 18:32:01 +0000 Subject: Fix dynamic CURLOPT_POSTFIELDS bug: back to static. CURLOPT_COPYPOSTFIELDS option added for dynamic. Fix some OS400 features. --- docs/libcurl/curl_easy_setopt.3 | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7c546d6a6..b5a0b270e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -386,8 +386,7 @@ POST/PUT and a 401 or 407 is received immediately afterwards. .SH NETWORK OPTIONS .IP CURLOPT_URL The actual URL to deal with. The parameter should be a char * to a zero -terminated string. The string must remain present until curl no longer needs -it, as it doesn't copy the string. +terminated string. If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will attempt to guess which protocol to use based on the given host name. If the @@ -662,14 +661,16 @@ also make the library use the a "Content-Type: application/x-www-form-urlencoded" header. (This is by far the most commonly used POST method). -Use the \fICURLOPT_POSTFIELDS\fP option to specify what data to post and -\fICURLOPT_POSTFIELDSIZE\fP to set the data size. +Use one of \fICURLOPT_POSTFIELDS\fP or \fICURLOPT_COPYPOSTFIELDS\fP options to +specify what data to post and \fICURLOPT_POSTFIELDSIZE\fP or +\fICURLOPT_POSTFIELDSIZE_LARGE\fP to set the data size. Optionally, you can provide data to POST using the \fICURLOPT_READFUNCTION\fP and \fICURLOPT_READDATA\fP options but then you must make sure to not set \fICURLOPT_POSTFIELDS\fP to anything but NULL. When providing data with a callback, you must transmit it using chunked transfer-encoding or you must set -the size of the data with the \fICURLOPT_POSTFIELDSIZE\fP option. +the size of the data with the \fICURLOPT_POSTFIELDSIZE\fP or +\fICURLOPT_POSTFIELDSIZE_LARGE\fP option. You can override the default POST Content-Type: header by setting your own with \fICURLOPT_HTTPHEADER\fP. @@ -690,11 +691,14 @@ If you issue a POST request and then want to make a HEAD or GET using the same re-used handle, you must explicitly set the new request type using \fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. .IP CURLOPT_POSTFIELDS -Pass a char * as parameter, which should be the full data to post in an HTTP +Pass a void * as parameter, which should be the full data to post in an HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded. Take note. +The pointed data are NOT copied by the library: as a consequence, they must +be preserved by the calling application until the transfer finishes. + This POST is a normal application/x-www-form-urlencoded kind (and libcurl will set that Content-Type by default when this option is used), which is the most commonly used one by HTML forms. See also the \fICURLOPT_POST\fP. Using @@ -721,6 +725,21 @@ Pass a curl_off_t as parameter. Use this to set the size of the \fICURLOPT_POSTFIELDS\fP data to prevent libcurl from doing strlen() on the data to figure out the size. This is the large file version of the \fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1) +.IP CURLOPT_COPYPOSTFIELDS +Pass a char * as parameter, which should be the full data to post in an HTTP +POST operation. It behaves has the \fICURLOPT_POSTFIELDS\fP option, but the +original data are copied by the library, allowing the application to overwrite +the original data after setting this option. + +Because data are copied, care must be taken when using this option in +conjunction with \fICURLOPT_POSTFIELDSIZE\fP or +\fICURLOPT_POSTFIELDSIZE_LARGE\fP: If the size has not been set prior to +\fICURLOPT_COPYPOSTFIELDS\fP, the data are assumed to be a null-terminated +string; else the stored size informs the library about the data byte count to +copy. In any case, the size must not be changed after +\fICURLOPT_COPYPOSTFIELDS\fP, unless another \fICURLOPT_POSTFIELDS\fP or +\fICURLOPT_COPYPOSTFIELDS\fP option is issued. + .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 -- cgit v1.2.1 From a83b5d1b675442d384b46a8fb8404e46c9e5f449 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Mon, 15 Oct 2007 21:19:40 +0000 Subject: Mention first version with CURLOPT_COPYPOSTFIELDS. Don't confuse NUL with NULL. --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- docs/libcurl/curl_formadd.3 | 6 +++--- 2 files changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b5a0b270e..8bdcf2172 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -727,18 +727,19 @@ data to figure out the size. This is the large file version of the \fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1) .IP CURLOPT_COPYPOSTFIELDS Pass a char * as parameter, which should be the full data to post in an HTTP -POST operation. It behaves has the \fICURLOPT_POSTFIELDS\fP option, but the +POST operation. It behaves as the \fICURLOPT_POSTFIELDS\fP option, but the original data are copied by the library, allowing the application to overwrite the original data after setting this option. Because data are copied, care must be taken when using this option in conjunction with \fICURLOPT_POSTFIELDSIZE\fP or \fICURLOPT_POSTFIELDSIZE_LARGE\fP: If the size has not been set prior to -\fICURLOPT_COPYPOSTFIELDS\fP, the data are assumed to be a null-terminated +\fICURLOPT_COPYPOSTFIELDS\fP, the data are assumed to be a NUL-terminated string; else the stored size informs the library about the data byte count to copy. In any case, the size must not be changed after \fICURLOPT_COPYPOSTFIELDS\fP, unless another \fICURLOPT_POSTFIELDS\fP or \fICURLOPT_COPYPOSTFIELDS\fP option is issued. +(Added in 7.17.1) .IP CURLOPT_HTTPPOST Tells libcurl you want a multipart/formdata HTTP POST to be made and you diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index a94dd506f..8508dd411 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -44,7 +44,7 @@ parts. .IP CURLFORM_COPYNAME followed by a string which provides the \fIname\fP of this part. libcurl copies the string so your application doesn't need to keep it around after -this function call. If the name isn't null terminated, or if you'd +this function call. If the name isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by \fIcurl_formfree(3)\fP. @@ -53,7 +53,7 @@ like it to contain zero bytes, you must set its length with followed by a string which provides the \fIname\fP of this part. libcurl will use the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. If the name -isn't null terminated, or if you'd like it to contain zero +isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. .IP CURLFORM_COPYCONTENTS @@ -68,7 +68,7 @@ data will be freed by \fIcurl_formfree(3)\fP. followed by a pointer to the contents of this part, the actual data to send away. libcurl will use the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. -If the data isn't null terminated, or if you'd like it to contain zero bytes, +If the data isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. .IP CURLFORM_CONTENTSLENGTH -- cgit v1.2.1 From e2b2a84497ca8a4460397e69be2c7fa1a37d6453 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 20 Nov 2007 23:16:19 +0000 Subject: clarify somewhat what happens to some data when a share is set to be used --- docs/libcurl/curl_easy_setopt.3 | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8bdcf2172..bda3fecd2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1491,6 +1491,14 @@ this curl handle use the data from the shared handle instead of keeping the data to itself. This enables several curl handles to share data. If the curl handles are used simultaneously, you \fBMUST\fP use the locking methods in the 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 +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 +way, as if no share was used. .IP CURLOPT_NEW_FILE_PERMS 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 -- cgit v1.2.1 From 1c93e75375882ed309c7d93a1ce59d27a53f23d3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 2 Dec 2007 23:38:23 +0000 Subject: Michal Marek introduced CURLOPT_PROXY_TRANSFER_MODE which is used to control the appending of the "type=" thing on FTP URLs when they are passed to a HTTP proxy. Some proxies just don't like that appending (which is done unconditionally in 7.17.1), and some proxies treat binary/ascii transfers better with the appending done! --- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index bda3fecd2..1f628d0c5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1064,6 +1064,13 @@ 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. +.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 +appending ;type=a or ;type=i to the URL. Without this setting, or it being +set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when +doing FTP via a proxy. Beware that not all proxies support this feature. +(Added in 7.17.2) .IP CURLOPT_CRLF Convert Unix newlines to CRLF newlines on transfers. .IP CURLOPT_RANGE -- cgit v1.2.1 From f8172f85b1c09554fc4134c4fc972bcfe4c7a9aa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 6 Dec 2007 22:36:52 +0000 Subject: clarify that when curl_multi_timeout() returns -1 it just means that there is no current timeout. It does not mean wait forever and it does not mean do not wait at all. It means there is no timeout value known at this point in time. --- docs/libcurl/curl_multi_timeout.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index b04acf890..fbdb8fb03 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -23,6 +23,10 @@ The timeout value returned in the long \fBtimeout\fP points to, is in number of milliseconds at this very moment. If 0, it means you should proceed immediately without waiting for anything. If it returns -1, there's no timeout at all set. + +Note: if libcurl returns a -1 timeout here, it just means that libcurl +currently has no stored timeout value. You must not wait too long (more than a +few seconds perhaps) before you call curl_multi_perform() again. .SH "RETURN VALUE" The standard CURLMcode for multi interface error codes. .SH "TYPICAL USAGE" -- cgit v1.2.1 From 8cdff55b8065faf019a453475868b0baf934244c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 8 Dec 2007 22:52:39 +0000 Subject: mention how to enable chunked encoding for POSTs --- docs/libcurl/curl_easy_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 1f628d0c5..2016ffc2e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -670,7 +670,9 @@ and \fICURLOPT_READDATA\fP options but then you must make sure to not set \fICURLOPT_POSTFIELDS\fP to anything but NULL. When providing data with a callback, you must transmit it using chunked transfer-encoding or you must set the size of the data with the \fICURLOPT_POSTFIELDSIZE\fP or -\fICURLOPT_POSTFIELDSIZE_LARGE\fP option. +\fICURLOPT_POSTFIELDSIZE_LARGE\fP option. To enable chunked encoding, you +simply pass in the appropriate Transfer-Encoding header, see the +post-callback.c example. You can override the default POST Content-Type: header by setting your own with \fICURLOPT_HTTPHEADER\fP. -- cgit v1.2.1 From 92eae30f4d9b8ea204bb56d6fbeb244561169e3a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 11 Dec 2007 21:19:38 +0000 Subject: clarify that the CURLMOPT_TIMERFUNCTION callback can pass in 0 and -1 as legal values and what they mean --- docs/libcurl/curl_multi_setopt.3 | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index f05ba2d36..7053735f5 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -47,10 +47,11 @@ changes. The timeout value is at what latest time the application should call one of the \&"performing" functions of the multi interface (\fIcurl_multi_socket(3)\fP, \fIcurl_multi_socket_all(3)\fP and \fIcurl_multi_perform(3)\fP) - to allow libcurl to keep timeouts and retries -etc to work. Libcurl attempts to limit calling this only when the fixed future -timeout time actually change. See also \fICURLMOPT_TIMERDATA\fP. This callback -can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP. (Added -in 7.16.0) +etc to work. A timeout value of -1 means that there is no timeout at all, and +0 means that the timeout is already reached. Libcurl attempts to limit calling +this only when the fixed future timeout time actually change. See also +\fICURLMOPT_TIMERDATA\fP. This callback can be used instead of, or in addition +to, \fIcurl_multi_timeout(3)\fP. (Added in 7.16.0) .IP CURLMOPT_TIMERDATA Pass a pointer to whatever you want passed to the \fBcurl_multi_timer_callback\fP's third argument, the userp pointer. This is -- cgit v1.2.1 From a46b40b7fdf567250451b984b977f5e03c716d5e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 2 Jan 2008 21:40:11 +0000 Subject: Richard Atterer brought a patch that added support for SOCKS4a proxies, which is an inofficial PROXY4 variant that sends the hostname to the proxy instead of the resolved address (which is already supported by SOCKS5). --socks4a is the curl command line option for it and CURLOPT_PROXYTYPE can now be set to CURLPROXY_SOCKS4A as well. --- docs/libcurl/curl_easy_setopt.3 | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2016ffc2e..cc2af682e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -430,8 +430,9 @@ Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. .IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for -this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2) -\fICURLPROXY_SOCKS5\fP. The HTTP type is default. (Added in 7.10) +this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2), +\fICURLPROXY_SOCKS5\fP and \fICURLPROXY_SOCKS4A\fP (added in 7.17.2). The HTTP +type is default. (Added in 7.10) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy -- cgit v1.2.1 From 2e42b0a252416803a90ea232dc94a0a21d5a97e5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 4 Jan 2008 23:01:00 +0000 Subject: Based on Maxim Perenesenko's patch, we now do SOCKS5 operations and let the proxy do the host name resolving and only if --socks5ip (or CURLOPT_SOCKS5_RESOLVE_LOCAL) is used we resolve the host name locally and pass on the IP address only to the proxy. --- docs/libcurl/curl_easy_setopt.3 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index cc2af682e..299ac3ebb 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "30 Aug 2007" "libcurl 7.17.0" "libcurl Manual" +.TH curl_easy_setopt 3 "4 Jan 2008" "libcurl 7.17.2" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -433,11 +433,19 @@ Pass a long with this option to set type of the proxy. Available options for this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5\fP and \fICURLPROXY_SOCKS4A\fP (added in 7.17.2). The HTTP type is default. (Added in 7.10) + +See also \fIURLOPT_SOCKS5_RESOLVE_LOCAL\fP. .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations through a 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_SOCKS5_RESOLVE_LOCAL +Set the parameter to 1 to get the library to resolve the host name locally +instead of passing it to the proxy to resolve, when using a SOCKS5 proxy. + +Note that libcurl before 7.17.2 always resolved the host name locally even +when SOCKS5 was used. (Added in 7.17.2) .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 -- cgit v1.2.1 From b4305764367f24f06ce7dedc557d90772a00eec1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 5 Jan 2008 22:04:18 +0000 Subject: Based on further discussion on curl-library, I reverted yesterday's SOCKS5 code to instead introduce support for a new proxy type called CURLPROXY_SOCKS5_HOSTNAME that is used to send the host name to the proxy instead of IP address and there's thus no longer any need for a new curl_easy_setopt() option. The default SOCKS5 proxy is again back to sending the IP address to the proxy. The new curl command line option for enabling sending host name to a SOCKS5 proxy is now --socks5-hostname. --- docs/libcurl/curl_easy_setopt.3 | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 299ac3ebb..05289e9de 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "4 Jan 2008" "libcurl 7.17.2" "libcurl Manual" +.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.17.2" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -431,10 +431,9 @@ specified in the proxy string \fICURLOPT_PROXY\fP. .IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2), -\fICURLPROXY_SOCKS5\fP and \fICURLPROXY_SOCKS4A\fP (added in 7.17.2). The HTTP -type is default. (Added in 7.10) - -See also \fIURLOPT_SOCKS5_RESOLVE_LOCAL\fP. +\fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.17.2) and +\fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.17.2). The HTTP type is +default. (Added in 7.10) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy -- cgit v1.2.1 From de23b98522991dbc1f2c184216d9f73bead83895 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 8 Jan 2008 14:52:05 +0000 Subject: Introducing curl_easy_pause() and new magic return codes for both the read and the write callbacks that now can make a connection's reading and/or writing get paused. --- docs/libcurl/Makefile.am | 7 +++-- docs/libcurl/curl_easy_pause.3 | 63 +++++++++++++++++++++++++++++++++++++++++ docs/libcurl/curl_easy_setopt.3 | 20 +++++++++---- 3 files changed, 81 insertions(+), 9 deletions(-) create mode 100644 docs/libcurl/curl_easy_pause.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index dbc04ce57..9bf8e99c7 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -18,7 +18,8 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ - curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 + curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \ + curl_easy_pause.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -36,7 +37,7 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \ curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \ curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \ - curl_formget.html curl_multi_assign.html + curl_formget.html curl_multi_assign.html curl_easy_pause.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \ @@ -53,7 +54,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \ curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \ - curl_formget.pdf curl_multi_assign.pdf + curl_formget.pdf curl_multi_assign.pdf curl_easy_pause.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3 new file mode 100644 index 000000000..247b39c27 --- /dev/null +++ b/docs/libcurl/curl_easy_pause.3 @@ -0,0 +1,63 @@ +.\" $Id$ +.\" +.TH curl_easy_pause 3 "17 Dec 2007" "libcurl 7.18.0" "libcurl Manual" +.SH NAME +curl_easy_pause - pause and unpause a connection +.SH SYNOPSIS +.B #include + +.BI "CURLcode curl_easy_pause(CURL *"handle ", int "bitmask " );" + +.SH DESCRIPTION +Using this function, you can explicitly mark a running connection to get +paused, and you can unpause a connection that was previously paused. + +A connection can made to pause by using this function or by letting the read +or the write callbacks return the proper magic return code +(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). + +NOTE: while it may feel tempting, take care and notice that you cannot call +this function from another thread. + +When this function is called to unpause reading, the chance is high that you +will get your write callback called before this function returns. + +The \fBhandle\fP argument is of course identifying the handle that operates on +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 +this function is called again without this bit set. Thus, the write callback +(\fICURLOPT_WRITEFUNCTION\fP) won't be called. +.IP CURLPAUSE_SEND +Pause sending data. There will be no data sent on this connection until this +function is called again without this bit set. Thus, the read callback +(\fICURLOPT_READFUNCTION\fP) won't be called. +.IP CURLPAUSE_ALL +Convenience define that pauses both directions. +.IP CURLPAUSE_CONT +Convenience define that unpauses both directions +.SH RETURN VALUE +CURLE_OK (zero) means that the option was set properly, and a non-zero return +code means something wrong occurred after the new state was set. See the +\fIlibcurl-errors(3)\fP man page for the full list with descriptions. +.SH AVAILABILITY +This function was added in libcurl 7.18.0. Before this version, there was no +explicit support for pausing transfers. +.SH "MEMORY USE" +When pausing a read by returning the magic return code from a write callback, +the read data is already in libcurl's internal buffers so it'll have to keep +it in an allocated buffer until the reading is again unpaused using this +function. + +If the downloaded data is compressed and is asked to get uncompressed +automatially on download, libcurl will continue to uncompress the entire +downloaded chunk and it will cache the data uncompressed. This has the side- +effect that if you download something that is compressed a lot, it can result +in a very large data amount needing to be allocated to save the data during +the pause. This said, you should probably consider not using paused reading if +you allow libcurl to uncompress data automatically. +.SH "SEE ALSO" +.BR curl_easy_cleanup "(3), " curl_easy_reset "(3)" diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 05289e9de..96f2d2b2c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.17.2" "libcurl Manual" +.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.18.0" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -95,6 +95,10 @@ of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library and it will abort the transfer and return \fICURLE_WRITE_ERROR\fP. +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 empty. @@ -142,6 +146,10 @@ The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error code from the transfer (Added in 7.12.1) +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 internal read function will be used. It is simply doing an fread() on the FILE * stream set with \fICURLOPT_READDATA\fP. @@ -431,8 +439,8 @@ specified in the proxy string \fICURLOPT_PROXY\fP. .IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2), -\fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.17.2) and -\fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.17.2). The HTTP type is +\fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and +\fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is default. (Added in 7.10) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to non-zero to get the library to tunnel all operations @@ -443,8 +451,8 @@ don't want this tunneling option. Set the parameter to 1 to get the library to resolve the host name locally instead of passing it to the proxy to resolve, when using a SOCKS5 proxy. -Note that libcurl before 7.17.2 always resolved the host name locally even -when SOCKS5 was used. (Added in 7.17.2) +Note that libcurl before 7.18.0 always resolved the host name locally even +when SOCKS5 was used. (Added in 7.18.0) .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 @@ -1080,7 +1088,7 @@ transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by appending ;type=a or ;type=i to the URL. Without this setting, or it being set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing FTP via a proxy. Beware that not all proxies support this feature. -(Added in 7.17.2) +(Added in 7.18.0) .IP CURLOPT_CRLF Convert Unix newlines to CRLF newlines on transfers. .IP CURLOPT_RANGE -- cgit v1.2.1 From 18faa509403c39b4914114cfe2966241b62b2959 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 10 Jan 2008 10:30:19 +0000 Subject: Georg Lippitsch brought CURLOPT_SEEKFUNCTION and CURLOPT_SEEKDATA to allow libcurl to seek in a given input stream. This is particularly important when doing upload resumes when there's already a huge part of the file present remotely. Before, and still if this callback isn't used, libcurl will read and through away the entire file up to the point to where the resuming begins (which of course can be a slow opereration depending on file size, I/O bandwidth and more). This new function will also be preferred to get used instead of the CURLOPT_IOCTLFUNCTION for seeking back in a stream when doing multi-stage HTTP auth with POST/PUT. --- docs/libcurl/curl_easy_setopt.3 | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 96f2d2b2c..56b763fe7 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -171,11 +171,32 @@ something special I/O-related needs to be done that the library can't do by itself. For now, rewinding the read data stream is the only action it can request. The rewinding of the read data stream may be necessary when doing a HTTP PUT or POST with a multi-pass authentication method. (Option added in -7.12.3) +7.12.3). + +Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking! .IP CURLOPT_IOCTLDATA Pass a pointer that will be untouched by libcurl and passed as the 3rd argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP. (Option added in 7.12.3) +.IP CURLOPT_SEEKFUNCTION +Function pointer that should match the following prototype: \fIint +function(void *instream, curl_off_t offset, int origin);\fP This function gets +called by libcurl to seek to a certain position in the input stream and can be +used to fast forward a file in a resumed upload (instead of reading all +uploaded bytes with the normal read function/callback). It is also called to +rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication +method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET, +SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl +only passes SEEK_SET. The callback must return 0 on success as returning +non-zero will cause the upload operation to fail. + +If you forward the input arguments directly to "fseek" or "lseek", note that +the data type for \fIoffset\fP is not the same as defined for curl_off_t on +many systems! (Option added in 7.18.0) +.IP CURLOPT_SEEKDATA +Data pointer to pass to the file read function. If you use the +\fICURLOPT_SEEKFUNCTION\fP option, this is the pointer you'll get as input. If +you don't specify a seek callback, NULL is passed. (Option added in 7.18.0) .IP CURLOPT_SOCKOPTFUNCTION Function pointer that should match the \fIcurl_sockopt_callback\fP prototype found in \fI\fP. This function gets called by libcurl after the -- cgit v1.2.1 From 08adf679691006a8fc45fca07c7a10e6a458283e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 11 Jan 2008 14:20:41 +0000 Subject: Daniel Egger made CURLOPT_RANGE work on file:// URLs the very same way it already worked for FTP:// URLs --- docs/libcurl/curl_easy_setopt.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 56b763fe7..dec4371e1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1119,6 +1119,8 @@ transfers also support several intervals, separated with commas as in \fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation techniques). Pass a NULL to this option to disable the use of ranges. + +Ranges work on HTTP, FTP and FILE (since 7.18.0) transfers only. .IP CURLOPT_RESUME_FROM Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. Set this option to 0 to make the transfer -- cgit v1.2.1 From ed0a413711f890b1a4e95e26ecccb71cef9b793c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 3 Feb 2008 10:10:00 +0000 Subject: it is stable now... --- docs/libcurl/curl_multi_timeout.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index fbdb8fb03..7302e0ac4 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -34,7 +34,7 @@ Call \fBcurl_multi_timeout(3)\fP, then wait for action on the sockets. You figure out which sockets to wait for by calling \fBcurl_multi_fdset(3)\fP or by a previous call to \fBcurl_multi_socket(3)\fP. .SH AVAILABILITY -This function was added in libcurl 7.15.4, although not deemed stable yet. +This function was added in libcurl 7.15.4. .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " -- cgit v1.2.1 From f9a60620818b6a19ebe3e6f15e1b57d7012e6fb0 Mon Sep 17 00:00:00 2001 From: Gunter Knauf Date: Tue, 19 Feb 2008 23:10:07 +0000 Subject: applied patch to disable SSLv2 by default; discussion: http://sourceforge.net/tracker/index.php?func=detail&aid=1767276&group_id=976&atid=350976 Submitted by Kaspar Brand. --- docs/libcurl/curl_easy_setopt.3 | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index dec4371e1..0da9d20bf 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1379,10 +1379,9 @@ Pass a long as parameter to control what version of SSL/TLS to attempt to use. The available options are: .RS .IP CURL_SSLVERSION_DEFAULT -The default action. When libcurl built with OpenSSL or NSS, this will attempt -to figure out the remote SSL protocol version. Unfortunately there are a lot of -ancient and broken servers in use which cannot handle this technique and will -fail to connect. When libcurl is built with GnuTLS, this will mean SSLv3. +The default action. This will attempt to figure out the remote SSL protocol +version, i.e. either SSLv3 or TLSv1 (but not SSLv2, which became disabled +by default with 7.18.1). .IP CURL_SSLVERSION_TLSv1 Force TLSv1 .IP CURL_SSLVERSION_SSLv2 -- cgit v1.2.1 From 4957a838ef72b0c65c87b160ce75efac1fa2e475 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 6 Mar 2008 12:37:07 +0000 Subject: curl_multi_timeout() is really not recommended with curl_multi_socket()-based usage --- docs/libcurl/curl_multi_socket.3 | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index f8587fdee..485f482f9 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -45,15 +45,18 @@ 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 this function was called. -To force libcurl to (re-)check all its internal sockets and transfers instead -of just a single one, you call \fBcurl_multi_socket_all(3)\fP. This is -typically done as the first function call before the application has any -knowledge about what sockets libcurl uses. - -Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to -wait for socket actions \- at most \- before doing the timeout action: call -the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to -CURL_SOCKET_TIMEOUT. +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. This is typically +done as the first function call before the application has any knowledge about +what sockets libcurl uses. + +Get the timeout time - how long to wait for socket actions at most before +doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with +the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT, by setting the +\fICURLMOPT_TIMERFUNCTION\fP option with \fIcurl_multi_setopt(3)\fP. You can +also use the \fIcurl_multi_timeout(3)\fP function to poll the value at any +given time, but for an event-based system using the callback is far better +than relying on polling the timeout value. Usage of \fIcurl_multi_socket(3)\fP is depricated, whereas the function is equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set -- cgit v1.2.1 From 1cf559492ac81d0533757cb36bb002cb6829d81b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 6 Mar 2008 12:43:47 +0000 Subject: spellchecked --- docs/libcurl/curl_multi_socket.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 485f482f9..12914fa61 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -27,7 +27,7 @@ application has detected action on a socket handled by libcurl, it should call socket with the action. When the events on a socket are known, they can be passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of events to be -choosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the +chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and libcurl will test the descriptor internally. @@ -58,7 +58,7 @@ also use the \fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but for an event-based system using the callback is far better than relying on polling the timeout value. -Usage of \fIcurl_multi_socket(3)\fP is depricated, whereas the function is +Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set to 0. @@ -94,7 +94,7 @@ register, interested in write readiness .IP "CURL_POLL_INOUT (3)" register, interested in both read and write readiness .IP "CURL_POLL_REMOVE (4)" -deregister +unregister .RE The \fIsocketp\fP argument is a private pointer you have previously set with @@ -134,7 +134,7 @@ them for activity. This can be done through your application code, or by way of an external library such as libevent or glib. 7. Wait for activity on any of libcurl's sockets, use the timeout value your -calback has been told +callback has been told 8, When activity is detected, call curl_multi_socket_action() for the socket(s) that got action. If no activity is detected and the timeout expires, -- cgit v1.2.1 From 7a8a20416fd7648686f05d14947ccdab44c6780c Mon Sep 17 00:00:00 2001 From: Michal Marek Date: Tue, 11 Mar 2008 07:37:40 +0000 Subject: - Added a type checking macro for curl_easy_setopt(), needs gcc-4.3 and only works in C mode atm (http://curl.haxx.se/mail/lib-2008-02/0267.html , http://curl.haxx.se/mail/lib-2008-02/0292.html ) --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0da9d20bf..4c6e795b5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1374,6 +1374,11 @@ operations. If the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is returned. + +Note that even though this option doesn't need any parameter, in some +configurations \fIcurl_easy_setopt\fP might be defined as a macro taking +exactly three arguments. Therefore, it's recommended to pass a dummy value as +parameter. .IP CURLOPT_SSLVERSION Pass a long as parameter to control what version of SSL/TLS to attempt to use. The available options are: -- cgit v1.2.1 From 9b48991ebd855efaeefc2a64c3e818465751db6a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 11 Mar 2008 12:18:00 +0000 Subject: Recommend passing a 1 as parameter to CURLOPT_SSLENGINE_DEFAULT rather than a "dummy" just to get things as fixed as possible in case we ever get the urge to change this to actually mean something. --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4c6e795b5..eb800e393 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1377,8 +1377,8 @@ returned. Note that even though this option doesn't need any parameter, in some configurations \fIcurl_easy_setopt\fP might be defined as a macro taking -exactly three arguments. Therefore, it's recommended to pass a dummy value as -parameter. +exactly three arguments. Therefore, it's recommended to pass 1 as parameter to +this option. .IP CURLOPT_SSLVERSION Pass a long as parameter to control what version of SSL/TLS to attempt to use. The available options are: -- cgit v1.2.1 From a782c3e3681eb7aef0b29d2a40d3544666a91c7c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 25 Mar 2008 19:17:26 +0000 Subject: spell it out loudly and clearly that CURLOPT_SSL_CTX_FUNCTION is only functional if libcurl is built against OpenSSL --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index eb800e393..bcea2466a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -310,6 +310,9 @@ Pass a pointer to whatever you want passed in to your \fICURLOPT_DEBUGFUNCTION\fP in the last void * argument. This pointer is not used by libcurl, it is only passed to the callback. .IP CURLOPT_SSL_CTX_FUNCTION +This option does only function for libcurl powered by OpenSSL. If libcurl was +built against another SSL library, this functionality is absent. + Function pointer that should match the following prototype: \fBCURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called by libcurl just before the initialization of an SSL connection after having -- cgit v1.2.1 From a2314225e02ea2f3bd49dc8557f2452846e49b19 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 31 Mar 2008 10:02:23 +0000 Subject: - Added CURLFORM_STREAM as a supported option to curl_formadd() to allow an application to provide data for a multipart with the read callback. Note that the size needs to be provided with CURLFORM_CONTENTSLENGTH when the stream option is used. This feature is verified by the new test case 554. This feature was sponsored by Xponaut. --- docs/libcurl/curl_formadd.3 | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 8508dd411..f3cea0054 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -38,9 +38,7 @@ parts you want to add to your post. The options listed first are for making normal parts. The options from \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload parts. - .SH OPTIONS - .IP CURLFORM_COPYNAME followed by a string which provides the \fIname\fP of this part. libcurl copies the string so your application doesn't need to keep it around after @@ -48,14 +46,12 @@ this function call. If the name isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by \fIcurl_formfree(3)\fP. - .IP CURLFORM_PTRNAME followed by a string which provides the \fIname\fP of this part. libcurl will use the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. If the name isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. - .IP CURLFORM_COPYCONTENTS followed by a pointer to the contents of this part, the actual data to send away. libcurl copies the provided data, so your application doesn't @@ -63,57 +59,55 @@ need to keep it around after this function call. If the data isn't null terminated, or if you'd like it to contain zero bytes, you must set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data will be freed by \fIcurl_formfree(3)\fP. - .IP CURLFORM_PTRCONTENTS followed by a pointer to the contents of this part, the actual data to send away. libcurl will use the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. If the data isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. - .IP CURLFORM_CONTENTSLENGTH -followed by a long giving the length of the contents. - +followed by a long giving the length of the contents. Note that for +\fICURLFORM_STREAM\fP contents, this option is mandatory. .IP CURLFORM_FILECONTENT followed by a filename, causes that file to be read and its contents used as data in this part. This part does \fInot\fP automatically become a file upload part simply because its data was read from a file. - .IP CURLFORM_FILE followed by a filename, makes this part a file upload part. It sets the \fIfilename\fP field to the basename of the provided filename, it reads the contents of the file and passes them as data and sets the content-type if the given file match one of the internally known file extensions. For \fBCURLFORM_FILE\fP the user may send one or more files in one part by -providing multiple \fBCURLFORM_FILE\fP arguments each followed by the -filename (and each CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE). - +providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename +(and each \fICURLFORM_FILE\fP is allowed to have a +\fICURLFORM_CONTENTTYPE\fP). .IP CURLFORM_CONTENTTYPE is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a string which provides the content-type for this part, possibly instead of an internally chosen one. - .IP CURLFORM_FILENAME is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a string, it tells libcurl to use the given string as the \fIfilename\fP in the file upload part instead of the actual file name. - .IP CURLFORM_BUFFER is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It tells libcurl that the file contents are already present in a buffer. The parameter is a string which provides the \fIfilename\fP field in the content header. - .IP CURLFORM_BUFFERPTR is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer to the buffer to be uploaded. This buffer must not be freed until after \fIcurl_easy_cleanup(3)\fP is called. You must also use \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. - .IP CURLFORM_BUFFERLENGTH is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a long which gives the length of the buffer. - +.IP CURLFORM_STREAM +Tells libcurl to use the \fICURLOPT_READFUNCTION\fP callback to get data. The +parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on to the +read callback's fourth argument. If you want the part to look like a file +upload one, set the \fICURLFORM_FILENAME\fP parameter as well. (Option added +in libcurl 7.18.2) .IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as @@ -121,7 +115,6 @@ its value. Each curl_forms structure element has a CURLformoption and a char pointer. The final element in the array must be a CURLFORM_END. All available options can be used in an array, except the CURLFORM_ARRAY option itself! The last argument in such an array must always be \fBCURLFORM_END\fP. - .IP CURLFORM_CONTENTHEADER specifies extra headers for the form POST section. This takes a curl_slist prepared in the usual way using \fBcurl_slist_append\fP and appends the list -- cgit v1.2.1 From 2dc20b84c1ca1588e40ff8e99ab67dd3ed2dc00e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 9 Apr 2008 11:27:47 +0000 Subject: "tag" the function referals properly --- docs/libcurl/curl_easy_escape.3 | 8 ++++---- docs/libcurl/curl_easy_unescape.3 | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3 index 73c09b4f1..d9ff6222a 100644 --- a/docs/libcurl/curl_easy_escape.3 +++ b/docs/libcurl/curl_easy_escape.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -35,12 +35,12 @@ returns that as a new allocated string. All input characters that are not a-z, A-Z or 0-9 are converted to their "URL escaped" version (%NN where NN is a two-digit hexadecimal number). -If the \fBlength\fP argument is set to 0 (zero), curl_easy_escape() uses -strlen() on the input \fBurl\fP to find out the size. +If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_escape(3)\fP +uses strlen() on the input \fBurl\fP to find out the size. You must \fIcurl_free(3)\fP the returned string when you're done with it. .SH AVAILABILITY -Added in 7.15.4 and replaces the old curl_escape() function. +Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function. .SH RETURN VALUE A pointer to a zero terminated string or NULL if it failed. .SH "SEE ALSO" diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3 index 8870daeab..b3fe5f02b 100644 --- a/docs/libcurl/curl_easy_unescape.3 +++ b/docs/libcurl/curl_easy_unescape.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -36,8 +36,8 @@ and returns that in an allocated memory area. All input characters that are URL encoded (%XX where XX is a two-digit hexadecimal number) are converted to their binary versions. -If the \fBlength\fP argument is set to 0 (zero), curl_easy_unescape() will use -strlen() on the input \fIurl\fP string to find out the size. +If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP +will use strlen() on the input \fIurl\fP string to find out the size. If \fBoutlength\fP is non-NULL, the function will write the length of the returned string in the integer it points to. This allows an escaped string @@ -45,7 +45,7 @@ containing %00 to still get used properly after unescaping. You must \fIcurl_free(3)\fP the returned string when you're done with it. .SH AVAILABILITY -Added in 7.15.4 and replaces the old curl_unescape() function. +Added in 7.15.4 and replaces the old \fIcurl_unescape(3)\fP function. .SH RETURN VALUE A pointer to a zero terminated string or NULL if it failed. .SH "SEE ALSO" -- cgit v1.2.1 From 74bb59fa5792ac1639930a623a42089ee6a6a6d7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 10 Apr 2008 09:03:26 +0000 Subject: clarify the COOKIE option a bit --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index bcea2466a..81dac8d57 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -856,6 +856,10 @@ option and thus you need to concatenate them all in one single string. Set multiple cookies in one string like this: "name1=content1; name2=content2;" etc. +Note that this option sets the cookie header explictly in the outgoing +request(s). If multiple requests are done due to authentication, followed +redirections or similar, they will all get this cookie passed on. + Using this option multiple times will only make the latest string override the previous ones. .IP CURLOPT_COOKIEFILE -- cgit v1.2.1 From 098106b54c1249d050603a70847ad651c491980f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 10 Apr 2008 09:06:47 +0000 Subject: mention what happens to the data when a write callback returns pause --- docs/libcurl/curl_easy_pause.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3 index 247b39c27..ae2ed90a0 100644 --- a/docs/libcurl/curl_easy_pause.3 +++ b/docs/libcurl/curl_easy_pause.3 @@ -14,7 +14,10 @@ paused, and you can unpause a connection that was previously paused. A connection can made to pause by using this function or by letting the read or the write callbacks return the proper magic return code -(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). +(\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback +that returns pause signals to the library that it couldn't take care of any +data at all, and that data will then be delivered again to the callback when +the writing is later unpaused. NOTE: while it may feel tempting, take care and notice that you cannot call this function from another thread. -- cgit v1.2.1 From 852989856d3802a9e7bd2f1e368302d92ddf66e2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 30 Apr 2008 21:20:08 +0000 Subject: - To make it easier for applications that want lots of magic stuff done on redirections and thus cannot use CURLOPT_FOLLOWLOCATION easily, we now introduce the new CURLINFO_REDIRECT_URL option that lets applications extract the URL libcurl would've redirected to if it had been told to. This then enables the application to continue to that URL as it thinks is suitable, without having to re-implement the magic of creating the new URL from the Location: header etc. Test 1029 verifies it. --- docs/libcurl/curl_easy_getinfo.3 | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 95455e3a1..be0f060d4 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -89,6 +89,12 @@ complete execution time for multiple redirections. (Added in 7.9.7) .IP CURLINFO_REDIRECT_COUNT Pass a pointer to a long to receive the total number of redirections that were actually followed. (Added in 7.9.7) +.IP CURLINFO_REDIRECT_URL +Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP +take you to if you would enable CURLOPT_FOLLOWLOCATION. This can come very +handy if you think using the built-in libcurl redirect logic isn't good enough +for you but you would still prefer to avoid implementing all the magic of +figuring out the new URL. (Added in 7.18.2) .IP CURLINFO_SIZE_UPLOAD Pass a pointer to a double to receive the total amount of bytes that were uploaded. -- cgit v1.2.1 From 514592b89207e83d13b5a4e79bc247aa6f74c4b7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 May 2008 21:43:24 +0000 Subject: - Introducing curl_easy_send() and curl_easy_recv(). They can be used to send and receive data over a connection previously setup with curl_easy_perform() and its CURLOPT_CONNECT_ONLY option. The sendrecv.c example was added to show how they can be used. --- docs/libcurl/Makefile.am | 8 +++-- docs/libcurl/curl_easy_recv.3 | 70 +++++++++++++++++++++++++++++++++++++++++++ docs/libcurl/curl_easy_send.3 | 65 ++++++++++++++++++++++++++++++++++++++++ docs/libcurl/index.html | 2 ++ docs/libcurl/libcurl-errors.3 | 6 +++- 5 files changed, 147 insertions(+), 4 deletions(-) create mode 100644 docs/libcurl/curl_easy_recv.3 create mode 100644 docs/libcurl/curl_easy_send.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 9bf8e99c7..9e562c21e 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -19,7 +19,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \ - curl_easy_pause.3 + curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -37,7 +37,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \ curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \ curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \ - curl_formget.html curl_multi_assign.html curl_easy_pause.html + curl_formget.html curl_multi_assign.html curl_easy_pause.html \ + curl_easy_recv.html curl_easy_send.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \ @@ -54,7 +55,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \ curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \ - curl_formget.pdf curl_multi_assign.pdf curl_easy_pause.pdf + curl_formget.pdf curl_multi_assign.pdf curl_easy_pause.pdf \ + curl_easy_recv.pdf curl_easy_send.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_easy_recv.3 b/docs/libcurl/curl_easy_recv.3 new file mode 100644 index 000000000..ea806ff66 --- /dev/null +++ b/docs/libcurl/curl_easy_recv.3 @@ -0,0 +1,70 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** +.\" +.TH curl_easy_recv 3 "29 April 2008" "libcurl 7.18.2" "libcurl Manual" +.SH NAME +curl_easy_recv - receives raw data on an "easy" connection +.SH SYNOPSIS +.B #include +.sp +.BI "CURLcode curl_easy_recv( CURL *" curl ", void *" buffer "," +.BI "size_t " buflen ", size_t *" n ");" +.ad +.SH DESCRIPTION +This function receives raw data from the established connection. You may use +it together with \fIcurl_easy_send(3)\fP to implement custom protocols using +libcurl. This functionality can be particularly useful if you use proxies +and/or SSL encryption: libcurl will take care of proxy negotiation and +connection set-up. + +\fBbuffer\fP is a pointer to your buffer that will get the received +data. \fBbuflen\fP is the maximum amount of data you can get in that +buffer. The variable \fBn\fP points to will receive the number of received +bytes. + +To establish the connection, set \fBCURLOPT_CONNECT_ONLY\fP option before +calling \fIcurl_easy_perform(3)\fP. Note that \fIcurl_easy_recv(3)\fP does not +work on connections that were created without this option. + +You must ensure that the socket has data to read before calling +\fIcurl_easy_recv(3)\fP, otherwise the call will return \fBCURLE_AGAIN\fP - +the socket is used in non-blocking mode internally. Use +\fIcurl_easy_getinfo(3)\fP with \fBCURLINFO_LASTSOCKET\fP to obtain the +socket; use your operating system facilities like \fIselect(2)\fP to check if +it has any data you can read. +.SH AVAILABILITY +Added in 7.18.2. +.SH RETURN VALUE +On success, returns \fBCURLE_OK\fP, stores the received data into +\fBbuffer\fP, and the number of bytes it actually read into \fB*n\fP. + +On failure, returns the appropriate error code. + +If there is no data to read, the function returns \fBCURLE_AGAIN\fP. Use +your operating system facilities to wait until the data is ready, and retry. +.SH EXAMPLE +See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example. +.SH "SEE ALSO" +.BR curl_easy_setopt "(3), " curl_easy_perform "(3), " +.BR curl_easy_getinfo "(3), " +.BR curl_easy_send "(3) " diff --git a/docs/libcurl/curl_easy_send.3 b/docs/libcurl/curl_easy_send.3 new file mode 100644 index 000000000..60a97b29d --- /dev/null +++ b/docs/libcurl/curl_easy_send.3 @@ -0,0 +1,65 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** +.\" +.TH curl_easy_send 3 "29 April 2008" "libcurl 7.18.2" "libcurl Manual" +.SH NAME +curl_easy_send - sends raw data over an "easy" connection +.SH SYNOPSIS +.B #include +.sp +.BI "CURLcode curl_easy_send( CURL *" curl ", const void *" buffer "," +.BI " size_t " buflen ", size_t *" n ");" +.ad +.SH DESCRIPTION +This function sends arbitrary data over the established connection. You may +use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols +using libcurl. This functionality can be particularly useful if you use +proxies and/or SSL encryption: libcurl will take care of proxy negotiation and +connection set-up. + +\fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want sent. +The variable \fBn\fP points to will receive the number of sent bytes. + +To establish the connection, set \fBCURLOPT_CONNECT_ONLY\fP option before +calling \fIcurl_easy_perform(3)\fP. Note that \fIcurl_easy_send(3)\fP will not +work on connections that were created without this option. + +You must ensure that the socket is writable before calling +\fIcurl_easy_send(3)\fP, otherwise the call will return \fBCURLE_AGAIN\fP - +the socket is used in non-blocking mode internally. Use +\fIcurl_easy_getinfo(3)\fP with \fBCURLINFO_LASTSOCKET\fP to obtain the +socket; use your operating system facilities like \fIselect(2)\fP to check if +it can be written to. +.SH AVAILABILITY +Added in 7.18.2. +.SH RETURN VALUE +On success, returns \fBCURLE_OK\fP and stores the number of bytes actually +sent into \fB*n\fP. Note that this may very well be less than the amount you +wanted to send. + +On failure, returns the appropriate error code. +.SH EXAMPLE +See \fBsendrecv.c\fP in \fBdocs/examples\fP directory for usage example. +.SH "SEE ALSO" +.BR curl_easy_setopt "(3), " curl_easy_perform "(3), " curl_easy_getinfo "(3), " +.BR curl_easy_recv "(3) " diff --git a/docs/libcurl/index.html b/docs/libcurl/index.html index 6b4f10550..287a2dd69 100644 --- a/docs/libcurl/index.html +++ b/docs/libcurl/index.html @@ -24,7 +24,9 @@
curl_easy_getinfo
curl_easy_init
curl_easy_perform +
curl_easy_recv
curl_easy_reset +
curl_easy_send
curl_easy_setopt
curl_easy_strerror
curl_escape diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index a686793f7..28e6f82c9 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -208,6 +208,10 @@ The resource referenced in the URL does not exist An unspecified error occurred during the SSH session .IP "CURLE_SSL_SHUTDOWN_FAILED (80)" 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 +\fIcurl_easy_send(3)\fP (Added in 7.18.2) .IP "CURLE_OBSOLETE*" These error codes will never be returned. They used to be used in an old libcurl version and are currently unused. -- cgit v1.2.1 From 2045c79e3745107badb5917d084ecd2913bef20b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 24 May 2008 11:19:51 +0000 Subject: Nikolai Kondrashov provided a clarification for CURLOPT_HEADERFUNCTION --- docs/libcurl/curl_easy_setopt.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 81dac8d57..d378edb4d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -270,6 +270,12 @@ of bytes actually taken care of, or return -1 to signal error to the library (it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return code). +If this option is not set, or if it is set to NULL, but +\fICURLOPT_HEADERDATA\fP (\fICURLOPT_WRITEHEADER\fP) is set to anything but +NULL, the function used to accept response data will be used instead. That is, +it will be the function specified with \fICURLOPT_WRITEFUNCTION\fP, or if it +is not specified or NULL - the default, stream-writing function. + Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a trailer. That trailer is identical to a HTTP header and if such a trailer is received it is passed to the application using this callback as well. There -- cgit v1.2.1 From 89977c73d1c0cba4401cfe70eb7b3cd69fdb190f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 24 May 2008 19:19:49 +0000 Subject: Christopher Palow's multi interface docs updates --- docs/libcurl/curl_multi_add_handle.3 | 2 ++ docs/libcurl/curl_multi_socket.3 | 19 ++++++++----------- 2 files changed, 10 insertions(+), 11 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index 3ce9f78ea..1553b4ec3 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -11,6 +11,8 @@ CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); .SH DESCRIPTION Adds a standard easy handle to the multi stack. This function call will make this \fImulti_handle\fP control the specified \fIeasy_handle\fP. +Furthermore, libcurl now initiates the connection associated with the +specified \fIeasy_handle\fP. When an easy handle has been added to a multi stack, you can not and you must not use \fIcurl_easy_perform(3)\fP on that handle! diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 12914fa61..ada5155bd 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -46,9 +46,8 @@ socket callback function set with the CURLMOPT_SOCKETFUNCTION option to previous time this function 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. This is typically -done as the first function call before the application has any knowledge about -what sockets libcurl uses. +just a single one by calling \fBcurl_multi_socket_all(3)\fP. Note that there +should rarely be reasons to use this function! Get the timeout time - how long to wait for socket actions at most before doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with @@ -125,22 +124,20 @@ function returns OK. 3. Set the timeout callback with CURLMOPT_TIMERFUNCTION, to get to know what timeout value to use when waiting for socket activities. -4. Add easy handles +4. Add easy handles with curl_multi_add_handle() -5. Call curl_multi_socket_all() first once - -6. Provide some means to manage the sockets libcurl is using, so you can check +5. Provide some means to manage the sockets libcurl is using, so you can check them for activity. This can be done through your application code, or by way of an external library such as libevent or glib. -7. Wait for activity on any of libcurl's sockets, use the timeout value your +6. Wait for activity on any of libcurl's sockets, use the timeout value your callback has been told -8, When activity is detected, call curl_multi_socket_action() for the +7, When activity is detected, call curl_multi_socket_action() for the socket(s) that got action. If no activity is detected and the timeout expires, -call \fIcurl_multi_socket(3)\fP with \fICURL_SOCKET_TIMEOUT\fP +call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP -9. Go back to step 7. +8. Go back to step 6. .SH AVAILABILITY This function was added in libcurl 7.15.4, although deemed stable since 7.16.0. -- cgit v1.2.1 From 930a45e7a93c964ec224bdddb59f97479b7e4a5d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 6 Jun 2008 17:33:35 +0000 Subject: - Added CURLINFO_PRIMARY_IP as a new information retrievable with curl_easy_getinfo. It returns a pointer to a string with the most recently used IP address. Modified test case 500 to also verify this feature. The implementing of this feature was sponsored by Lenny Rachitsky at NeuStar. --- docs/libcurl/curl_easy_getinfo.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index be0f060d4..9837d417d 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -159,6 +159,12 @@ counted). Combined with \fICURLINFO_REDIRECT_COUNT\fP you are able to know how many times libcurl successfully reused existing connection(s) or not. See the Connection Options of \fIcurl_easy_setopt(3)\fP to see how libcurl tries to make persistent connections to save time. (Added in 7.12.3) +.IP CURLINFO_PRIMARY_IP +Pass a pointer to a char pointer to receive the pointer to a zero-terminated +string holding the IP address of the most recent connection done with this +\fBcurl\fP handle. This string may be IPv6 if that's enabled. Note that you +get a pointer to a memory area that will be re-used at next request so you +need to copy the string if you want to keep the information. (Added in 7.18.3) .IP CURLINFO_COOKIELIST Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all cookies cURL knows (expired ones, too). Don't forget to -- cgit v1.2.1 From 3fe8251dfbb533803e25cc38365114b28c5a1c85 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 6 Jun 2008 18:40:21 +0000 Subject: - Axel Tillequin and Arnaud Ebalard added support for CURLOPT_CRLFILE, for OpenSSL, NSS and GnuTLS-built libcurls. --- docs/libcurl/curl_easy_setopt.3 | 18 ++++++++++++++++++ docs/libcurl/libcurl-errors.3 | 2 ++ 2 files changed, 20 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d378edb4d..ee425a268 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1452,6 +1452,24 @@ in combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If indicate an accessible path. The \fICURLOPT_CAPATH\fP function apparently does not work in Windows due to some limitation in openssl. This option is OpenSSL-specific and does nothing if libcurl is built to use GnuTLS. +.IP CURLOPT_CRLFILE +Pass a char * to a zero terminated string naming a file with the concatenation +of CRL (in PEM format) to use in the certificate validation that occurs during +the SSL exchange. + +When curl is built to use NSS or GnuTLS, there is no way to influence the use +of CRL passed to help in the verification process. When libcurl is built with +OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both +set, requiring CRL check against all the elements of the certificate chain if +a CRL file is passed. + +This option makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER\fP option. + +A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It +is returned when the SSL exchange fails because the CRL file cannot be loaded. +Note that a failure in certificate verification due to a revocation information +found in the CRL does not trigger this specific error. .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 28e6f82c9..994489b71 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -212,6 +212,8 @@ Failed to shut down the SSL connection 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 \fIcurl_easy_send(3)\fP (Added in 7.18.2) +.IP "CURLE_SSL_CRL_BADFILE (82)" +Failed to load CRL file (Added in 7.18.3) .IP "CURLE_OBSOLETE*" These error codes will never be returned. They used to be used in an old libcurl version and are currently unused. -- cgit v1.2.1 From e1c456407ea38a08440a61cb0c484921ac1f139c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 6 Jun 2008 18:40:58 +0000 Subject: mention added in 7.18.3 --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ee425a268..f1f086e84 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1469,7 +1469,7 @@ This option makes sense only when used in combination with the A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. Note that a failure in certificate verification due to a revocation information -found in the CRL does not trigger this specific error. +found in the CRL does not trigger this specific error. (Added in 7.18.3) .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, -- cgit v1.2.1 From 621c2b901527248b4822895bc0305373a7d2dd63 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 6 Jun 2008 20:52:32 +0000 Subject: - Axel Tillequin and Arnaud Ebalard added support for CURLOPT_ISSUERCERT, for OpenSSL, NSS and GnuTLS-built libcurls. --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++++++++++ docs/libcurl/libcurl-errors.3 | 2 ++ 2 files changed, 18 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f1f086e84..6e7ce3ec7 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1443,6 +1443,22 @@ bundle is assumed to be stored, as established at build time. 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 +from a specific branch of the tree. + +This option makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER\fP option. Otherwise, the result of the check is not +considered as failure. + +A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, +which is returned if the setup of the SSL/TLS session has failed due to a +mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER\fP has +to be set too for the check to fail). (Added in 7.18.3) .IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate directory must be diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 994489b71..c1ab31237 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -214,6 +214,8 @@ return code is only returned from \fIcurl_easy_recv(3)\fP and \fIcurl_easy_send(3)\fP (Added in 7.18.2) .IP "CURLE_SSL_CRL_BADFILE (82)" Failed to load CRL file (Added in 7.18.3) +.IP "CURLE_SSL_ISSUER_ERROR (83)" +Issuer check failed (Added in 7.18.3) .IP "CURLE_OBSOLETE*" These error codes will never be returned. They used to be used in an old libcurl version and are currently unused. -- cgit v1.2.1 From c6efb8252632e8a344c0839e80f4aa830e8a0db2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 8 Jun 2008 21:04:46 +0000 Subject: the next release is now called 7.19.0 --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- docs/libcurl/libcurl-errors.3 | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6e7ce3ec7..fe77c4494 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1458,7 +1458,7 @@ considered as failure. A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, which is returned if the setup of the SSL/TLS session has failed due to a mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER\fP has -to be set too for the check to fail). (Added in 7.18.3) +to be set too for the check to fail). (Added in 7.19.0) .IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple CA certificates to verify the peer with. The certificate directory must be @@ -1485,7 +1485,7 @@ This option makes sense only when used in combination with the A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. Note that a failure in certificate verification due to a revocation information -found in the CRL does not trigger this specific error. (Added in 7.18.3) +found in the CRL does not trigger this specific error. (Added in 7.19.0) .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index c1ab31237..4fb87ad56 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-errors 3 "30 Aug 2007" "libcurl 7.17.0" "libcurl errors" +.TH libcurl-errors 3 "8 Jun 2008" "libcurl 7.19.0" "libcurl errors" .SH NAME libcurl-errors \- error codes in libcurl .SH DESCRIPTION @@ -213,9 +213,9 @@ 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 \fIcurl_easy_send(3)\fP (Added in 7.18.2) .IP "CURLE_SSL_CRL_BADFILE (82)" -Failed to load CRL file (Added in 7.18.3) +Failed to load CRL file (Added in 7.19.0) .IP "CURLE_SSL_ISSUER_ERROR (83)" -Issuer check failed (Added in 7.18.3) +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 version and are currently unused. -- cgit v1.2.1 From 9c8997cbe4cb0e9e7b5f8eb32ee788851621ffe4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 8 Jun 2008 22:00:42 +0000 Subject: 7.19.0 is next --- docs/libcurl/curl_easy_getinfo.3 | 2 +- docs/libcurl/curl_easy_setopt.3 | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 9837d417d..fc45b01ae 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -164,7 +164,7 @@ Pass a pointer to a char pointer to receive the pointer to a zero-terminated string holding the IP address of the most recent connection done with this \fBcurl\fP handle. This string may be IPv6 if that's enabled. Note that you get a pointer to a memory area that will be re-used at next request so you -need to copy the string if you want to keep the information. (Added in 7.18.3) +need to copy the string if you want to keep the information. (Added in 7.19.0) .IP CURLINFO_COOKIELIST Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all cookies cURL knows (expired ones, too). Don't forget to diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index fe77c4494..92056b589 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.18.0" "libcurl Manual" +.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.19.0" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS -- cgit v1.2.1 From 654f0473025afeaaa1cbfe64a13ae0b3ca306361 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 30 Jun 2008 09:39:26 +0000 Subject: minor language fix --- docs/libcurl/ABI | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI index 5ed97da5a..f38c87888 100644 --- a/docs/libcurl/ABI +++ b/docs/libcurl/ABI @@ -9,7 +9,7 @@ ABI - Application Binary Interface First, allow me to define the word for this context: ABI describes the - low-level interface between an application program a library. Calling + low-level interface between an application program and a library. Calling conventions, function arguments, return values, struct sizes/defines and more. -- cgit v1.2.1 From 7c648782bc7c97be81c619acd8598c38b59c5832 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 3 Jul 2008 06:56:03 +0000 Subject: Introcuding a new timestamp for curl_easy_getinfo(): CURLINFO_APPCONNECT_TIME. This is set with the "application layer" handshake/connection is completed (typically SSL, TLS or SSH). By using this you can figure out the application layer's own connect time. You can extract the time stamp using curl's -w option and the new variable named 'time_appconnect'. This feature was sponsored by Lenny Rachitsky at NeuStar. --- docs/libcurl/curl_easy_getinfo.3 | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index fc45b01ae..b8fdf466e 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -71,6 +71,12 @@ start until the name resolving was completed. .IP CURLINFO_CONNECT_TIME Pass a pointer to a double to receive the time, in seconds, it took from the start until the connect to the remote host (or proxy) was completed. +.IP CURLINFO_APPCONNECT_TIME +Pass a pointer to a double to receive the time, in seconds, it took from the +start until the SSL/SSH connect/handshake to the remote host was completed. +This time is most often very near to the PRETRANSFER time, except for cases +such as HTTP pippelining where the pretransfer time can be delayed due to +waits in line for the pipeline and more. (Added in 7.19.0) .IP CURLINFO_PRETRANSFER_TIME Pass a pointer to a double to receive the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all @@ -190,29 +196,33 @@ An overview of the six time values available from curl_easy_getinfo() curl_easy_perform() | - |--NT - |--|--CT - |--|--|--PT - |--|--|--|--ST - |--|--|--|--|--TT - |--|--|--|--|--RT + |--NAMELOOKUP + |--|--CONNECT + |--|--|--APPCONNECT + |--|--|--|--PRETRANSFER + |--|--|--|--|--STARTTRANSFER + |--|--|--|--|--|--TOTAL + |--|--|--|--|--|--REDIRECT .FI -.IP NT +.IP NAMELOOKUP \fICURLINFO_NAMELOOKUP_TIME\fP. The time it took from the start until the name resolving was completed. -.IP CT +.IP CONNECT \fICURLINFO_CONNECT_TIME\fP. The time it took from the start until the connect to the remote host (or proxy) was completed. -.IP PT +.IP APPCONNECT +\fICURLINFO_APPCONNECT_TIME\fP. The time it took from the start until the SSL +connect/handshake with the remote host was completed. (Added in in 7.19.0) +.IP PRETRANSFER \fICURLINFO_PRETRANSFER_TIME\fP. The time it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. -.IP ST +.IP STARTTRANSFER \fICURLINFO_STARTTRANSFER_TIME\fP. The time it took from the start until the first byte is just about to be transferred. -.IP TT +.IP TOTAL \fICURLINFO_TOTAL_TIME\fP. Total time of the previous request. -.IP RT +.IP REDIRECT \fICURLINFO_REDIRECT_TIME\fP. The time it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. So, this is zero if no redirection took place. -- cgit v1.2.1 From 60f0b4fffe3de8eb1a1fc3015c2f6643fdccb57a Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Tue, 8 Jul 2008 21:16:18 +0000 Subject: Fixed test 554 to pass the torture test. --- docs/libcurl/curl_formadd.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index f3cea0054..e55c542f2 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -128,9 +128,9 @@ you've called \fIcurl_easy_cleanup(3)\fP for the curl handle. See example below. .SH RETURN VALUE -0 means everything was ok, non-zero means an error occurred as +0 means everything was ok, non-zero means an error occurred corresponding +to a CURL_FORMADD_* constant defined in .I -defines. .SH EXAMPLE .nf -- cgit v1.2.1 From a17fadea3a324a65398780d88f41414ecfb169b0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 10 Jul 2008 13:40:59 +0000 Subject: updated to match current reality --- docs/libcurl/curl_multi_socket.3 | 90 ++++++++++++++++++++++------------------ 1 file changed, 49 insertions(+), 41 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index ada5155bd..38fe60013 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -10,7 +10,10 @@ curl_multi_socket \- reads/writes available data CURLMcode curl_multi_socket_action(CURLM * multi_handle, curl_socket_t sockfd, int ev_bitmask, int *running_handles); +.fi +.B "Now deprecated versions:" +.nf CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, int *running_handles); @@ -20,47 +23,48 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle, .SH DESCRIPTION Alternative versions of \fIcurl_multi_perform(3)\fP that allows the application to pass in the file descriptor/socket that has been detected to -have \&"action" on it and let libcurl perform. This allows libcurl to not have -to scan through all possible file descriptors to check for action. When the -application has detected action on a socket handled by libcurl, it should call -\fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument set to the -socket with the action. When the events on a socket are known, they can be -passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP -to 0, and then adding using bitwise OR (|) any combination of events to be -chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the -events on a socket are unknown, pass 0 instead, and libcurl will test the -descriptor internally. - -At return, the int \fBrunning_handles\fP points to will contain the number of -still running easy handles within the multi handle. When this number reaches -zero, all transfers are complete/done. Note that when you call +have \&"action" on it and let libcurl perform. This lets libcurl avoid having +to scan through all possible file descriptors to check for action. + +When the application has detected action on a socket handled by libcurl, it +should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument +set to the socket with the action. When the events on a socket are known, they +can be passed as an events bitmask \fBev_bitmask\fP by first setting +\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of +events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or +CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and +libcurl will test the descriptor internally. + +At return, the integer \fBrunning_handles\fP points to will contain the number +of still running easy handles within the multi handle. When this number +reaches zero, all transfers are complete/done. Note that when you call \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed. -The curl_multi_socket functions inform the application about 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 this function 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 rarely be reasons to use this function! - -Get the timeout time - how long to wait for socket actions at most before -doing the timeout action: call the \fBcurl_multi_socket(3)\fP function with -the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT, by setting the -\fICURLMOPT_TIMERFUNCTION\fP option with \fIcurl_multi_setopt(3)\fP. You can -also use the \fIcurl_multi_timeout(3)\fP function to poll the value at any -given time, but for an event-based system using the callback is far better -than relying on polling the timeout value. +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 +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. + +Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION\fP option with +\fIcurl_multi_setopt(3)\fP. Your application will then get called with +information on how long to wait for socket actions at most before doing the +timeout action: call the \fBcurl_multi_socket_action(3)\fP function with the +\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the +\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but +for an event-based system using the callback is far better than relying on +polling the timeout value. Usage of \fIcurl_multi_socket(3)\fP is deprecated, whereas the function is -equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set -to 0. +equivalent to \fIcurl_multi_socket_action(3)\fP with \fBev_bitmask\fP set to +0. +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! .SH "CALLBACK DETAILS" The socket \fBcallback\fP function uses a prototype like this @@ -107,15 +111,19 @@ The \fIuserp\fP argument is a private pointer you have previously set with .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. -If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you -should call \fIcurl_multi_socket(3)\fP again, before you wait for more actions -on libcurl's sockets. 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". +Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means +that you should call \fIcurl_multi_socket(3)\fP again, before you wait for +more actions on libcurl's sockets. 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". + +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 this only returns errors etc regarding the whole multi stack. There -might still have occurred problems on individual transfers even when this -function returns OK. +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 +return OK. .SH "TYPICAL USAGE" 1. Create a multi handle -- cgit v1.2.1 From 6b7ccde1567f401018144e9fa9fcaa63616df338 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 10 Jul 2008 22:24:11 +0000 Subject: (Added in the section for CURLOPT_DNS_CACHE_TIMEOUT, pointed out on the curl-library list on July 9th 2008 by Mathew Hounsell) NOTE: the name resolve functions of various libc implementations don't re-read name server information unless explicitly told so (by for example calling Ires_init(3). 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. --- docs/libcurl/curl_easy_setopt.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 92056b589..f389f98b4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -505,6 +505,12 @@ Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero (0) to completely disable 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 +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 Pass a long. If the value is non-zero, it tells curl to use a global DNS cache that will survive between easy handle creations and deletions. This is not -- cgit v1.2.1 From 7d0eabaa808474fc083723a2fc6932f9d1e0de4e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 23 Jul 2008 20:53:04 +0000 Subject: - I went over the curl_easy_setopt man page and replaced most references to non-zero with the fixed value of 1. We should strive at making options support '1' for enabling them mentioned explicitly, as that then will allow us for to extend them in the future without breaking older programs. --- docs/libcurl/curl_easy_setopt.3 | 197 ++++++++++++++++++++-------------------- 1 file changed, 97 insertions(+), 100 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f389f98b4..a6001e9ea 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -56,7 +56,7 @@ The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. .SH BEHAVIOR OPTIONS .IP CURLOPT_VERBOSE -Set the parameter to non-zero to get the library to display a lot of verbose +Set the parameter to 1 to get the library to display a lot of verbose information about its operations. Very useful for libcurl and/or protocol debugging and understanding. The verbose information will be sent to stderr, or the stream set with \fICURLOPT_STDERR\fP. @@ -65,17 +65,17 @@ You hardly ever want this set in production use, you will almost always want this when you debug/report problems. Another neat option for debugging is the \fICURLOPT_DEBUGFUNCTION\fP. .IP CURLOPT_HEADER -A non-zero parameter tells the library to include the header in the body +A parameter set to 1 tells the library to include the header in the body output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). .IP CURLOPT_NOPROGRESS -A non-zero parameter tells the library to shut off the built-in progress meter +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 at all. .IP CURLOPT_NOSIGNAL -Pass a long. If it is non-zero, libcurl will not use any functions that +Pass a long. If it is 1, libcurl will not use any functions that install signal handlers or any functions that cause signals to be sent to the process. This option is mainly here to allow multi-threaded unix applications to still set/use all timeout options etc, without risking getting signals. @@ -188,7 +188,7 @@ rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET, SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl only passes SEEK_SET. The callback must return 0 on success as returning -non-zero will cause the upload operation to fail. +something else will cause the upload operation to fail. If you forward the input arguments directly to "fseek" or "lseek", note that the data type for \fIoffset\fP is not the same as defined for curl_off_t on @@ -410,7 +410,7 @@ touched. Do not rely on the contents in those cases. Pass a FILE * as parameter. Tell libcurl to use this stream instead of stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE\fP data. .IP CURLOPT_FAILONERROR -A non-zero parameter tells the library to fail silently if the HTTP code +A parameter set to 1 tells the library to fail silently if the HTTP code returned is equal to or larger than 400. The default action would be to return the page normally, ignoring that code. @@ -473,12 +473,12 @@ this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is default. (Added in 7.10) .IP CURLOPT_HTTPPROXYTUNNEL -Set the parameter to non-zero to get the library to tunnel all operations -through a 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. +Set the parameter to 1 to make the library tunnel all operations through a +given HTTP proxy. There is a big difference between using a proxy and to +tunnel through it. If you don't know what this means, you probably don't want +this tunneling option. .IP CURLOPT_SOCKS5_RESOLVE_LOCAL -Set the parameter to 1 to get the library to resolve the host name locally +Set the parameter to 1 to make the library to resolve the host name locally instead of passing it to the proxy to resolve, when using a SOCKS5 proxy. Note that libcurl before 7.18.0 always resolved the host name locally even @@ -495,10 +495,10 @@ set. Note that port numbers are only valid 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 working local port number. It starts with the given \fICURLOPT_LOCALPORT\fP -and adds one to the number for each retry. Setting this value to 1 or below -will make libcurl do only one try for exact port number. Note that port -numbers by nature is a scarce resource that will be busy at times so setting -this value to something too low might cause unnecessary connection setup +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 +by nature are scarce resources that will be busy at times so setting this +value to something too low might cause unnecessary connection setup failures. (Added in 7.15.2) .IP CURLOPT_DNS_CACHE_TIMEOUT Pass a long, this sets the timeout in seconds. Name resolves will be kept in @@ -512,7 +512,7 @@ name server information unless explicitly told so (by for example calling 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 -Pass a long. If the value is non-zero, it tells curl to use a global DNS cache +Pass a long. If the value is 1, it tells curl to use a global DNS cache that will survive between easy handle creations and deletions. This is not thread-safe and this will use a global variable. @@ -560,11 +560,11 @@ parameter. 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 password after that \fImachine\fP, -which ever information is not specified in the URL. +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 +password after that \fImachine\fP, which ever information is not specified in +the URL. Undefined values of the option will have this effect. .IP CURL_NETRC_IGNORED @@ -572,9 +572,8 @@ 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. +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. .RE Only machine name, user name and password are taken into account (init macros and similar things aren't supported). @@ -659,24 +658,23 @@ bitmask can be constructed by or'ing together the bits listed above for the work. (Added in 7.10.7) .SH HTTP OPTIONS .IP CURLOPT_AUTOREFERER -Pass a non-zero parameter to enable this. When enabled, libcurl will +Pass a parameter set to 1 to enable this. When enabled, libcurl will automatically set the Referer: field in requests where it follows a Location: redirect. .IP CURLOPT_ENCODING -Sets the contents of the Accept-Encoding: header sent in an HTTP -request, and enables decoding of a response when a Content-Encoding: -header is received. Three encodings are supported: \fIidentity\fP, -which does nothing, \fIdeflate\fP which requests the server to -compress its response using the zlib algorithm, and \fIgzip\fP which -requests the gzip algorithm. If a zero-length string is set, then an -Accept-Encoding: header containing all supported encodings is sent. - -This is a request, not an order; the server may or may not do it. This -option must be set (to any non-NULL value) or else any unsolicited -encoding done by the server is ignored. See the special file -lib/README.encoding for details. +Sets the contents of the Accept-Encoding: header sent in an HTTP request, and +enables decoding of a response when a Content-Encoding: header is received. +Three encodings are supported: \fIidentity\fP, which does nothing, +\fIdeflate\fP which requests the server to compress its response using the +zlib algorithm, and \fIgzip\fP which requests the gzip algorithm. If a +zero-length string is set, then an Accept-Encoding: header containing all +supported encodings is sent. + +This is a request, not an order; the server may or may not do it. This option +must be set (to any non-NULL value) or else any unsolicited encoding done by +the server is ignored. See the special file lib/README.encoding for details. .IP CURLOPT_FOLLOWLOCATION -A non-zero parameter tells the library to follow any Location: header that the +A parameter set to 1 tells the library to follow any Location: header that the server sends as part of an HTTP header. This means that the library will re-send the same request on the new location @@ -684,7 +682,7 @@ and follow new Location: headers all the way until no more such headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects libcurl will follow. .IP CURLOPT_UNRESTRICTED_AUTH -A non-zero parameter tells the library it can continue to send authentication +A parameter set to 1 tells the library it can continue to send authentication (user+password) when following locations, even when hostname changed. This option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. .IP CURLOPT_MAXREDIRS @@ -695,20 +693,20 @@ redirections have been followed, the next redirect will cause an error Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite number of redirects (which is the default) .IP CURLOPT_POST301 -A non-zero parameter tells the library to respect RFC 2616/10.3.2 and not +A parameter set to 1 tells the library to respect RFC 2616/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. 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) .IP CURLOPT_PUT -A non-zero parameter tells the library to use HTTP PUT to transfer data. The +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. This option is deprecated and starting with version 7.12.1 you should instead use \fICURLOPT_UPLOAD\fP. .IP CURLOPT_POST -A non-zero parameter tells the library to do a regular HTTP post. This will +A parameter set to 1 tells the library to do a regular HTTP post. This will also make the library use the a "Content-Type: application/x-www-form-urlencoded" header. (This is by far the most commonly used POST method). @@ -738,7 +736,7 @@ adding a header like "Transfer-Encoding: chunked" with \fICURLOPT_HTTPHEADER\fP. With HTTP 1.0 or without chunked transfer, you must specify the size in the request. -When setting \fICURLOPT_POST\fP to a non-zero value, it will automatically set +When setting \fICURLOPT_POST\fP to 1, it will automatically set \fICURLOPT_NOBODY\fP to 0 (since 7.14.1). If you issue a POST request and then want to make a HEAD or GET using the same @@ -900,12 +898,12 @@ error for this. Using \fICURLOPT_VERBOSE\fP or \fICURLOPT_DEBUGFUNCTION\fP will get a warning to display, but that is the only visible feedback you get about this possibly lethal situation. .IP CURLOPT_COOKIESESSION -Pass a long set to non-zero 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 without expiry date and they are meant to be alive and -existing for this "session" only. +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 without expiry date and they are meant to be alive and existing for +this "session" only. .IP CURLOPT_COOKIELIST Pass a char * to a cookie string. Cookie can be either in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format. If cURL @@ -916,12 +914,12 @@ by cURL. (Added in 7.15.4) Passing the special string \&"FLUSH" will write 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 non-zero, this forces the HTTP request to get back +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 previously using the same curl handle. -When setting \fICURLOPT_HTTPGET\fP to a non-zero value, it will automatically -set \fICURLOPT_NOBODY\fP to 0 (since 7.14.1). +When setting \fICURLOPT_HTTPGET\fP to 1, it will automatically set +\fICURLOPT_NOBODY\fP to 0 (since 7.14.1). .IP CURLOPT_HTTP_VERSION Pass a long, set to one of the values described below. They force libcurl to use the specific HTTP versions. This is not sensible to do unless you have a @@ -984,10 +982,10 @@ Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. 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. Before version 7.15.6, if you also set \fICURLOPT_NOBODY\fP non-zero, -this option didn't work. +option. Before version 7.15.6, if you also set \fICURLOPT_NOBODY\fP to 1, this +option didn't work. .IP CURLOPT_DIRLISTONLY -A non-zero parameter tells the library to just list the names of files in a +A parameter set to 1 tells the library to just list the names of files in a directory, instead of doing a full directory listing that would include file sizes, dates etc. This works for FTP and SFTP URLs. @@ -997,12 +995,12 @@ might not include subdirectories and symbolic links. (This option was known as CURLOPT_FTPLISTONLY up to 7.16.4) .IP CURLOPT_APPEND -A non-zero parameter tells the library to append to the remote file instead of +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. (This option was known as CURLOPT_FTPAPPEND up to 7.16.4) .IP CURLOPT_FTP_USE_EPRT -Pass a long. If the value is non-zero, it tells curl to use the EPRT (and +Pass a long. If the value is 1, it tells curl to use the EPRT (and LPRT) command when doing active FTP downloads (which is enabled by \fICURLOPT_FTPPORT\fP). Using EPRT means that it will first attempt to use EPRT and then LPRT before using PORT, but if you pass FALSE (zero) to this @@ -1010,14 +1008,14 @@ option, it will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5) If the server is an IPv6 host, this option will have no effect as of 7.12.3. .IP CURLOPT_FTP_USE_EPSV -Pass a long. If the value is non-zero, it tells curl to use the EPSV command +Pass a long. If the value is 1, it tells curl to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. If the server is an IPv6 host, this option will have no effect as of 7.12.3. .IP CURLOPT_FTP_CREATE_MISSING_DIRS -Pass a long. If the value is non-zero, curl will attempt to create any remote +Pass a long. If the value is 1, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working directory. (Added in 7.10.7) @@ -1040,11 +1038,11 @@ fails. This is currently only known to be required when connecting to Tumbleweed's Secure Transport FTPS server using client certificates for authentication. (Added in 7.15.5) .IP CURLOPT_FTP_SKIP_PASV_IP -Pass a long. If set to a non-zero value, it instructs libcurl to not use the -IP address the server suggests in its 227-response to libcurl's PASV command -when libcurl connects the data connection. Instead libcurl will re-use the -same IP address it already uses for the control connection. But it will use -the port number from the 227-response. (Added in 7.14.2) +Pass a long. If set to 1, it instructs libcurl to not use the IP address the +server suggests in its 227-response to libcurl's PASV command when libcurl +connects the data connection. Instead libcurl will re-use the same IP address +it already uses for the control connection. But it will use the port number +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 @@ -1113,7 +1111,7 @@ compliant than 'nocwd' but without the full penalty of 'multicwd'. .RE .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT -A non-zero parameter 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 @@ -1125,10 +1123,10 @@ 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 -appending ;type=a or ;type=i to the URL. Without this setting, or it being -set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when -doing FTP via a proxy. Beware that not all proxies support this feature. -(Added in 7.18.0) +appending ;type=a or ;type=i to the URL. Without this setting, or it being set +to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing +FTP via a proxy. Beware that not all proxies support this feature. (Added in +7.18.0) .IP CURLOPT_CRLF Convert Unix newlines to CRLF newlines on transfers. .IP CURLOPT_RANGE @@ -1173,13 +1171,13 @@ possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and replace or extend the set of headers sent by libcurl. Use \fICURLOPT_HTTP_VERSION\fP to change HTTP version. .IP CURLOPT_FILETIME -Pass a long. If it is a non-zero value, libcurl will attempt to get the -modification date of the remote document in this operation. This requires that -the remote server sends the time or replies to a time querying command. The +Pass a long. If it is 1, libcurl will attempt to get the modification date of +the remote document in this operation. This requires that the remote server +sends the time or replies to a time querying command. The \fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME\fP argument can be used after a transfer to extract the received time (if any). .IP CURLOPT_NOBODY -A non-zero parameter tells the library to not include the body-part in the +A parameter set to 1 tells the library to not include the body-part in the output. This is only relevant for protocols that have separate header and body parts. On HTTP(S) servers, this will make libcurl do a HEAD request. @@ -1205,7 +1203,7 @@ For uploading using SCP, this option or \fICURLOPT_INFILESIZE\fP is mandatory. Note that this option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns. .IP CURLOPT_UPLOAD -A non-zero parameter tells the library to prepare for an upload. The +A parameter set to 1 tells the library to prepare for an upload. The \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP or \fICURLOPT_INFILESIZE_LARGE\fP options are also interesting for uploads. If the protocol is HTTP, uploading means using the PUT request unless you tell @@ -1301,14 +1299,14 @@ the \fICURLMOPT_MAXCONNECTS\fP option. .IP CURLOPT_CLOSEPOLICY (Obsolete) This option does nothing. .IP CURLOPT_FRESH_CONNECT -Pass a long. Set to non-zero to make the next transfer use a new (fresh) -connection by force. If the connection cache is full before this connection, -one of the existing connections will be closed as according to the selected or -default policy. This option should be used with caution and only if you -understand what it does. Set this to 0 to have libcurl attempt re-using an -existing connection (default behavior). +Pass a long. Set to 1 to make the next transfer use a new (fresh) connection +by force. If the connection cache is full before this connection, one of the +existing connections will be closed as according to the selected or default +policy. This option should be used with caution and only if you understand +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 non-zero to make the next transfer explicitly close the +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. This option should be used with caution and only if you understand what it @@ -1340,8 +1338,8 @@ Resolve to ipv4 addresses. Resolve to ipv6 addresses. .RE .IP CURLOPT_CONNECT_ONLY -Pass a long. A non-zero parameter tells the library to perform any required -proxy authentication and connection setup, but no data transfer. +Pass a long. If the parameter equals 1, it tells the library to perform all +the required proxy authentication and connection setup, but no data transfer. This option is useful with the \fICURLINFO_LASTSOCKET\fP option to \fIcurl_easy_getinfo(3)\fP. The library can set up the connection and then the @@ -1416,26 +1414,25 @@ Force SSLv3 .IP CURLOPT_SSL_VERIFYPEER Pass a long as parameter. -This option determines whether curl verifies the authenticity of the -peer's certificate. A nonzero value means curl verifies; zero means it -doesn't. The default is nonzero, but before 7.10, it was zero. - -When negotiating an SSL connection, the server sends a certificate -indicating its identity. Curl verifies whether the certificate is -authentic, i.e. that you can trust that the server is who the -certificate says it is. This trust is based on a chain of digital -signatures, rooted in certification authority (CA) certificates you -supply. As of 7.10, curl installs a default bundle of CA certificates -and you can specify alternate certificates with the +This option determines whether curl verifies the authenticity of the peer's +certificate. A value of 1 means curl verifies; zero means it doesn't. The +default is nonzero, but before 7.10, it was zero. + +When negotiating an SSL connection, the server sends a certificate indicating +its identity. Curl verifies whether the certificate is authentic, i.e. that +you can trust that the server is who the certificate says it is. This trust +is based on a chain of digital signatures, rooted in certification authority +(CA) certificates you supply. As of 7.10, curl installs a default bundle of +CA certificates and you can specify alternate certificates with the \fICURLOPT_CAINFO\fP option or the \fICURLOPT_CAPATH\fP option. -When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification -fails to prove that the certificate is authentic, the connection -fails. When the option is zero, the connection succeeds regardless. +When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification fails to +prove that the certificate is authentic, the connection fails. When the +option is zero, the connection succeeds regardless. -Authenticating the certificate is not by itself very useful. You -typically want to ensure that the server, as authentically identified -by its certificate, is the server you mean to be talking to. Use +Authenticating the certificate is not by itself very useful. You typically +want to ensure that the server, as authentically identified by its +certificate, is the server you mean to be talking to. Use \fICURLOPT_SSL_VERIFYHOST\fP to control that. .IP CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more -- cgit v1.2.1 From 5373289574d03138e5bbaef5f119abf90a7f6e5c Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Wed, 23 Jul 2008 22:02:03 +0000 Subject: Eliminated references to TRUE and FALSE since those identifiers aren't defined by the libcurl API. Also changed curl_easy_setopt examples to pass longs where appropriate. --- docs/libcurl/curl_easy_setopt.3 | 8 ++++---- docs/libcurl/libcurl-tutorial.3 | 30 +++++++++++++++--------------- 2 files changed, 19 insertions(+), 19 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a6001e9ea..d8f7d8268 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -251,7 +251,7 @@ If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl function that performs transfers. -\fICURLOPT_NOPROGRESS\fP must be set to FALSE to make this function actually +\fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually get called. .IP CURLOPT_PROGRESSDATA Pass a pointer that will be untouched by libcurl and passed as the first @@ -502,7 +502,7 @@ value to something too low might cause unnecessary connection setup failures. (Added in 7.15.2) .IP CURLOPT_DNS_CACHE_TIMEOUT Pass a long, this sets the timeout in seconds. Name resolves will be kept in -memory for this number of seconds. Set to zero (0) to completely disable +memory for this number of seconds. Set to zero to completely disable caching, or set to -1 to make the cached entries remain forever. By default, libcurl caches this info for 60 seconds. @@ -1003,7 +1003,7 @@ overwrite it. This is only useful when uploading to an ftp site. Pass a long. If the value is 1, it tells curl to use the EPRT (and LPRT) command when doing active FTP downloads (which is enabled by \fICURLOPT_FTPPORT\fP). Using EPRT means that it will first attempt to use -EPRT and then LPRT before using PORT, but if you pass FALSE (zero) to this +EPRT and then LPRT before using PORT, but if you pass zero to this option, it will not try using EPRT or LPRT, only plain PORT. (Added in 7.10.5) If the server is an IPv6 host, this option will have no effect as of 7.12.3. @@ -1011,7 +1011,7 @@ If the server is an IPv6 host, this option will have no effect as of 7.12.3. Pass a long. If the value is 1, it tells curl to use the EPSV command when doing passive FTP downloads (which it always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you -pass FALSE (zero) to this option, it will not try using EPSV, only plain PASV. +pass zero to this option, it will not try using EPSV, only plain PASV. If the server is an IPv6 host, this option will have no effect as of 7.12.3. .IP CURLOPT_FTP_CREATE_MISSING_DIRS diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 0d52cf987..9e97fae9e 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -276,7 +276,7 @@ yassl Required actions unknown -When using multiple threads you should set the CURLOPT_NOSIGNAL option to TRUE +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 not honored during the DNS lookup - which you can work around by building libcurl with c-ares support. c-ares is a library that provides asynchronous @@ -293,12 +293,12 @@ actually does, or the remote server might return non-standard replies that confuse the library which then confuses your program. There's one golden rule when these things occur: set the CURLOPT_VERBOSE -option to TRUE. It'll cause the library to spew out the entire protocol +option to 1. It'll cause the library to spew out the entire protocol details it sends, some internal info and some received protocol data as well (especially when using FTP). If you're using HTTP, adding the headers in the 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 TRUE. +output with CURLOPT_HEADER set 1. Of course there are bugs left. We need to get to know about them to be able to fix them, so we're quite dependent on your bug reports! When you do report @@ -343,7 +343,7 @@ between the application and the callback. Tell libcurl that we want to upload: - curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, TRUE); + curl_easy_setopt(easyhandle, CURLOPT_UPLOAD, 1L); A few protocols won't behave properly when uploads are done without any prior knowledge of the expected file size. So, set the upload file size using the @@ -398,7 +398,7 @@ use for a particular host. As an extension to the normal functionality, libcurl also supports this file for non-FTP protocols such as HTTP. To make curl use this file, use the CURLOPT_NETRC option: - curl_easy_setopt(easyhandle, CURLOPT_NETRC, TRUE); + curl_easy_setopt(easyhandle, CURLOPT_NETRC, 1L); And a very basic example of how such a .netrc file may look like: @@ -486,7 +486,7 @@ then passing that list to libcurl. curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr); /* set the size of the postfields data */ - curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23); + curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23L); /* pass our list of custom made headers */ curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers); @@ -563,7 +563,7 @@ 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 CURLOPT_HTTPGET option: - curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, TRUE); + curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L); Just setting CURLOPT_POSTFIELDS to "" or NULL will *not* stop libcurl from doing a POST. It will just make it POST without any data to send! @@ -575,7 +575,7 @@ that can be switched on and then makes it presents a progress meter in your terminal. Switch on the progress meter by, oddly enough, set CURLOPT_NOPROGRESS to -FALSE. This option is set to TRUE by default. +zero. This option is set to 1 by default. For most applications however, the built-in progress meter is useless and what instead is interesting is the ability to specify a progress @@ -725,7 +725,7 @@ rarely allowed. Tell libcurl to use proxy tunneling like this: - curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, TRUE); + curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, 1L); In fact, there might even be times when you want to do plain HTTP operations using a tunnel like this, as it then enables you to operate on @@ -790,9 +790,9 @@ just a matter of thinking again. To force your upcoming request to not use an already existing connection (it will even close one first if there happens to be one alive to the same host you're about to operate on), you can do that by setting CURLOPT_FRESH_CONNECT -to TRUE. In a similar spirit, you can also forbid the upcoming request to be +to 1. In a similar spirit, you can also forbid the upcoming request to be "lying" around and possibly get re-used after the request by setting -CURLOPT_FORBID_REUSE to TRUE. +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 @@ -935,7 +935,7 @@ error code (CURLE_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE to send commands before a transfer, no transfer will actually take place when a quote command has failed. -If you set the CURLOPT_HEADER to true, you will tell libcurl to get +If you set the CURLOPT_HEADER to 1, you will tell libcurl to get information about the target file and output "headers" about it. The headers will be in "HTTP-style", looking like they do in HTTP. @@ -1015,7 +1015,7 @@ work it tries PASV instead. (EPSV is an extension to the original FTP spec and does not exist nor work on all FTP servers.) You can prevent libcurl from first trying the EPSV command by setting -CURLOPT_FTP_USE_EPSV to FALSE. +CURLOPT_FTP_USE_EPSV to zero. In some cases, you will prefer to have the server connect back to you for the second connection. This might be when the server is perhaps behind a firewall @@ -1029,14 +1029,14 @@ from. When doing the "PORT" approach, libcurl will attempt to use the EPRT and the LPRT before trying PORT, as they work with more protocols. You can disable -this behavior by setting CURLOPT_FTP_USE_EPRT to FALSE. +this behavior by setting CURLOPT_FTP_USE_EPRT to zero. .SH "Headers Equal Fun" Some protocols provide "headers", meta-data separated from the normal data. These headers are by default not included in the normal data stream, but you can make them appear in the data stream by setting CURLOPT_HEADER to -TRUE. +1. What might be even more useful, is libcurl's ability to separate the headers from the data and thus make the callbacks differ. You can for example set a -- cgit v1.2.1 From 5aed78e183e843a6935679d3ebdafd0c10b41114 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 30 Jul 2008 21:55:26 +0000 Subject: - Phil Blundell added the CURLOPT_SCOPE option, as well as adjusted the URL parser to allow numerical IPv6-addresses to be specified with the scope given, as per RFC4007 - with a percent letter that itself needs to be URL escaped. For example, for an address of fe80::1234%1 the HTTP URL is: "http://[fe80::1234%251]/" --- docs/libcurl/curl_easy_setopt.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d8f7d8268..6191469d6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "5 Jan 2008" "libcurl 7.19.0" "libcurl Manual" +.TH curl_easy_setopt 3 "30 Jul 2008" "libcurl 7.19.0" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -547,6 +547,9 @@ notably telnet or rlogin) small segments may need to be sent without delay. This is less efficient than sending larger amounts of data at a time, and can contribute to congestion on the network if overdone. +.IP CURLOPT_ADDRESS_SCOPE +Pass a long specifying the scope_id value to use when connecting to IPv6 +link-local or site-local addresses. .SH NAMES and PASSWORDS OPTIONS (Authentication) .IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and -- cgit v1.2.1 From a3045b4e4944a36f467f363607d6c6a50727fca2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 6 Aug 2008 21:22:07 +0000 Subject: - mention curl_multi_socket_action() rather than the deprecated curl_multi_socket() - don't claim that it has an argument named 'easy' because it doesn't! --- docs/libcurl/curl_multi_timeout.3 | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index 7302e0ac4..b4da9af89 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -14,10 +14,9 @@ An application using the libcurl multi interface should call actions \- at most \- before proceeding. Proceeding means either doing the socket-style timeout action: call the -\fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to -CURL_SOCKET_TIMEOUT and the \fBeasy\fP argument set to CURL_EASY_TIMEOUT, or -simply calling \fBcurl_multi_perform(3)\fP if you're using the simpler and -older multi interface approach. +\fBcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set +to CURL_SOCKET_TIMEOUT, or call \fBcurl_multi_perform(3)\fP if you're using +the simpler and older multi interface approach. The timeout value returned in the long \fBtimeout\fP points to, is in number of milliseconds at this very moment. If 0, it means you should proceed -- cgit v1.2.1 From 6768e81d5dfd540c5db030a9fe1c3e2d433617c5 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Wed, 20 Aug 2008 19:45:43 +0000 Subject: Added an edited version of Vincent Le Normand's documentation of SFTP quote commands to the man pages. --- docs/libcurl/curl_easy_setopt.3 | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6191469d6..84bcd1dc2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -972,8 +972,12 @@ properly filled in with text strings. Use \fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL to this option. +The set of valid FTP commands depends on the server (see RFC959 for a +list of mandatory commands). The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, -rename, rm, rmdir, symlink. (SFTP support added in 7.16.3) +rename, rm, rmdir, symlink (see +.BR curl (1)) +(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 @@ -1630,4 +1634,4 @@ If you try to set an option that libcurl doesn't know about, perhaps because the library is too old to support it or the option was removed in a recent version, this function will return \fICURLE_FAILED_INIT\fP. .SH "SEE ALSO" -.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), " +.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3)" -- cgit v1.2.1 From e082d2403c1818696d319eff211ce82d23765ad3 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 28 Aug 2008 02:32:41 +0000 Subject: Fixed a couple of typos --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 84bcd1dc2..6059e38bf 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -587,7 +587,7 @@ standard Unix ftp client does). It should only be readable by user. Pass a char * as parameter, pointing to a zero terminated string containing the full path name to the file you want libcurl to use as .netrc file. If this option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to -find the a .netrc file in the current user's home directory. (Added in 7.10.9) +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. @@ -710,7 +710,7 @@ This option is deprecated and starting with version 7.12.1 you should instead use \fICURLOPT_UPLOAD\fP. .IP CURLOPT_POST A parameter set to 1 tells the library to do a regular HTTP post. This will -also make the library use the a "Content-Type: +also make the library use a "Content-Type: application/x-www-form-urlencoded" header. (This is by far the most commonly used POST method). @@ -1575,7 +1575,7 @@ CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. (Added in 7.16.1) .IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 Pass a char * pointing to a string containing 32 hexadecimal digits. The -string should be the 128 bit MD5 cheksum of the remote host's public key, and +string should be the 128 bit MD5 checksum of the remote host's public key, and libcurl will reject the connection to the host unless the md5sums match. This option is only for SCP and SFTP transfers. (Added in 7.17.1) .IP CURLOPT_SSH_PUBLIC_KEYFILE -- cgit v1.2.1 From 4c9768565ec3a9baf26ac8a547bca6e42cc64fa5 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 5 Sep 2008 14:29:21 +0000 Subject: - Introducing CURLOPT_CERTINFO and the corresponding CURLINFO_CERTINFO. By enabling this feature with CURLOPT_CERTINFO for a request using SSL (HTTPS or FTPS), libcurl will gather lots of server certificate info and that info can then get extracted by a client after the request has completed with curl_easy_getinfo()'s CURLINFO_CERTINFO option. Linus Nielsen Feltzing helped me test and smoothen out this feature. Unfortunately, this feature currently only works with libcurl built to use OpenSSL. This feature was sponsored by networking4all.com - thanks! --- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6059e38bf..e07776ccf 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1496,6 +1496,13 @@ A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. Note that a failure in certificate verification due to a revocation information 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 +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.0) .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, -- cgit v1.2.1 From bc90fefb5b6738219bd4158f2adf6c7cb0a7af21 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 7 Sep 2008 21:33:50 +0000 Subject: SOCKS5_RESOLVE_LOCAL was just never added as an option! --- docs/libcurl/curl_easy_setopt.3 | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e07776ccf..7d30fa697 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -477,12 +477,6 @@ Set the parameter to 1 to make the library tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy and to tunnel through it. If you don't know what this means, you probably don't want this tunneling option. -.IP CURLOPT_SOCKS5_RESOLVE_LOCAL -Set the parameter to 1 to make the library to resolve the host name locally -instead of passing it to the proxy to resolve, when using a SOCKS5 proxy. - -Note that libcurl before 7.18.0 always resolved the host name locally even -when SOCKS5 was used. (Added in 7.18.0) .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 -- cgit v1.2.1 From ac1ab03cb0f7477357e5417a719b6ddc73b5dd41 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Tue, 9 Sep 2008 05:39:59 +0000 Subject: Hammer home the fact that "multi interface" != "multi-threaded" --- docs/libcurl/libcurl-tutorial.3 | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 9e97fae9e..1a1b3980f 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -1117,12 +1117,18 @@ interface that transfers one file at a time and doesn't return until its done. 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. +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 +reverse. The multi interface can allow a single-threaded application +to perform the same kinds of multiple, simultaneous transfers that +multi-threaded programs can perform. It allows many of the benefits +of multi-threaded transfers without the complexity of managing and +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 in to a "multi stack". You create the easy handles you want and you set all the options just like you -- cgit v1.2.1 From 152cf6325d3b1b0383d9c36fab9243005e4ea456 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Wed, 10 Sep 2008 07:11:45 +0000 Subject: Checked in some grammatical and minor other fixes in the documentation and examples that I found in the FreeBSD ports system. --- docs/libcurl/curl_easy_pause.3 | 4 ++-- docs/libcurl/curl_multi_setopt.3 | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3 index ae2ed90a0..6208c79ad 100644 --- a/docs/libcurl/curl_easy_pause.3 +++ b/docs/libcurl/curl_easy_pause.3 @@ -12,7 +12,7 @@ curl_easy_pause - pause and unpause a connection Using this function, you can explicitly mark a running connection to get paused, and you can unpause a connection that was previously paused. -A connection can made to pause by using this function or by letting the read +A connection can be paused by using this function or by letting the read or the write callbacks return the proper magic return code (\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback that returns pause signals to the library that it couldn't take care of any @@ -56,7 +56,7 @@ it in an allocated buffer until the reading is again unpaused using this function. If the downloaded data is compressed and is asked to get uncompressed -automatially on download, libcurl will continue to uncompress the entire +automatically on download, libcurl will continue to uncompress the entire downloaded chunk and it will cache the data uncompressed. This has the side- effect that if you download something that is compressed a lot, it can result in a very large data amount needing to be allocated to save the data during diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 7053735f5..c3e4dd76c 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -49,7 +49,7 @@ one of the \&"performing" functions of the multi interface \fIcurl_multi_perform(3)\fP) - to allow libcurl to keep timeouts and retries etc to work. A timeout value of -1 means that there is no timeout at all, and 0 means that the timeout is already reached. Libcurl attempts to limit calling -this only when the fixed future timeout time actually change. See also +this only when the fixed future timeout time actually changes. See also \fICURLMOPT_TIMERDATA\fP. This callback can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP. (Added in 7.16.0) .IP CURLMOPT_TIMERDATA -- cgit v1.2.1 From 08cf6780ba8ea242cb451f07e14bb572079e22cf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 8 Oct 2008 10:39:43 +0000 Subject: - Igor Novoseltsev brought a patch that introduced two new options to curl_easy_setopt: CURLOPT_USERNAME and CURLOPT_PASSWORD that sort of deprecates the good old CURLOPT_USERPWD since they allow applications to set the user name and password independently and perhaps more importantly allow both to contain colon(s) which CURLOPT_USERPWD doesn't fully support. --- docs/libcurl/curl_easy_setopt.3 | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7d30fa697..36d956d94 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -601,14 +601,34 @@ to prevent accidental information leakage. 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. +.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 +\fICURLOPT_USERPWD\fP is used. In comparison to \fICURLOPT_USERPWD\fP the +CURLOPT_USERNAME allows the username to contain colon, like in 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. + +In order to specify the password to be used in conjunction with the user name +use the \fICURLOPT_PASSWORD\fP option. (Added in 7.19.1) +.IP CURLOPT_PASSWORD +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) .IP CURLOPT_HTTPAUTH Pass a long as parameter, which is set to a bitmask, to tell libcurl what 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 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. (Added in -7.10.6) +the actual name and password with the \fICURLOPT_USERPWD\fP option or +with the \fICURLOPT_USERNAME\fP and the \fICURLOPT_USERPASSWORD\fP options. +(Added in 7.10.6) .RS .IP CURLAUTH_BASIC HTTP Basic authentication. This is the default choice, and the only method -- cgit v1.2.1 From 6887106ff7e9be173f7cabe15da96a60194e1931 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 9 Oct 2008 20:03:04 +0000 Subject: Fixed a leftover reference to CURLOPT_FTP_SSL (thanks to Carlos Alloatti for spotting it). --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 36d956d94..298303994 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1085,7 +1085,7 @@ Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. .IP CURLOPT_FTPSSLAUTH Pass a long using one of the values from below, to alter how libcurl issues \&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see -\fICURLOPT_FTP_SSL\fP). (Added in 7.12.2) +\fICURLOPT_USE_SSL\fP). (Added in 7.12.2) .RS .IP CURLFTPAUTH_DEFAULT Allow libcurl to decide -- cgit v1.2.1 From 5af597c2fbbc68f77c35bd9c5c4574f0ea6a9be2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 16 Oct 2008 11:35:19 +0000 Subject: Added CURLINFO_CERTINFO --- docs/libcurl/curl_easy_getinfo.3 | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index b8fdf466e..44d01810b 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_getinfo 3 "21 Mar 2006" "libcurl 7.15.4" "libcurl Manual" +.TH curl_easy_getinfo 3 "16 Oct 2008" "libcurl 7.19.1" "libcurl Manual" .SH NAME curl_easy_getinfo - extract information from a curl handle .SH SYNOPSIS @@ -190,6 +190,15 @@ Pass a pointer to a 'char *' to receive a pointer to a string holding the path of the entry path. That is the initial path libcurl ended up in when logging on to the remote FTP server. This stores a NULL as pointer if something is wrong. (Added in 7.15.4) +.IP CURLINFO_CERTINFO +Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to +struct that holds a number of linked lists with info about the certificate +chain, assuming you had CURLOPT_CERTINFO enabled when the previous request was +done. The struct reports how many certs it found and then you can extract info +for each of those certs by following the linked lists. The info chain is +provided in a series of data in the format "name:content" where the content is +for the specific named data. See also the certinfo.c example. (Added in +7.19.1) .SH TIMES .NF An overview of the six time values available from curl_easy_getinfo() -- cgit v1.2.1 From 86c5d02a5e2ea6c7ae8fdfad59ee29e5316c7b94 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 16 Oct 2008 12:29:32 +0000 Subject: correct version number for the certinfo addition --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 298303994..cface443c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1516,7 +1516,7 @@ 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 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.0) +7.19.1) .IP CURLOPT_RANDOM_FILE Pass a char * to a zero terminated file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, -- cgit v1.2.1 From a8245df7457120e8aa1d85e870e5b2120674c13e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 16 Oct 2008 12:35:47 +0000 Subject: mention the openssl requirement for the certinfo data --- docs/libcurl/curl_easy_getinfo.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 44d01810b..d7ece13ea 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -197,7 +197,8 @@ chain, assuming you had CURLOPT_CERTINFO enabled when the previous request was done. The struct reports how many certs it found and then you can extract info for each of those certs by following the linked lists. The info chain is provided in a series of data in the format "name:content" where the content is -for the specific named data. See also the certinfo.c example. (Added in +for the specific named data. See also the certinfo.c example. NOTE: this +option is only available in libcurl built with OpenSSL support. (Added in 7.19.1) .SH TIMES .NF -- cgit v1.2.1 From a9a4300a367a4beeef0674240e6721d68f1b1ae3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 16 Oct 2008 20:21:22 +0000 Subject: - Igor Novoseltsev added CURLOPT_PROXYUSER and CURLOPT_PROXYPASSWORD that then make CURLOPT_PROXYUSERPWD sort of deprecated. The primary motive for adding these new options is that they have no problems with the colon separator that the CURLOPT_PROXYUSERPWD option does. --- docs/libcurl/curl_easy_setopt.3 | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index cface443c..9759e8fcc 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -620,6 +620,26 @@ 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) +.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". +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. + +In order to specify the password to be used in conjunction with the user name +use the \fICURLOPT_PROXYPASSWORD\fP option. (Added in 7.19.1) +.IP CURLOPT_PROXYPASSWORD +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) .IP CURLOPT_HTTPAUTH Pass a long as parameter, which is set to a bitmask, to tell libcurl what authentication method(s) you want it to use. The available bits are listed -- cgit v1.2.1 From 1d12b1fa1e260c14d55b1620cf4e251d16f3d6b6 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 16 Oct 2008 21:02:38 +0000 Subject: CURLOPT_POST301 => CURLOPT_POSTREDIR --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9759e8fcc..31482a168 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "30 Jul 2008" "libcurl 7.19.0" "libcurl Manual" +.TH curl_easy_setopt 3 "16 Oct 2008" "libcurl 7.19.1" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -729,13 +729,14 @@ redirections have been followed, the next redirect will cause an error \fICURLOPT_FOLLOWLOCATION\fP is used at the same time. Added in 7.15.1: Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite number of redirects (which is the default) -.IP CURLOPT_POST301 +.IP CURLOPT_POSTREDIR A parameter set to 1 tells the library to respect RFC 2616/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. 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) .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. -- cgit v1.2.1 From 98b13037e7a853d28d34a49f5d01b60480a67957 Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Fri, 17 Oct 2008 03:59:02 +0000 Subject: remove some spurious line-endings --- docs/libcurl/curl_easy_setopt.3 | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 31482a168..6ebda874c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -620,26 +620,26 @@ 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) -.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". -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. - -In order to specify the password to be used in conjunction with the user name -use the \fICURLOPT_PROXYPASSWORD\fP option. (Added in 7.19.1) -.IP CURLOPT_PROXYPASSWORD -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) +.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". +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. + +In order to specify the password to be used in conjunction with the user name +use the \fICURLOPT_PROXYPASSWORD\fP option. (Added in 7.19.1) +.IP CURLOPT_PROXYPASSWORD +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) .IP CURLOPT_HTTPAUTH Pass a long as parameter, which is set to a bitmask, to tell libcurl what authentication method(s) you want it to use. The available bits are listed -- cgit v1.2.1 From 6e0739931d3627f378abaa109fea4e62bcca1673 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 28 Oct 2008 10:21:19 +0000 Subject: Philippe Vaucher pointed out this use of an outdated option name... --- docs/libcurl/libcurl-tutorial.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 1a1b3980f..f006becb5 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -339,7 +339,7 @@ between the application and the callback. curl_easy_setopt(easyhandle, CURLOPT_READFUNCTION, read_function); - curl_easy_setopt(easyhandle, CURLOPT_INFILE, &filedata); + curl_easy_setopt(easyhandle, CURLOPT_READDATA, &filedata); Tell libcurl that we want to upload: -- cgit v1.2.1 From 9c86097286e960ae52249482a1e4c9d4e2075028 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Tue, 28 Oct 2008 23:48:05 +0000 Subject: Mention more restrictions on timeouts when using signals --- docs/libcurl/curl_easy_setopt.3 | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6ebda874c..9d0ebe84f 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "16 Oct 2008" "libcurl 7.19.1" "libcurl Manual" +.TH curl_easy_setopt 3 "28 Oct 2008" "libcurl 7.19.1" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -81,8 +81,10 @@ process. This option is mainly here to allow multi-threaded unix applications to still set/use all timeout options etc, without risking getting signals. (Added in 7.10) +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 -lookups. It enables nice timeouts for name resolves without signals. +lookups, which enables nice timeouts for name resolves without signals. .PP .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION @@ -1300,8 +1302,10 @@ In unix-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL\fP is set. .IP CURLOPT_TIMEOUT_MS Like \fICURLOPT_TIMEOUT\fP but takes number of milliseconds instead. If -libcurl is built to use the standard system name resolver, that part will -still use full-second resolution for timeouts. (Added in 7.16.2) +libcurl is built to use the standard system name resolver, that portion +of the transfer will still use full-second resolution for timeouts with +a minimum timeout allowed of one second. +(Added in 7.16.2) .IP CURLOPT_LOW_SPEED_LIMIT Pass a long as parameter. It contains the transfer speed in bytes per second that the transfer should be below during \fICURLOPT_LOW_SPEED_TIME\fP seconds @@ -1364,9 +1368,11 @@ timeouts). See also the \fICURLOPT_TIMEOUT\fP option. In unix-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL\fP is set. .IP CURLOPT_CONNECTTIMEOUT_MS -Like \fICURLOPT_CONNECTTIMEOUT\fP but takes number of milliseconds instead. If -libcurl is built to use the standard system name resolver, that part will -still use full-second resolution for timeouts. (Added in 7.16.2) +Like \fICURLOPT_CONNECTTIMEOUT\fP but takes the number of milliseconds +instead. If libcurl is built to use the standard system name resolver, +that portion of the connect will still use full-second resolution for +timeouts with a minimum timeout allowed of one second. +(Added in 7.16.2) .IP CURLOPT_IPRESOLVE Allows an application to select what kind of IP addresses to use when resolving host names. This is only interesting when using host names that -- cgit v1.2.1 From 5d791838d28045487cd716c565f4550d61b6b13a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 5 Nov 2008 21:48:00 +0000 Subject: mention the speed unit for the _SPEED_LARGE options from bug #2226722 --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9d0ebe84f..a8151b24b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1315,15 +1315,15 @@ Pass a long as parameter. It contains the time in seconds that the transfer should be below the \fICURLOPT_LOW_SPEED_LIMIT\fP for the library to consider it too slow and abort. .IP CURLOPT_MAX_SEND_SPEED_LARGE -Pass a curl_off_t as parameter. If an upload exceeds this speed on cumulative -average during the transfer, the transfer will pause to keep the average rate -less than or equal to the parameter value. Defaults to unlimited -speed. (Added in 7.15.5) +Pass a curl_off_t as parameter. If an upload exceeds this speed (counted in +bytes per second) on cumulative average during the transfer, the transfer will +pause to keep the average rate less than or equal to the parameter value. +Defaults to unlimited speed. (Added in 7.15.5) .IP CURLOPT_MAX_RECV_SPEED_LARGE -Pass a curl_off_t as parameter. If a download exceeds this speed on -cumulative average during the transfer, the transfer will pause to keep the -average rate less than or equal to the parameter value. Defaults to unlimited -speed. (Added in 7.15.5) +Pass a curl_off_t as parameter. If a download exceeds this speed (counted in +bytes per second) on cumulative average during the transfer, the transfer will +pause to keep the average rate less than or equal to the parameter +value. Defaults to unlimited speed. (Added in 7.15.5) .IP CURLOPT_MAXCONNECTS 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 -- cgit v1.2.1 From acc29ff1d980b9b1427495012a6ba9c075c36d3a Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Mon, 17 Nov 2008 08:16:25 +0000 Subject: Fixed an outdated mention of having keep strings around in curl_easy_setopt calls. Added a paragraph explaining that libcurl takes care of low-level protocol details. Made a few minor edits. --- docs/libcurl/libcurl-tutorial.3 | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index f006becb5..dfbae11da 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-tutorial 3 "27 Feb 2007" "libcurl" "libcurl programming" +.TH libcurl-tutorial 3 "17 Nov 2008" "libcurl" "libcurl programming" .SH NAME libcurl-tutorial \- libcurl programming tutorial .SH "Objective" @@ -41,7 +41,7 @@ refer to their respective man pages. .SH "Building" There are many different ways to build C programs. This chapter will assume a -unix-style build process. If you use a different build system, you can still +UNIX-style build process. If you use a different build system, you can still read this to get general information that may apply to your environment as well. .IP "Compiling the Program" @@ -167,11 +167,9 @@ something different. Alas, multiple requests using the same handle will use the same options. Many of the options you set in libcurl are "strings", pointers to data -terminated with a zero byte. Keep in mind that when you set strings with -\fIcurl_easy_setopt(3)\fP, libcurl will not copy the data. It will merely -point to the data. You MUST make sure that the data remains available for -libcurl to use until finished or until you use the same option again to point -to something else. +terminated with a zero byte. When you set strings with +\fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they don't +need to be kept around in your application after being set[4]. One of the most basic properties to set in the handle is the URL. You set your preferred URL to transfer with CURLOPT_URL in a manner similar to: @@ -245,14 +243,20 @@ again. Mind you, it is even preferred that you re-use an existing handle if you intend to make another transfer. libcurl will then attempt to re-use the previous connection. +For some protocols, downloading a file can involve a complicated process of +logging in, setting the transfer mode, changing the current directory and +finally transferring the file data. libcurl takes care of all that +complication for you. Given simply the URL to a file, libcurl will take care +of all the details needed to get the file moved from one machine to another. + .SH "Multi-threading Issues" The first basic rule is that you must \fBnever\fP share a libcurl handle (be it easy or multi or whatever) between multiple threads. Only use one handle in one thread at a time. libcurl is completely thread safe, except for two issues: signals and SSL/TLS -handlers. Signals are used timeouting name resolves (during DNS lookup) - when -built without c-ares support and not on Windows.. +handlers. Signals are used for timing out name resolves (during DNS lookup) - +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 @@ -350,7 +354,7 @@ knowledge of the expected file size. So, set the upload file size using the CURLOPT_INFILESIZE_LARGE for all known file sizes like this[1]: .nf - /* in this example, file_size must be an off_t variable */ + /* in this example, file_size must be an curl_off_t variable */ curl_easy_setopt(easyhandle, CURLOPT_INFILESIZE_LARGE, file_size); .fi @@ -389,7 +393,7 @@ to the CURLOPT_USERPWD option like this: curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); -There's a long time unix "standard" way of storing ftp user names and +There's a long time UNIX "standard" way of storing ftp user names and passwords, namely in the $HOME/.netrc file. The file should be made private so that only the user may read it (see also the "Security Considerations" chapter), as it might contain the password in plain text. libcurl has the @@ -1194,6 +1198,9 @@ This happens on Windows machines when libcurl is built and used as a DLL. However, you can still do this on Windows if you link with a static library. .IP "[3]" -The curl-config tool is generated at build-time (on unix-like systems) and +The curl-config tool is generated at build-time (on UNIX-like systems) and should be installed with the 'make install' or similar instruction that installs the library, header files, man pages etc. +.IP "[4]" +This behavior was different in versions before 7.17.0, where strings had to +remain valid past the end of the \fIcurl_easy_setopt(3)\fP call. -- cgit v1.2.1 From 32f78136b27a8a5a0df89c4b349ece4d53dcad03 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Tue, 9 Dec 2008 22:00:18 +0000 Subject: Documented CURLOPT_CONNECT_ONLY as being useful only on HTTP URLs. --- docs/libcurl/curl_easy_setopt.3 | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a8151b24b..38fe0ff40 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1388,6 +1388,7 @@ Resolve to ipv6 addresses. .IP CURLOPT_CONNECT_ONLY Pass a long. If the parameter equals 1, it tells the library to perform all the required proxy authentication and connection setup, but no data transfer. +This option is useful only on HTTP URLs. This option is useful with the \fICURLINFO_LASTSOCKET\fP option to \fIcurl_easy_getinfo(3)\fP. The library can set up the connection and then the -- cgit v1.2.1 From 6e376532b00879ead13d5e07453ab8dd0d97571e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Dec 2008 23:13:31 +0000 Subject: - Internet Explorer had a broken HTTP digest authentication before v7 and there are servers "out there" that relies on the client doing this broken Digest authentication. Apache even comes with an option to work with such broken clients. The difference is only for URLs that contain a query-part (a '?'-letter and text to the right of it). libcurl now supports this quirk, and you enable it by setting the CURLAUTH_DIGEST_IE bit in the bitmask you pass to the CURLOPT_HTTPAUTH or CURLOPT_PROXYAUTH options. They are thus individually controlled to server and proxy. --- docs/libcurl/curl_easy_setopt.3 | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 38fe0ff40..5e51aeffc 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "28 Oct 2008" "libcurl 7.19.1" "libcurl Manual" +.TH curl_easy_setopt 3 "11 Dec 2008" "libcurl 7.19.3" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -661,6 +661,13 @@ others. HTTP Digest authentication. Digest authentication is defined in RFC2617 and is a more secure way to do authentication over public networks than the regular old-fashioned Basic method. +.IP CURLAUTH_DIGEST_IE +HTTP Digest authentication with an IE flavor. Digest authentication is +defined in RFC2617 and is a more secure way to do authentication over public +networks than the regular old-fashioned Basic method. The IE flavor is simply +that libcurl will use a special "quirk" that IE is known to have used before +version 7 and that some servers require the client to use. (This define was +added in 7.19.3) .IP CURLAUTH_GSSNEGOTIATE HTTP GSS-Negotiate authentication. The GSS-Negotiate (also known as plain \&"Negotiate") method was designed by Microsoft and is used in their web -- cgit v1.2.1 From 000a13e21a30ca55da1fc7affe28fcb7c7171bb7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 19 Dec 2008 19:03:55 +0000 Subject: expand the CURLOPT_POSTREDIR explanation --- docs/libcurl/curl_easy_setopt.3 | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5e51aeffc..66412937b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -739,13 +739,20 @@ redirections have been followed, the next redirect will cause an error Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite number of redirects (which is the default) .IP CURLOPT_POSTREDIR -A parameter set to 1 tells the library to respect RFC 2616/10.3.2 and not -convert POST requests into GET requests when following a 301 redirection. The -non-RFC behaviour is ubiquitous in web browsers, so the library does the +Pass a bitmask to control how libcurl acts on redirects after POSTs that get a +301 or 302 response back. A parameter with bit 0 set (value +\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 2616/10.3.2 and +not convert POST requests into GET requests when following a 301 +redirection. Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain +the request method after a 302 redirect. 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) +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. -- cgit v1.2.1 From d5bfec70af0d53eed164c9fdec142ebe8fe5c81d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 22 Dec 2008 13:07:13 +0000 Subject: - Anthony Bryan provided a set of patches that cleaned up manual language, corrected spellings and more. --- docs/libcurl/libcurl.3 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 9c48f7405..fb33a5e14 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -4,7 +4,7 @@ .SH NAME libcurl \- client-side URL transfers .SH DESCRIPTION -This is an short overview on how to use libcurl in your C programs. There are +This is a short overview on how to use libcurl in your C programs. There are specific man pages for each function mentioned in here. There are also the \fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the \fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for @@ -25,14 +25,14 @@ the option of using the "easy" interface, or the "multi" interface. The easy interface is a synchronous interface with which you call \fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is -completed, the function return and you can continue. More details are found in +completed, the function returns and you can continue. More details are found in the \fIlibcurl-easy(3)\fP man page. The multi interface on the other hand is an asynchronous interface, that you call and that performs only a little piece of the transfer on each invoke. It is perfect if you want to do things while the transfer is in progress, or similar. The multi interface allows you to select() on libcurl action, and -even to easily download multiple files simultaneously using a single thread. See further deails in the \fIlibcurl-multi(3)\fP man page. +even to easily download multiple files simultaneously using a single thread. See further details in the \fIlibcurl-multi(3)\fP man page. You can have multiple easy handles share certain data, even if they are used in different threads. This magic is setup using the share interface, as @@ -106,7 +106,7 @@ do as many of your file transfers as possible using the same curl handle. When you call \fIcurl_easy_cleanup(3)\fP, all the possibly open connections held by libcurl will be closed and forgotten. -Note that the options set with \fIcurl_easy_setopt(3)\fP will be used in on +Note that the options set with \fIcurl_easy_setopt(3)\fP will be used on every repeated \fIcurl_easy_perform(3)\fP call. .SH "GLOBAL CONSTANTS" @@ -161,7 +161,7 @@ and has a place to call the libcurl functions. Note that if multiple modules in the program use libcurl, they all will separately call the libcurl functions, and that's OK because only the first \fIcurl_global_init()\fP and the last \fIcurl_global_cleanup()\fP in a -program changes anything. (libcurl uses a reference count in static +program change anything. (libcurl uses a reference count in static memory). In a C++ module, it is common to deal with the global constant -- cgit v1.2.1 From 6d2ff9d2a7700ab2c2abc9723f95a79404652eec Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 28 Dec 2008 21:29:13 +0000 Subject: Anthony Bryan reported this outputs wrong in the PDF and I've now tried to escape these letters what I think is the correct way. --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 66412937b..01618bbf5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1597,9 +1597,9 @@ The checking this option controls is of the identity that the server .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, -it consists of one or more cipher strings separated by colons. Commas or spaces -are also acceptable separators but colons are normally used, \!, \- and \+ can -be used as operators. +it consists of one or more cipher strings separated by colons. Commas or +spaces are also acceptable separators but colons are normally used, \&!, \&- +and \&+ can be used as operators. For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', \'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you -- cgit v1.2.1 From 4f0a7170af076dd6b2594d30b09ce70d11813d94 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 28 Dec 2008 21:31:55 +0000 Subject: The CURLOPT_KRBLEVEL description wasn't properly formatted and thus was corrupted in ouputs. Another report from Anthony Bryan. --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 01618bbf5..59d2da26e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1623,9 +1623,9 @@ cache. Note that while nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0) .IP CURLOPT_KRBLEVEL -Pass a char * as parameter. Set the kerberos security level for FTP; this -also enables kerberos awareness. This is a string, 'clear', 'safe', -'confidential' or \&'private'. If the string is set but doesn't match one +Pass a char * as parameter. Set the kerberos security level for FTP; this also +enables kerberos awareness. This is a string, \&'clear', \&'safe', +\&'confidential' or \&'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos support for FTP. -- cgit v1.2.1 From 60ff74140e2bf778bbed208b4d4422f958baa32d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 28 Dec 2008 21:35:53 +0000 Subject: Anthony Bryan reported and I corrected two typos. --- docs/libcurl/libcurl-tutorial.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index dfbae11da..f3d6ef72b 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -191,8 +191,8 @@ similar to this: curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data); -You can control what data your function get in the forth argument by setting -another property: +You can control what data your callback function gets in the fourth argument +by setting another property: curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct); -- cgit v1.2.1 From 27b8a5fd84faf025fffa2154786e55c45c9e499a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 28 Dec 2008 21:43:34 +0000 Subject: Anthony Bryan reported quirks, I updated --- docs/libcurl/libcurl-tutorial.3 | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index f3d6ef72b..dd4be66c4 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -284,9 +284,8 @@ 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 not honored during the DNS lookup - which you can work around by building libcurl with c-ares support. c-ares is a library that provides asynchronous -name resolves. Unfortunately, c-ares does not yet fully support IPv6. On some -platforms, libcurl simply will not function properly multi-threaded unless -this option is set. +name resolves. On some platforms, libcurl simply will not function properly +multi-threaded unless this option is set. Also, note that CURLOPT_DNS_USE_GLOBAL_CACHE is not thread-safe. @@ -977,7 +976,7 @@ are then use 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 -figure out which cookies to use. Set header file to read cookies from with +figure out which cookies to use. Set the header file to read cookies from with CURLOPT_COOKIEFILE. The CURLOPT_COOKIEFILE option also automatically enables the cookie parser in @@ -986,9 +985,9 @@ understand incoming cookies and they will just be ignored. However, when the parser is enabled the cookies will be understood and the cookies will be kept in memory and used properly in subsequent requests when the same handle is used. Many times this is enough, and you may not have to save the cookies to -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 able might be to use a file name you know doesn't exist. +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 Netscape or Mozilla browsers, you can make libcurl use that cookie file as @@ -1094,14 +1093,12 @@ Many of the protocols libcurl supports send name and password unencrypted as clear text (HTTP Basic authentication, FTP, TELNET etc). It is very easy for anyone on your network or a network nearby yours, to just fire up a network analyzer tool and eavesdrop on your passwords. Don't let the fact that HTTP -uses base64 encoded passwords fool you. They may not look readable at a first -glance, but they very easily "deciphered" by anyone within seconds. - -To avoid this problem, use protocols that don't let snoopers see your -password: HTTPS, FTPS and FTP-kerberos are a few examples. HTTP Digest -authentication allows this too, but isn't supported by libcurl as of this -writing. +Basic uses base64 encoded passwords fool you. They may not look readable at a +first glance, but they very easily "deciphered" by anyone within seconds. +To avoid this problem, use HTTP athentication methods or other protocols that +don't let snoopers see your password: HTTP with Digest, NTLM or GSS +authentication, HTTPS, FTPS, SCP, SFTP and FTP-kerberos are a few examples. .IP "Showing What You Do" 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 -- cgit v1.2.1 From f61cfc59314e4779c13312efc4845f580f0933b1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 28 Dec 2008 21:56:56 +0000 Subject: Anthony Bryan's man page cleanup in language and spelling --- docs/libcurl/curl_easy_pause.3 | 2 +- docs/libcurl/curl_easy_setopt.3 | 163 ++++++++++++++++++------------------ docs/libcurl/curl_formfree.3 | 2 +- docs/libcurl/curl_formget.3 | 2 +- docs/libcurl/curl_getdate.3 | 6 +- docs/libcurl/curl_getenv.3 | 2 +- docs/libcurl/curl_global_init.3 | 2 +- docs/libcurl/curl_mprintf.3 | 6 +- docs/libcurl/curl_multi_assign.3 | 4 +- docs/libcurl/curl_multi_fdset.3 | 6 +- docs/libcurl/curl_multi_info_read.3 | 4 +- docs/libcurl/curl_multi_init.3 | 2 +- docs/libcurl/curl_multi_perform.3 | 6 +- docs/libcurl/curl_multi_setopt.3 | 8 +- docs/libcurl/curl_multi_socket.3 | 10 +-- docs/libcurl/curl_share_init.3 | 2 +- docs/libcurl/curl_share_setopt.3 | 4 +- docs/libcurl/curl_strequal.3 | 2 +- docs/libcurl/curl_version_info.3 | 12 +-- docs/libcurl/libcurl-errors.3 | 60 ++++++------- docs/libcurl/libcurl-multi.3 | 2 +- docs/libcurl/libcurl-tutorial.3 | 92 ++++++++++---------- 22 files changed, 199 insertions(+), 200 deletions(-) (limited to 'docs/libcurl') 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 .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 @@ -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 @@ -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 -- cgit v1.2.1 From 9aea3e265d8919aea04bb6791673d5718399936d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 29 Dec 2008 21:26:11 +0000 Subject: further clarifcation based on input from Anthony Bryan --- docs/libcurl/curl_easy_setopt.3 | 26 ++++++++++++++------------ docs/libcurl/libcurl-tutorial.3 | 8 ++++---- 2 files changed, 18 insertions(+), 16 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d46ab9426..5aa64f553 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -607,12 +607,9 @@ the authentication method. 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 the same way that -\fICURLOPT_USERPWD\fP is used. In comparison to \fICURLOPT_USERPWD\fP the -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. +\fBCURLOPT_USERNAME\fP sets the user name to be used in protocol +authentication. You should not use this option together with the (older) +CURLOPT_USERPWD option. In order to specify the password to be used in conjunction with the user name use the \fICURLOPT_PASSWORD\fP option. (Added in 7.19.1) @@ -1212,12 +1209,17 @@ 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. -Note that libcurl will still act and assume the keyword it would use if you -didn't set your custom one is the one in use and it will act according to -that. Thus, changing this to a HEAD when libcurl otherwise would do a GET -might cause libcurl to act funny, and similar. To switch to a proper HEAD, use -\fICURLOPT_NOBODY\fP, to switch to a proper POST, use \fICURLOPT_POST\fP or -\fICURLOPT_POSTFIELDS\fP and so on. +When you change the request method by setting \fBCURLOPT_CUSTOMREQUEST\fP to +something, you don't actually change how libcurl behaves or acts in regards to +the particular request method, it will only change the actual string sent in +the request. + +For example: if you tell libcurl to do a HEAD request, but then change the +request to a "GET" with \fBCURLOPT_CUSTOMREQUEST\fP you'll still see libcurl +act as if it sent a HEAD even when it does send a GET. + +To switch to a proper HEAD, use \fICURLOPT_NOBODY\fP, to switch to a proper +POST, use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and so on. Restore to the internal default by setting this to NULL. diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 10474be4a..3c36c7357 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -987,11 +987,11 @@ in memory and used properly in subsequent requests when the same handle is used. Many times this is enough, and you may not have to save the cookies to 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. +not read any cookies is to use the name of a file you know doesn't exist. -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 +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. Perhaps the most advanced cookie operation libcurl offers, is saving the -- cgit v1.2.1 From 2f9038bf629335d0b23a7bde2e002bf587a2cd33 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 Jan 2009 21:22:51 +0000 Subject: Mohun Biswas clarified --- docs/libcurl/curl_formadd.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index e55c542f2..190a6b20d 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -106,8 +106,9 @@ long which gives the length of the buffer. Tells libcurl to use the \fICURLOPT_READFUNCTION\fP callback to get data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on to the read callback's fourth argument. If you want the part to look like a file -upload one, set the \fICURLFORM_FILENAME\fP parameter as well. (Option added -in libcurl 7.18.2) +upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that when +using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be set +with the total expected length of the part. (Option added in libcurl 7.18.2) .IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as -- cgit v1.2.1 From 5aeef9c1c87f2f72f10807a609ced1976ab46cd2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 25 Jan 2009 23:26:25 +0000 Subject: - Craig A West brought CURLOPT_NOPROXY and the corresponding --noproxy option. They basically offer the same thing the NO_PROXY environment variable only offered previously: list a set of host names that shall not use the proxy even if one is specified. --- docs/libcurl/curl_easy_setopt.3 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5aa64f553..c9bc0365c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -474,6 +474,14 @@ this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and \fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is default. (Added in 7.10) +.IP CURLOPT_NOPROXY +Pass a pointer to a zero terminated string. The should be a comma- separated +list of hosts which do not use a proxy, if one is specified. The only +wildcard is a single * character, which matches all hosts, and effectively +disables the proxy. Each name in this list is matched as either a domain which +contains the hostname, or the hostname itself. For example, local.com would +match local.com, local.com:80, and www.local.com, but not www.notlocal.com. +(Added in 7.19.4) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to 1 to make the library tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy and to -- cgit v1.2.1 From 0516ce7786e9500c2e447d48aa9b3f24a6ca70f9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Jan 2009 22:43:06 +0000 Subject: - Chad Monroe provided the new CURLOPT_TFTP_BLKSIZE option that allows an app to set desired block size to use for TFTP transfers instead of the default 512 bytes. --- docs/libcurl/curl_easy_setopt.3 | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c9bc0365c..e0a6bc687 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1008,6 +1008,14 @@ Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. (added in 7.16.2) +.SH TFTP OPTIONS +.IP CURLOPT_TFTPBLKSIZE +Specify block size to use for TFTP data transmission. Valid range as per RFC +2348 is 8-65464 bytes. The default of 512 bytes will be used if this option is +not specified. The specified block size will only be used pending support by +the remote server. If the server does not return an option acknowledgement or +returns an option acknowledgement with no blksize, the default of 512 bytes +will be used. (added in 7.19.4) .SH FTP OPTIONS .IP CURLOPT_FTPPORT Pass a pointer to a zero terminated string as parameter. It will be used to -- cgit v1.2.1 From de4610a55f9e99bebaf448ca33e2e43baf977c74 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 28 Jan 2009 21:33:58 +0000 Subject: - Markus Moeller introduced two new options to libcurl: CURLOPT_SOCKS5_GSSAPI_SERVICE and CURLOPT_SOCKS5_GSSAPI_NEC to allow libcurl to do GSS-style authentication with SOCKS5 proxies. The curl tool got the options called --socks5-gssapi-service and --socks5-gssapi-nec to enable these. --- docs/libcurl/curl_easy_setopt.3 | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e0a6bc687..c6e6013b5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -487,6 +487,16 @@ Set the parameter to 1 to make the library tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy and to tunnel through it. If you don't know what this means, you probably don't want this tunneling option. +.IP CURLOPT_SOCKS5_GSSAPI_SERVICE +Pass a char * as parameter to a string holding the name of the service. The +default service name for a SOCKS5 server is rcmd/server-fqdn. This option +allows you to change it. (Added in 7.19.4) +.IP CURLOPT_SOCKS5_GSSAPI_NEC +Pass a long set to 1 to enable or 0 to disable. As part of the gssapi +negotiation a protection mode is negotiated. The rfc1961 says in section +4.3/4.4 it should be protected, but the NEC reference implementation does not. +If enabled, this option allows the unprotected exchange of the protection mode +negotiation. (Added in 7.19.4). .IP CURLOPT_INTERFACE 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 -- cgit v1.2.1 From bdd4294e79eea15cb6f312f7ee7d388ad40a65e3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 Feb 2009 16:19:23 +0000 Subject: - Craig A West brought us: libcurl now defaults to do CONNECT with HTTP version 1.1 instead of 1.0 like before. This change also introduces the new proxy type for libcurl called 'CURLPROXY_HTTP_1_0' that then allows apps to switch (back) to CONNECT 1.0 requests. The curl tool also got a --proxy1.0 option that works exactly like --proxy but sets CURLPROXY_HTTP_1_0. I updated all test cases cases that use CONNECT and I tried to do some using --proxy1.0 and some updated to do CONNECT 1.1 to get both versions run. --- docs/libcurl/curl_easy_setopt.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c6e6013b5..579016bb7 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -470,10 +470,10 @@ Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. .IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for -this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_SOCKS4\fP (added in 7.15.2), -\fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and -\fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is -default. (Added in 7.10) +this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP (added in 7.19.4), +\fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5\fP, +\fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and \fICURLPROXY_SOCKS5_HOSTNAME\fP +(added in 7.18.0). The HTTP type is default. (Added in 7.10) .IP CURLOPT_NOPROXY Pass a pointer to a zero terminated string. The should be a comma- separated list of hosts which do not use a proxy, if one is specified. The only -- cgit v1.2.1 From 44c02227e9220dfa2aaefa6be8827261da56d05c Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 6 Feb 2009 19:25:32 +0000 Subject: Mention the first release of CURLOPT_FTP_FILEMETHOD --- docs/libcurl/curl_easy_setopt.3 | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 579016bb7..09e3de3fd 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1190,6 +1190,7 @@ libcurl does one CWD with the full target directory and then operates on the file \&"normally" (like in the multicwd case). This is somewhat more standards compliant than 'nocwd' but without the full penalty of 'multicwd'. .RE +(Added in 7.15.1) .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A parameter set to 1 tells the library to use ASCII mode for FTP transfers, -- cgit v1.2.1 From 5c4cdcb2d5f4bbcb35b7ce0a87190dd2fb0b1fd7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Feb 2009 12:32:12 +0000 Subject: mention when CURLOPT_ADDRESS_SCOPE was added --- docs/libcurl/curl_easy_setopt.3 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 09e3de3fd..fc61f2804 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -563,7 +563,7 @@ data at a time, and can contribute to congestion on the network if overdone. .IP CURLOPT_ADDRESS_SCOPE Pass a long specifying the scope_id value to use when connecting to IPv6 -link-local or site-local addresses. +link-local or site-local addresses. (Added in 7.19.0) .SH NAMES and PASSWORDS OPTIONS (Authentication) .IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and @@ -861,7 +861,6 @@ copy. In any case, the size must not be changed after \fICURLOPT_COPYPOSTFIELDS\fP, unless another \fICURLOPT_POSTFIELDS\fP or \fICURLOPT_COPYPOSTFIELDS\fP option is issued. (Added in 7.17.1) - .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 -- cgit v1.2.1 From c65f9acdc7cffe7b5803d35f64266f27de60bafc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Feb 2009 12:33:10 +0000 Subject: introducing the symbols-in-versions file, in an effort to help app authors to better know and track symbols in earlier libcurl versions --- docs/libcurl/symbols-in-versions | 292 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 docs/libcurl/symbols-in-versions (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions new file mode 100644 index 000000000..9c712a112 --- /dev/null +++ b/docs/libcurl/symbols-in-versions @@ -0,0 +1,292 @@ + _ _ ____ _ + ___| | | | _ \| | + / __| | | | |_) | | + | (__| |_| | _ <| |___ + \___|\___/|_| \_\_____| + + This document lists defines and other symbols present in libcurl, together + with exact information about the first libcurl version that provides the + symbol, the first version in which the symbol was marked as deprecated and + for a few symbols the last version that featured it. The names appear in + alphabetical order. + + Name Introduced Deprecated Removed + +CURLAUTH_ANY 7.10.6 +CURLAUTH_ANYSAFE 7.10.6 +CURLAUTH_BASIC 7.10.6 +CURLAUTH_DIGEST 7.10.6 +CURLAUTH_DIGEST_IE 7.19.3 +CURLAUTH_GSSNEGOTIATE 7.10.6 +CURLAUTH_NTLM 7.10.6 +CURLFTPAUTH_DEFAULT 7.12.2 +CURLFTPAUTH_DEFAULT 7.12.2 +CURLFTPAUTH_SSL 7.12.2 +CURLFTPAUTH_SSL 7.12.2 +CURLFTPAUTH_TLS 7.12.2 +CURLFTPAUTH_TLS 7.12.2 +CURLFTPMETHOD_MULTICWD 7.15.1 +CURLFTPMETHOD_NOCWD 7.15.1 +CURLFTPMETHOD_SINGLECWD 7.15.1 +CURLFTPSSL_CCC_ACTIVE 7.16.1 +CURLFTPSSL_CCC_NONE 7.16.1 +CURLFTPSSL_CCC_PASSIVE 7.16.1 +CURLINFO_APPCONNECT_TIME 7.19.0 +CURLINFO_CERTINFO 7.19.1 +CURLINFO_CONNECT_TIME 7.4.1 +CURLINFO_CONTENT_LENGTH_DOWNLOAD 7.6.1 +CURLINFO_CONTENT_LENGTH_UPLOAD 7.6.1 +CURLINFO_CONTENT_TYPE 7.9.4 +CURLINFO_COOKIELIST 7.14.1 +CURLINFO_DATA_IN 7.9.6 +CURLINFO_DATA_OUT 7.9.6 +CURLINFO_FILETIME 7.5 +CURLINFO_FTP_ENTRY_PATH 7.15.4 +CURLINFO_HEADER_IN 7.9.6 +CURLINFO_HEADER_OUT 7.9.6 +CURLINFO_HEADER_SIZE 7.4.1 +CURLINFO_HTTPAUTH_AVAIL 7.10.8 +CURLINFO_HTTP_CODE 7.4.1 7.10.8 +CURLINFO_HTTP_CONNECTCODE 7.10.7 +CURLINFO_LASTSOCKET 7.15.2 +CURLINFO_NAMELOOKUP_TIME 7.4.1 +CURLINFO_NUM_CONNECTS 7.12.3 +CURLINFO_OS_ERRNO 7.12.2 +CURLINFO_PRETRANSFER_TIME 7.4.1 +CURLINFO_PRIMARY_IP 7.19.0 +CURLINFO_PRIVATE 7.10.3 +CURLINFO_PRIVATE 7.10.3 +CURLINFO_PROXYAUTH_AVAIL 7.10.8 +CURLINFO_REDIRECT_COUNT 7.9.7 +CURLINFO_REDIRECT_TIME 7.9.7 +CURLINFO_REDIRECT_URL 7.18.2 +CURLINFO_REQUEST_SIZE 7.4.1 +CURLINFO_RESPONSE_CODE 7.10.8 +CURLINFO_SIZE_DOWNLOAD 7.4.1 +CURLINFO_SIZE_UPLOAD 7.4.1 +CURLINFO_SPEED_DOWNLOAD 7.4.1 +CURLINFO_SPEED_UPLOAD 7.4.1 +CURLINFO_SSL_ENGINES 7.12.3 +CURLINFO_SSL_VERIFYRESULT 7.5 +CURLINFO_STARTTRANSFER_TIME 7.9.2 +CURLINFO_TEXT 7.9.6 +CURLINFO_TOTAL_TIME 7.4.1 +CURLOPT_ADDRESS_SCOPE 7.19.0 +CURLOPT_APPEND 7.16.4 +CURLOPT_AUTOREFERER 7.1 +CURLOPT_BUFFERSIZE 7.10 +CURLOPT_CAINFO 7.4.2 +CURLOPT_CAPATH 7.9.8 +CURLOPT_CERTINFO 7.19.1 +CURLOPT_CLOSEFUNCTION 7.7 7.11.1 7.15.4 +CURLOPT_CLOSEPOLICY 7.7 7.16.1 +CURLOPT_CONNECTTIMEOUT 7.7 +CURLOPT_CONNECTTIMEOUT_MS 7.16.2 +CURLOPT_CONNECT_ONLY 7.15.2 +CURLOPT_CONV_FROM_NETWORK_FUNCTION 7.15.4 +CURLOPT_CONV_FROM_UTF8_FUNCTION 7.15.4 +CURLOPT_CONV_TO_NETWORK_FUNCTION 7.15.4 +CURLOPT_COOKIE 7.1 +CURLOPT_COOKIEFILE 7.1 +CURLOPT_COOKIEJAR 7.9 +CURLOPT_COOKIELIST 7.17.1 +CURLOPT_COOKIESESSION 7.9.7 +CURLOPT_COPYPOSTFIELDS 7.17.1 +CURLOPT_CRLF 7.1 +CURLOPT_CRLFILE 7.19.0 +CURLOPT_CUSTOMREQUEST 7.1 +CURLOPT_DEBUGDATA 7.9.6 +CURLOPT_DEBUGFUNCTION 7.9.6 +CURLOPT_DIRLISTONLY 7.16.4 +CURLOPT_DNS_CACHE_TIMEOUT 7.9.3 +CURLOPT_DNS_USE_GLOBAL_CACHE 7.9.3 7.11.1 +CURLOPT_EGDSOCKET 7.7 +CURLOPT_ENCODING 7.12.2 +CURLOPT_ERRORBUFFER 7.1 +CURLOPT_FAILONERROR 7.1 +CURLOPT_FILE 7.1 7.9.7 +CURLOPT_FILETIME 7.5 +CURLOPT_FLAGS 7.1 - 7.9.2 +CURLOPT_FOLLOWLOCATION 7.1 +CURLOPT_FORBID_REUSE 7.7 +CURLOPT_FRESH_CONNECT 7.7 +CURLOPT_FTPAPPEND 7.1 7.16.4 +CURLOPT_FTPASCII 7.1 7.11.1 7.15.4 +CURLOPT_FTPLISTONLY 7.1 7.16.4 +CURLOPT_FTPPORT 7.1 +CURLOPT_FTPSSLAUTH 7.12.2 +CURLOPT_FTP_ACCOUNT 7.13.1 +CURLOPT_FTP_ALTERNATIVE_TO_USER 7.15.5 +CURLOPT_FTP_CREATE_MISSING_DIRS 7.10.7 +CURLOPT_FTP_FILEMETHOD 7.15.1 +CURLOPT_FTP_RESPONSE_TIMEOUT 7.10.8 +CURLOPT_FTP_SKIP_PASV_IP 7.15.0 +CURLOPT_FTP_SSL 7.11.0 7.16.4 +CURLOPT_FTP_SSL_CCC 7.16.1 +CURLOPT_FTP_USE_EPRT 7.10.5 +CURLOPT_FTP_USE_EPSV 7.9.2 +CURLOPT_HEADER 7.1 +CURLOPT_HEADERFUNCTION 7.7.2 +CURLOPT_HTTP200ALIASES 7.10.3 +CURLOPT_HTTPAUTH 7.10.6 +CURLOPT_HTTPGET 7.8.1 +CURLOPT_HTTPHEADER 7.1 +CURLOPT_HTTPPOST 7.1 +CURLOPT_HTTPPROXYTUNNEL 7.3 +CURLOPT_HTTPREQUEST 7.1 - 7.15.4 +CURLOPT_HTTP_CONTENT_DECODING 7.16.2 +CURLOPT_HTTP_TRANSFER_DECODING 7.16.2 +CURLOPT_HTTP_VERSION 7.9.1 +CURLOPT_IGNORE_CONTENT_LENGTH 7.14.1 +CURLOPT_INFILE 7.1 7.9.7 +CURLOPT_INFILESIZE 7.1 +CURLOPT_INFILESIZE_LARGE 7.11.0 +CURLOPT_INTERFACE 7.3 +CURLOPT_IOCTLDATA 7.12.3 +CURLOPT_IOCTLFUNCTION 7.12.3 +CURLOPT_IPRESOLVE 7.10.8 +CURLOPT_ISSUERCERT 7.19.0 +CURLOPT_KEYPASSWD 7.17.0 +CURLOPT_KRB4LEVEL 7.3 +CURLOPT_KRBLEVEL 7.16.4 +CURLOPT_LOCALPORT 7.15.2 +CURLOPT_LOCALPORTRANGE 7.15.2 +CURLOPT_LOW_SPEED_LIMIT 7.1 +CURLOPT_LOW_SPEED_TIME 7.1 +CURLOPT_MAXCONNECTS 7.7 +CURLOPT_MAXFILESIZE 7.10.8 +CURLOPT_MAXFILESIZE_LARGE 7.11.0 +CURLOPT_MAXREDIRS 7.5 +CURLOPT_MAX_RECV_SPEED_LARGE 7.15.5 +CURLOPT_MAX_SEND_SPEED_LARGE 7.15.5 +CURLOPT_MUTE 7.1 7.8 7.15.4 +CURLOPT_NETRC 7.1 +CURLOPT_NETRC_FILE 7.11.0 +CURLOPT_NEW_DIRECTORY_PERMS 7.16.4 +CURLOPT_NEW_FILE_PERMS 7.16.4 +CURLOPT_NOBODY 7.1 +CURLOPT_NOPROGRESS 7.1 +CURLOPT_NOPROXY 7.19.4 +CURLOPT_NOSIGNAL 7.10 +CURLOPT_OPENSOCKETDATA 7.17.1 +CURLOPT_OPENSOCKETFUNCTION 7.17.1 +CURLOPT_PASSWDDATA 7.1 7.11.1 7.15.4 +CURLOPT_PASSWDFUNCTION 7.1 7.11.1 7.15.4 +CURLOPT_PASSWORD 7.19.1 +CURLOPT_PASV_POST 7.12.1 - 7.13.0 +CURLOPT_PORT 7.1 +CURLOPT_POST 7.1 +CURLOPT_POST301 7.17.1 7.19.1 +CURLOPT_POSTFIELDS 7.1 +CURLOPT_POSTFIELDSIZE 7.2 +CURLOPT_POSTFIELDSIZE_LARGE 7.11.1 +CURLOPT_POSTQUOTE 7.1 +CURLOPT_POSTREDIR 7.19.1 +CURLOPT_PREQUOTE 7.9.5 +CURLOPT_PRIVATE 7.10.3 +CURLOPT_PROGRESSDATA 7.1 +CURLOPT_PROGRESSFUNCTION 7.1 +CURLOPT_PROGRESSMODE 7.1 - 7.9.2 +CURLOPT_PROXY 7.1 +CURLOPT_PROXYAUTH 7.10.7 +CURLOPT_PROXYPASSWORD 7.19.1 +CURLOPT_PROXYPORT 7.1 +CURLOPT_PROXYTYPE 7.10 +CURLOPT_PROXYUSERNAME 7.19.1 +CURLOPT_PROXYUSERPWD 7.1 +CURLOPT_PROXY_TRANSFER_MODE 7.18.0 +CURLOPT_PUT 7.1 +CURLOPT_QUOTE 7.1 +CURLOPT_RANDOM_FILE 7.7 +CURLOPT_RANGE 7.1 +CURLOPT_READDATA 7.9.7 +CURLOPT_READFUNCTION 7.1 +CURLOPT_REFERER 7.1 +CURLOPT_RESUME_FROM 7.1 +CURLOPT_RESUME_FROM_LARGE 7.11.0 +CURLOPT_SEEKDATA 7.18.1 +CURLOPT_SEEKFUNCTION 7.18.1 +CURLOPT_SHARE 7.10 +CURLOPT_SOCKOPTDATA 7.16.0 +CURLOPT_SOCKOPTFUNCTION 7.16.0 +CURLOPT_SOCKS5_GSSAPI_NEC 7.19.4 +CURLOPT_SOCKS5_GSSAPI_SERVICE 7.19.4 +CURLOPT_SOURCE_HOST 7.12.1 - 7.13.0 +CURLOPT_SOURCE_PATH 7.12.1 - 7.13.0 +CURLOPT_SOURCE_PORT 7.12.1 - 7.13.0 +CURLOPT_SOURCE_POSTQUOTE 7.12.1 - 7.15.4 +CURLOPT_SOURCE_PREQUOTE 7.12.1 - 7.15.4 +CURLOPT_SOURCE_QUOTE 7.13.0 - 7.15.4 +CURLOPT_SOURCE_URL 7.13.0 - 7.15.4 +CURLOPT_SOURCE_USERPWD 7.12.1 - 7.15.4 +CURLOPT_SSH_AUTH_TYPES 7.16.1 +CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 7.17.1 +CURLOPT_SSH_PRIVATE_KEYFILE 7.16.1 +CURLOPT_SSH_PUBLIC_KEYFILE 7.16.1 +CURLOPT_SSLCERT 7.1 +CURLOPT_SSLCERTTYPE 7.9.3 +CURLOPT_SSLENGINE 7.9.3 +CURLOPT_SSLENGINE_DEFAULT 7.9.3 +CURLOPT_SSLKEY 7.9.3 +CURLOPT_SSLKEYPASSWD 7.17.0 +CURLOPT_SSLKEYTYPE 7.9.3 +CURLOPT_SSLVERSION 7.1 +CURLOPT_SSL_CIPHER_LIST 7.9 +CURLOPT_SSL_CTX_DATA 7.10.6 +CURLOPT_SSL_CTX_FUNCTION 7.10.6 +CURLOPT_SSL_SESSIONID_CACHE 7.16.0 +CURLOPT_SSL_VERIFYHOST 7.8.1 +CURLOPT_SSL_VERIFYPEER 7.4.2 +CURLOPT_STDERR 7.1 +CURLOPT_TCP_NODELAY 7.11.2 +CURLOPT_TELNETOPTIONS 7.7 +CURLOPT_TFTPBLKSIZE 7.19.4 +CURLOPT_TIMECONDITION 7.1 +CURLOPT_TIMEOUT 7.1 +CURLOPT_TIMEOUT_MS 7.16.2 +CURLOPT_TIMEVALUE 7.1 +CURLOPT_TRANSFERTEXT 7.11.1 +CURLOPT_UNRESTRICTED_AUTH 7.10.4 +CURLOPT_UPLOAD 7.1 +CURLOPT_URL 7.1 +CURLOPT_USERAGENT 7.1 +CURLOPT_USERNAME 7.19.1 +CURLOPT_USERPWD 7.1 +CURLOPT_USE_SSL 7.17.0 +CURLOPT_VERBOSE 7.1 +CURLOPT_WRITEDATA 7.9.7 +CURLOPT_WRITEFUNCTION 7.1 +CURLOPT_WRITEHEADER 7.1 +CURLPROXY_HTTP 7.10 +CURLPROXY_SOCKS4 7.10 +CURLPROXY_SOCKS4 7.10 +CURLUSESSL_ALL 7.17.0 +CURLUSESSL_CONTROL 7.17.0 +CURLUSESSL_NONE 7.17.0 +CURLUSESSL_TRY 7.17.0 +CURL_HTTP_VERSION_1_0 7.9.1 +CURL_HTTP_VERSION_1_1 7.9.1 +CURL_HTTP_VERSION_NONE 7.9.1 +CURL_IPRESOLVE_V4 7.10.8 +CURL_IPRESOLVE_V6 7.10.8 +CURL_IPRESOLVE_WHATEVER 7.10.8 +CURL_NETRC_IGNORED 7.9.8 +CURL_NETRC_OPTIONAL 7.9.8 +CURL_NETRC_REQUIRED 7.9.8 +CURL_SSLVERSION_DEFAULT 7.9.2 +CURL_SSLVERSION_SSLv2 7.9.2 +CURL_SSLVERSION_SSLv3 7.9.2 +CURL_SSLVERSION_TLSv1 7.9.2 +CURL_VERSION_ASYNCHDNS 7.10.7 +CURL_VERSION_CONV 7.15.4 +CURL_VERSION_DEBUG 7.10.6 +CURL_VERSION_GSSNEGOTIATE 7.10.6 +CURL_VERSION_IDN 7.12.0 +CURL_VERSION_IPV6 7.10 +CURL_VERSION_KERBEROS4 7.10 +CURL_VERSION_LARGEFILE 7.11.1 +CURL_VERSION_LIBZ 7.10 +CURL_VERSION_NTLM 7.10.6 +CURL_VERSION_SPNEGO 7.10.8 +CURL_VERSION_SSL 7.10 +CURL_VERSION_SSPI 7.13.2 -- cgit v1.2.1 From d3d7ed1766c2a2439077ca4cbe047a29b45c5e0c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Feb 2009 12:39:26 +0000 Subject: include the symbols-in-versions file in the release archive --- docs/libcurl/Makefile.am | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 9e562c21e..c2b5f92c5 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -60,8 +60,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) -EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI - +EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI \ + symbols-in-versions MAN2HTML= roffit --mandir=. < $< >$@ SUFFIXES = .3 .html -- cgit v1.2.1 From 517b8ed0576008cbd116cda045c0061acad9a356 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Feb 2009 12:52:09 +0000 Subject: completed the CURLPROXY_ collection --- docs/libcurl/symbols-in-versions | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 9c712a112..8ddaa2259 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -258,8 +258,11 @@ CURLOPT_WRITEDATA 7.9.7 CURLOPT_WRITEFUNCTION 7.1 CURLOPT_WRITEHEADER 7.1 CURLPROXY_HTTP 7.10 +CURLPROXY_HTTP_1_0 7.19.4 CURLPROXY_SOCKS4 7.10 -CURLPROXY_SOCKS4 7.10 +CURLPROXY_SOCKS4A 7.18.0 +CURLPROXY_SOCKS5 7.10 +CURLPROXY_SOCKS5_HOSTNAME 7.18.0 CURLUSESSL_ALL 7.17.0 CURLUSESSL_CONTROL 7.17.0 CURLUSESSL_NONE 7.17.0 -- cgit v1.2.1 From 002cf105c6779ecf66acb36ba86aa415b8b98b09 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 11 Feb 2009 21:47:14 +0000 Subject: - CURLINFO_CONDITION_UNMET was added to allow an application to get to know if the condition in the previous request was unmet. This is typically a time condition set with CURLOPT_TIMECONDITION and was previously not possible to reliably figure out. From bug report #2565128 (http://curl.haxx.se/bug/view.cgi?id=2565128) --- docs/libcurl/curl_easy_getinfo.3 | 10 ++++++++-- docs/libcurl/curl_easy_setopt.3 | 6 ++++-- docs/libcurl/symbols-in-versions | 1 + 3 files changed, 13 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index d7ece13ea..6c999cb7d 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_getinfo 3 "16 Oct 2008" "libcurl 7.19.1" "libcurl Manual" +.TH curl_easy_getinfo 3 "11 Feb 2009" "libcurl 7.19.4" "libcurl Manual" .SH NAME curl_easy_getinfo - extract information from a curl handle .SH SYNOPSIS @@ -200,6 +200,12 @@ provided in a series of data in the format "name:content" where the content is for the specific named data. See also the certinfo.c example. NOTE: this option is only available in libcurl built with OpenSSL support. (Added in 7.19.1) +.IP CURLINFO_CONDITION_UNMET +Pass a pointer to a long to receive the number 1 if the condition provided in +the previous request didn't match (see \fICURLOPT_TIMECONDITION\fP). Alas, if +this returns a 1 you know that the reason you didn't get data in return is +because it didn't fulfill the condition. The long ths argument points to will +get a zero stored if the condition instead was met. (Added in 7.19.4) .SH TIMES .NF An overview of the six time values available from curl_easy_getinfo() diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index fc61f2804..e5e35d3d0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1326,8 +1326,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 not have -been met. +this feature will have no effect even if the given time condition would not +have been met. \fIcurl_easy_getinfo(3)\fP with the +\fICURLINFO_CONDITION_UNMET\fP option can be used after a transfer to learn if +a zero-byte successful "transfer" was due to this condition not matching. .IP CURLOPT_TIMEVALUE 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 diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 8ddaa2259..ccf996d3f 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -33,6 +33,7 @@ CURLFTPSSL_CCC_NONE 7.16.1 CURLFTPSSL_CCC_PASSIVE 7.16.1 CURLINFO_APPCONNECT_TIME 7.19.0 CURLINFO_CERTINFO 7.19.1 +CURLINFO_CONDITION_UNMET 7.19.4 CURLINFO_CONNECT_TIME 7.4.1 CURLINFO_CONTENT_LENGTH_DOWNLOAD 7.6.1 CURLINFO_CONTENT_LENGTH_UPLOAD 7.6.1 -- cgit v1.2.1 From 8f81fd6be5d3a480eca3f7ebbded5113f66c64be Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 17 Feb 2009 09:07:25 +0000 Subject: - CURLOPT_FTP_CREATE_MISSING_DIRS can now be set to 2 in addition to 1 for plain FTP connections, and it will then allow MKD to fail once and retry the CWD afterwards. This is especially useful if you're doing many simultanoes connections against the same server and they all have this option enabled, as then CWD may first fail but then another connection does MKD before this connection and thus MKD fails but trying CWD works! The numbers can (should?) now be set with the convenience enums now called CURLFTP_CREATE_DIR and CURLFTP_CREATE_DIR_RETRY. Tests has proven that if you're making an application that uploads a set of files to an ftp server, you will get a noticable gain in speed if you're using multiple connections and this option will be then be very useful. --- docs/libcurl/curl_easy_setopt.3 | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e5e35d3d0..59a277d0d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1103,6 +1103,17 @@ This setting also applies to SFTP-connections. curl will attempt to create the remote directory if it can't obtain a handle to the target-location. The creation will fail if a file of the same name as the directory to create already exists or lack of permissions prevents creation. (Added in 7.16.3) + +Starting with 7.19.4, you can also set this value to 2, which will make +libcurl retry the CWD command again if the subsequent MKD command fails. This +is especially useful if you're doing many simultanoes connections against the +same server and they all have this option enabled, as then CWD may first fail +but then another connection does MKD before this connection and thus MKD fails +but trying CWD works! 7.19.4 also introduced the \fICURLFTP_CREATE_DIR\fP and +\fICURLFTP_CREATE_DIR_RETRY\fP enum names for these arguments. + +Before version 7.19.4, libcurl will simply ignore arguments set to 2 and act +as if 1 was selected. .IP CURLOPT_FTP_RESPONSE_TIMEOUT Pass a long. Causes curl to set a timeout period (in seconds) on the amount of time that the server is allowed to take in order to generate a response -- cgit v1.2.1 From 0517fa153cf549ddbf04c67952fbdb9b34a5cb4f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 17 Feb 2009 09:43:27 +0000 Subject: three new CURLFTP_CREATE_DIR* symbols --- docs/libcurl/symbols-in-versions | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index ccf996d3f..7184ecc6a 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -31,6 +31,9 @@ CURLFTPMETHOD_SINGLECWD 7.15.1 CURLFTPSSL_CCC_ACTIVE 7.16.1 CURLFTPSSL_CCC_NONE 7.16.1 CURLFTPSSL_CCC_PASSIVE 7.16.1 +CURLFTP_CREATE_DIR 7.19.4 +CURLFTP_CREATE_DIR_NONE 7.19.4 +CURLFTP_CREATE_DIR_RETRY 7.19.4 CURLINFO_APPCONNECT_TIME 7.19.0 CURLINFO_CERTINFO 7.19.1 CURLINFO_CONDITION_UNMET 7.19.4 -- cgit v1.2.1 From 07dc741e18626f77862a3aa90fcd9e4a04d6f2b6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Feb 2009 10:40:36 +0000 Subject: mention default port number --- docs/libcurl/curl_easy_setopt.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 59a277d0d..9c4c6afa0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -445,7 +445,8 @@ Set HTTP proxy to use. The parameter should be a char * to a zero terminated string holding the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]:// since any such prefix will be ignored. The -proxy's port number may optionally be specified with the separate option +proxy's port number may optionally be specified with the separate option. If +not specified, libcurl will default to using port 1080 for proxies. \fICURLOPT_PROXYPORT\fP. When you tell the library to use an HTTP proxy, libcurl will transparently -- cgit v1.2.1 From 6c9f37d263593bd72759cc2c0d275a3a9cd47b19 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Feb 2009 18:45:00 +0000 Subject: - After a bug reported by James Cheng I've made curl_easy_getinfo() for CURLINFO_CONTENT_LENGTH_DOWNLOAD and CURLINFO_CONTENT_LENGTH_UPLOAD return -1 if the sizes aren't know. Previously these returned 0, make it impossible to detect the difference between actually zero and unknown. --- docs/libcurl/curl_easy_getinfo.3 | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 6c999cb7d..63aea1b84 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -134,9 +134,11 @@ on the list pointer once you're done with it, as libcurl will not free the data for you. (Added in 7.12.3) .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD Pass a pointer to a double to receive the content-length of the download. This -is the value read from the Content-Length: field. +is the value read from the Content-Length: field. Since 7.19.4, this returns -1 +if the size isn't known. .IP CURLINFO_CONTENT_LENGTH_UPLOAD -Pass a pointer to a double to receive the specified size of the upload. +Pass a pointer to a double to receive the specified size of the upload. Since +7.19.4, this returns -1 if the size isn't known. .IP CURLINFO_CONTENT_TYPE Pass a pointer to a 'char *' to receive the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get NULL, -- cgit v1.2.1 From 042cc1f69ec0878f542667cb684378869f859911 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 Mar 2009 23:05:31 +0000 Subject: - David Kierznowski notified us about a security flaw (http://curl.haxx.se/docs/adv_20090303.html also known as CVE-2009-0037) in which previous libcurl versions (by design) can be tricked to access an arbitrary local/different file instead of a remote one when CURLOPT_FOLLOWLOCATION is enabled. This flaw is now fixed in this release together this the addition of two new setopt options for controlling this new behavior: o CURLOPT_REDIR_PROTOCOLS controls what protocols libcurl is allowed to follow to when CURLOPT_FOLLOWLOCATION is enabled. By default, this option excludes the FILE and SCP protocols and thus you nee to explicitly allow them in your app if you really want that behavior. o CURLOPT_PROTOCOLS controls what protocol(s) libcurl is allowed to fetch using the primary URL option. This is useful if you want to allow a user or other outsiders control what URL to pass to libcurl and yet not allow all protocols libcurl may have been built to support. --- docs/libcurl/curl_easy_setopt.3 | 24 ++++++++++++++++++++++++ docs/libcurl/symbols-in-versions | 15 +++++++++++++++ 2 files changed, 39 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9c4c6afa0..dd3473b99 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -440,6 +440,26 @@ The string given to CURLOPT_URL must be url-encoded and follow RFC 2396 \fICURLOPT_URL\fP is the only option that \fBmust\fP be set before \fIcurl_easy_perform(3)\fP is called. + +\fICURLOPT_PROTOCOLS\fP can be used to limit what protocols libcurl will use +for this transfer, independent of what libcurl has been compiled to +support. That may be useful if you accept the URL from an external source and +want to limit the accessibility. +.IP CURLOPT_PROTOCOLS +Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask +limits what protocols libcurl may use in the transfer. This allows you to have +a libcurl built to support a wide range of protocols but still limit specific +transfers to only be allowed to use a subset of them. By default libcurl will +accept all protocols it supports. See also +\fICURLOPT_REDIR_PROTOCOLS\fP. (Added in 7.19.4) +.IP CURLOPT_REDIR_PROTOCOLS +Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask +limits what protocols libcurl may use in a transfer that it follows to in a +redirect when \fICURLOPT_FOLLOWLOCATION\fP is enabled. This allows you to +limit specific transfers to only be allowed to use a subset of protocols in +redirections. By default libcurl will allow all protocols except for FILE and +SCP. This is a difference compared to pre-7.19.4 versions which +unconditionally would follow to all protocols supported. (Added in 7.19.4) .IP CURLOPT_PROXY Set HTTP proxy to use. The parameter should be a char * to a zero terminated string holding the host name or dotted IP address. To specify port number in @@ -743,6 +763,10 @@ This means that the library will re-send the same request on the new location and follow new Location: headers all the way until no more such headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects libcurl will follow. + +NOTE: since 7.19.4, libcurl can limit to what protocols it will automatically +follow. The accepted protocols are set with \fICURLOPT_REDIR_PROTOCOLS\fP and +it excludes the FILE protocol by default. .IP CURLOPT_UNRESTRICTED_AUTH A parameter set to 1 tells the library it can continue to send authentication (user+password) when following locations, even when hostname changed. This diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 7184ecc6a..e429f2e98 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -191,6 +191,7 @@ CURLOPT_PRIVATE 7.10.3 CURLOPT_PROGRESSDATA 7.1 CURLOPT_PROGRESSFUNCTION 7.1 CURLOPT_PROGRESSMODE 7.1 - 7.9.2 +CURLOPT_PROTOCOLS 7.19.4 CURLOPT_PROXY 7.1 CURLOPT_PROXYAUTH 7.10.7 CURLOPT_PROXYPASSWORD 7.19.1 @@ -205,6 +206,7 @@ CURLOPT_RANDOM_FILE 7.7 CURLOPT_RANGE 7.1 CURLOPT_READDATA 7.9.7 CURLOPT_READFUNCTION 7.1 +CURLOPT_REDIR_PROTOCOLS 7.19.4 CURLOPT_REFERER 7.1 CURLOPT_RESUME_FROM 7.1 CURLOPT_RESUME_FROM_LARGE 7.11.0 @@ -261,6 +263,19 @@ CURLOPT_VERBOSE 7.1 CURLOPT_WRITEDATA 7.9.7 CURLOPT_WRITEFUNCTION 7.1 CURLOPT_WRITEHEADER 7.1 +CURLPROTO_ALL 7.19.4 +CURLPROTO_DICT 7.19.4 +CURLPROTO_FILE 7.19.4 +CURLPROTO_FTP 7.19.4 +CURLPROTO_FTPS 7.19.4 +CURLPROTO_HTTP 7.19.4 +CURLPROTO_HTTPS 7.19.4 +CURLPROTO_LDAP 7.19.4 +CURLPROTO_LDAPS 7.19.4 +CURLPROTO_SCP 7.19.4 +CURLPROTO_SFTP 7.19.4 +CURLPROTO_TELNET 7.19.4 +CURLPROTO_TFTP 7.19.4 CURLPROXY_HTTP 7.10 CURLPROXY_HTTP_1_0 7.19.4 CURLPROXY_SOCKS4 7.10 -- cgit v1.2.1 From 983a53950399a8a9b60b97b99884935aba2c4c9e Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 5 Mar 2009 06:44:18 +0000 Subject: Expanded the security section of the libcurl-tutorial man page to cover more issues for authors to consider when writing robust libcurl-using applications. --- docs/libcurl/libcurl-tutorial.3 | 181 +++++++++++++++++++++++++++++++++++----- 1 file changed, 161 insertions(+), 20 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 3c36c7357..f920b8d01 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-tutorial 3 "17 Nov 2008" "libcurl" "libcurl programming" +.TH libcurl-tutorial 3 "4 Mar 2009" "libcurl" "libcurl programming" .SH NAME libcurl-tutorial \- libcurl programming tutorial .SH "Objective" @@ -200,7 +200,7 @@ Using that property, you can easily pass local data between your application and the function that gets invoked by libcurl. libcurl itself won't touch the data you pass with \fICURLOPT_WRITEDATA\fP. -libcurl offers its own default internal callback that'll take care of the data +libcurl offers its own default internal callback that will take care of the data if you don't set the callback with \fICURLOPT_WRITEFUNCTION\fP. It will then simply output the received data to stdout. You can have the default callback write the data to a different file handle by passing a 'FILE *' to a file @@ -738,24 +738,24 @@ stand in the way for such innovative actions either! .IP "Proxy Auto-Config" Netscape first came up with this. It is basically a web page (usually using a -\&.pac extension) with a javascript that when executed by the browser with the +\&.pac extension) with a Javascript that when executed by the browser with the requested URL as input, returns information to the browser on how to connect to the URL. The returned information might be "DIRECT" (which means no proxy should be used), "PROXY host:port" (to tell the browser where the proxy for this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS proxy). -libcurl has no means to interpret or evaluate javascript and thus it doesn't +libcurl has no means to interpret or evaluate Javascript and thus it doesn't support this. If you get yourself in a position where you face this nasty invention, the following advice have been mentioned and used in the past: -- Depending on the javascript complexity, write up a script that translates it +- Depending on the Javascript complexity, write up a script that translates it to another language and execute that. -- Read the javascript code and rewrite the same logic in another language. +- Read the Javascript code and rewrite the same logic in another language. -- Implement a javascript interpreted, people have successfully used the -Mozilla javascript engine in the past. +- Implement a Javascript interpreted, people have successfully used the +Mozilla Javascript engine in the past. - Ask your admins to stop this, for a static proxy setup or similar. @@ -836,7 +836,7 @@ If just changing the actual HTTP request keyword is what you want, like when GET, HEAD or POST is not good enough for you, CURLOPT_CUSTOMREQUEST is there for you. It is very simple to use: - curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNRUQUEST"); + curl_easy_setopt(easyhandle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); When using the custom request, you change the request keyword of the actual request you are performing. Thus, by default you make a GET request but you can @@ -908,7 +908,7 @@ 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 require data interchange and thus need -a data-connection must be left to libcurl's own judgment. Also be aware +a data-connection must be left to libcurl's own judgement. 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 or similar) you might confuse libcurl and then it might not attempt to @@ -1062,20 +1062,32 @@ actually true headers, but in this case we pretend they are! ;-) .SH "Security Considerations" -libcurl is in itself not insecure. If used the right way, you can use libcurl -to transfer data pretty safely. - -There are of course many things to consider that may loosen up this -situation: +The libcurl project takes security seriously. The library is written with +caution and precautions are taken to mitigate many kinds of risks encountered +while operating with potentially malicious servers on the Internet. It is a +powerful library, however, which allows application writers to make trade offs +between ease of writing and exposure to potential risky operations. If +used the right way, you can use libcurl to transfer data pretty safely. + +Many applications are used in closed networks where users and servers +can be trusted, but many others are used on arbitrary servers and are fed +input from potentially untrusted users. Following is a discussion about +some risks in the ways in which applications commonly use libcurl and +potential mitigations of those risks. It is by no means comprehensive, but +shows classes of attacks that robust applications should consider. The +Common Weakness Enumeration project at http://cwe.mitre.org/ is a good +reference for many of these and similar types of weaknesses of which +application writers should be aware. .IP "Command Lines" If you use a command line tool (such as curl) that uses libcurl, and you give -option to the tool on the command line those options can very likely get read +options to the tool on the command line those options can very likely get read by other users of your system when they use 'ps' or other tools to list currently running processes. To avoid this problem, never feed sensitive things to programs using command -line options. +line options. Write them to a protected file and use the \-K option to +avoid this. .IP ".netrc" \&.netrc is a pretty handy file/feature that allows you to login quickly and @@ -1091,14 +1103,143 @@ plain text anywhere. .IP "Clear Text Passwords" Many of the protocols libcurl supports send name and password unencrypted as clear text (HTTP Basic authentication, FTP, TELNET etc). It is very easy for -anyone on your network or a network nearby yours, to just fire up a network +anyone on your network or a network nearby yours to just fire up a network analyzer tool and eavesdrop on your passwords. Don't let the fact that HTTP Basic uses base64 encoded passwords fool you. They may not look readable at a first glance, but they very easily "deciphered" by anyone within seconds. -To avoid this problem, use HTTP athentication methods or other protocols that +To avoid this problem, use HTTP authentication methods or other protocols that don't let snoopers see your password: HTTP with Digest, NTLM or GSS -authentication, HTTPS, FTPS, SCP, SFTP and FTP-kerberos are a few examples. +authentication, HTTPS, FTPS, SCP, SFTP and FTP-Kerberos are a few examples. + +.IP "Redirects" +The CURLOPT_FOLLOWLOCATION option automatically follows HTTP redirects sent +by a remote server. These redirects can refer to any kind of URL, not just +HTTP. A redirect to a file: URL would cause the libcurl to read (or write) +arbitrary files from the local filesystem. If the application returns +the data back to the user (as would happen in some kinds of CGI scripts), +an attacker could leverage this to read otherwise forbidden data (e.g. +file://localhost/etc/passwd). + +If authentication credentials are stored in the ~/.netrc file, or Kerberos +is in use, any other URL type (not just file:) that requires +authentication is also at risk. A redirect such as +ftp://some-internal-server/private-file would then return data even when +the server is password protected. + +In the same way, if an unencrypted SSH private key has been configured for +the user running the libcurl application, SCP: or SFTP: URLs could access +password or private-key protected resources, +e.g. sftp://user@some-internal-server/etc/passwd + +The CURLOPT_REDIR_PROTOCOLS and CURLOPT_NETRC options can be used to +mitigate against this kind of attack. + +A redirect can also specify a location available only on the machine running +libcurl, including servers hidden behind a firewall from the attacker. +e.g. http://127.0.0.1/ or http://intranet/delete-stuff.cgi?delete=all or +tftp://bootp-server/pc-config-data + +Apps can mitigate against this by disabling CURLOPT_FOLLOWLOCATION and +handling redirects itself, sanitizing URLs as necessary. Alternately, an +app could leave CURLOPT_FOLLOWLOCATION enabled but set CURLOPT_REDIR_PROTOCOLS +and install a CURLOPT_OPENSOCKETFUNCTION callback function in which addresses +are sanitized before use. + +.IP "Private Resources" +A user who can control the DNS server of a domain being passed in within +a URL can change the address of the host to a local, private address +which the libcurl application will then use. e.g. The innocuous URL +http://fuzzybunnies.example.com/ could actually resolve to the IP address +of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3 +Apps can mitigate against this by setting a CURLOPT_OPENSOCKETFUNCTION +and checking the address before a connection. + +All the malicious scenarios regarding redirected URLs apply just as well +to non-redirected URLs, if the user is allowed to specify an arbitrary URL +that could point to a private resource. For example, a web app providing +a translation service might happily translate file://localhost/etc/passwd +and display the result. Apps can mitigate against this with the +CURLOPT_PROTOCOLS option as well as by similar mitigation techniques for +redirections. + +A malicious FTP server could in response to the PASV command return an +IP address and port number for a server local to the app running libcurl +but behind a firewall. Apps can mitigate against this by using the +CURLOPT_FTP_SKIP_PASV_IP option or CURLOPT_FTPPORT. + +.IP Uploads +When uploading, a redirect can cause a local (or remote) file to be +overwritten. Apps must not allow any unsanitized URL to be passed in +for uploads. Also, CURLOPT_FOLLOWLOCATION should not be used on uploads. +Instead, the app should handle redirects itself, sanitizing each URL first. + +.IP Authentication +Use of CURLOPT_UNRESTRICTED_AUTH could cause authentication information to +be sent to an unknown second server. Apps can mitigate against this +by disabling CURLOPT_FOLLOWLOCATION and handling redirects itself, +sanitizing where necessary. + +Use of the CURLAUTH_ANY option to CURLOPT_HTTPAUTH could result in user +name and password being sent in clear text to an HTTP server. Instead, +use CURLAUTH_ANYSAFE which ensures that the password is encrypted over +the network, or else fail the request. + +Use of the CURLUSESSL_TRY option to CURLOPT_USE_SSL could result in user +name and password being sent in clear text to an FTP server. Instead, +use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or +else fail the request. + +.IP Cookies +If cookies are enabled and cached, then a user could craft a URL which +performs some malicious action to a site whose authentication is already +stored in a cookie. e.g. http://mail.example.com/delete-stuff.cgi?delete=all +Apps can mitigate against this by disabling cookies or clearing them +between requests. + +.IP "Dangerous URLs" +SCP URLs can contain raw commands within the scp: URL, which is a side effect +of how the SCP protocol is designed. e.g. +scp://user:pass@host/a;date >/tmp/test; +Apps must not allow unsanitized SCP: URLs to be passed in for downloads. + +.IP "Denial of Service" +A malicious server could cause libcurl to effectively hang by sending +a trickle of data through, or even no data at all but just keeping the TCP +connection open. This could result in a denial-of-service attack. The +CURLOPT_TIMEOUT and/or CURLOPT_LOW_SPEED_LIMIT options can be used to +mitigate against this. + +A malicious server could cause libcurl to effectively hang by starting to +send data, then severing the connection without cleanly closing the +TCP connection. The app could install a CURLOPT_SOCKOPTFUNCTION callback +function and set the TCP SO_KEEPALIVE option to mitigate against this. +Setting one of the timeout options would also work against this attack. + +A malicious server could cause libcurl to download an infinite amount of +data, potentially causing all of memory or disk to be filled. Setting +the CURLOPT_MAXFILESIZE_LARGE option is not sufficient to guard against this. +Instead, the app should monitor the amount of data received within the +write or progress callback and abort once the limit is reached. + +A malicious HTTP server could cause an infinite redirection loop, causing a +denial-of-service. This can be mitigated by using the CURLOPT_MAXREDIRS +option. + +.IP "Arbitrary Headers" +User-supplied data must be sanitized when used in options like +CURLOPT_USERAGENT, CURLOPT_HTTPHEADER, CURLOPT_POSTFIELDS and others that +are used to generate structured data. Characters like embedded carriage +returns or ampersands could allow the user to create additional headers or +fields that could cause malicious transactions. + +.IP "Server Certificates" +A secure application should never use the CURLOPT_SSL_VERIFYPEER option to +disable certificate validation. There are numerous attacks that are enabled +by apps that fail to properly validate server TLS/SSL certificates, +thus enabling a malicious server to spoof a legitimate one. HTTPS without +validated certificates is potentially as insecure as a plain HTTP connection. + .IP "Showing What You Do" 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 -- cgit v1.2.1 From 9a0c9cd6e1c6124be255cc1cd6e722c94721f282 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 18 Mar 2009 09:14:28 +0000 Subject: minor fix --- docs/libcurl/libcurl-tutorial.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index f920b8d01..6d366219e 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -381,7 +381,7 @@ them URL encoded, as %XX where XX is a two-digit hexadecimal number. libcurl also provides options to set various passwords. The user name and password as shown embedded in the URL can instead get set with the CURLOPT_USERPWD option. The argument passed to libcurl should be a char * to -a string in the format "user:password:". In a manner like this: +a string in the format "user:password". In a manner like this: curl_easy_setopt(easyhandle, CURLOPT_USERPWD, "myname:thesecret"); -- cgit v1.2.1 From 31a7bfc47f2258f4825a7038d2f4e9f445a71cdf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 20 Mar 2009 23:28:20 +0000 Subject: Gary Maxwell helped us clarify that CURLOPT_SHARE specificly needs the locking functions if the easy handles are used in multiple threads --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index dd3473b99..9599b65e6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1726,8 +1726,9 @@ Pass a share handle as a parameter. The share handle must have been created by a previous call to \fIcurl_share_init(3)\fP. Setting this option, will make this curl handle use the data from the shared handle instead of keeping the data to itself. This enables several curl handles to share data. If the curl -handles are used simultaneously, you \fBMUST\fP use the locking methods in the -share handle. See \fIcurl_share_setopt(3)\fP for details. +handles are used simultaneously in multiple threads, you \fBMUST\fP use the +locking methods in the 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 -- cgit v1.2.1 From 875c55d86bcfb35f01106865b60dcd1594bfc340 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 6 Apr 2009 21:44:53 +0000 Subject: - I clarified in the docs that CURLOPT_SEEKFUNCTION should return 0 on success and 1 on fatal errors. Previously it only mentioned non-zero on fatal errors. This is a slight change in meaning, but it follows what we've done elsewhere before and it opens up for LOTS of more useful return codes whenever we can think of them... --- docs/libcurl/curl_easy_setopt.3 | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9599b65e6..9de7ab651 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -208,9 +208,10 @@ currently only one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the primary connection (meaning the control connection in the FTP case). Future versions of libcurl may support more purposes. It passes the newly created socket descriptor so additional setsockopt() calls can be done at the user's -discretion. A non-zero return code from the callback function will signal an -unrecoverable error to the library and it will close the socket and return -\fICURLE_COULDNT_CONNECT\fP. (Option added in 7.15.6.) +discretion. Return 0 (zero) from the callback on success. Return 1 from the +callback function to signal an unrecoverable error to the library and it will +close the socket and return \fICURLE_COULDNT_CONNECT\fP. (Option added in +7.15.6.) .IP CURLOPT_SOCKOPTDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. -- cgit v1.2.1 From 28cc9dd3319ac5a8867939cb2bd631a73896efec Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 7 Apr 2009 20:51:01 +0000 Subject: clarified after chat in #curl --- docs/libcurl/curl_multi_remove_handle.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 index f905b54e8..45a77ffc9 100644 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -15,8 +15,9 @@ specified easy handle be removed from this multi handle's control. When the easy handle has been removed from a multi stack, it is again perfectly legal to invoke \fIcurl_easy_perform()\fP on this easy handle. -Removing a handle while being used, will effectively halt all transfers in -progress. +Removing an easy handle while being used, will effectively halt the transfer +in progress involving that easy handle. All other easy handles and transfers +will remain unaffected. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. .SH "SEE ALSO" -- cgit v1.2.1 From 7356ff0b184a1a6e500e664af67ffd6828126bb6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 17 Apr 2009 12:55:09 +0000 Subject: As Jeff Pohlmeyer suggested: "pointer to 'char *'" is now instead put: "pointer to a char pointer". --- docs/libcurl/curl_easy_getinfo.3 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 63aea1b84..afb087084 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -43,7 +43,7 @@ explicitly mentioned below. .SH AVAILABLE INFORMATION The following information can be extracted: .IP CURLINFO_EFFECTIVE_URL -Pass a pointer to a 'char *' to receive the last used effective URL. +Pass a pointer to a char pointer to receive the last used effective URL. .IP CURLINFO_RESPONSE_CODE Pass a pointer to a long to receive the last received HTTP or FTP code. This option was known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. This @@ -140,15 +140,15 @@ if the size isn't known. Pass a pointer to a double to receive the specified size of the upload. Since 7.19.4, this returns -1 if the size isn't known. .IP CURLINFO_CONTENT_TYPE -Pass a pointer to a 'char *' to receive the content-type of the downloaded +Pass a pointer to a char pointer to receive the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get NULL, it means that the server didn't send a valid Content-Type header or that the protocol used doesn't support this. .IP CURLINFO_PRIVATE -Pass a pointer to a 'char *' to receive the pointer to the private data +Pass a pointer to a char pointer to receive the pointer to the private data associated with the curl handle (set with the CURLOPT_PRIVATE option to \fIcurl_easy_setopt(3)\fP). Please note that for internal reasons, the -value is returned as a 'char *', although effectively being a 'void *'. +value is returned as a char pointer, although effectively being a 'void *'. (Added in 7.10.3) .IP CURLINFO_HTTPAUTH_AVAIL Pass a pointer to a long to receive a bitmask indicating the authentication @@ -188,10 +188,10 @@ libcurl close the socket and cleanup other resources associated with the handle. This is typically used in combination with \fICURLOPT_CONNECT_ONLY\fP. (Added in 7.15.2) .IP CURLINFO_FTP_ENTRY_PATH -Pass a pointer to a 'char *' to receive a pointer to a string holding the path -of the entry path. That is the initial path libcurl ended up in when logging -on to the remote FTP server. This stores a NULL as pointer if something is -wrong. (Added in 7.15.4) +Pass a pointer to a char pointer to receive a pointer to a string holding the +path of the entry path. That is the initial path libcurl ended up in when +logging on to the remote FTP server. This stores a NULL as pointer if +something is wrong. (Added in 7.15.4) .IP CURLINFO_CERTINFO Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to struct that holds a number of linked lists with info about the certificate -- cgit v1.2.1 From 991b120eeebeb9a9b092272273066a27956d744e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 18 Apr 2009 22:48:28 +0000 Subject: escape the ' properly --- docs/libcurl/libcurl-tutorial.3 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 6d366219e..bb5f6628b 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -667,14 +667,14 @@ default to assume a HTTP proxy): .IP "Environment Variables" -libcurl automatically checks and uses a set of environment variables to -know what proxies to use for certain protocols. The names of the variables -are following an ancient de facto standard and are built up as -"[protocol]_proxy" (note the lower casing). Which makes the variable -'http_proxy' checked for a name of a proxy to use when the input URL is -HTTP. Following the same rule, the variable named 'ftp_proxy' is checked -for FTP URLs. Again, the proxies are always HTTP proxies, the different -names of the variables simply allows different HTTP proxies to be used. +libcurl automatically checks and uses a set of environment variables to know +what proxies to use for certain protocols. The names of the variables are +following an ancient de facto standard and are built up as "[protocol]_proxy" +(note the lower casing). Which makes the variable \&'http_proxy' checked for a +name of a proxy to use when the input URL is HTTP. Following the same rule, +the variable named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are +always HTTP proxies, the different names of the variables simply allows +different HTTP proxies to be used. The proxy environment variable contents should be in the format \&"[protocol://][user:password@]machine[:port]". Where the protocol:// part is -- cgit v1.2.1 From 0145919a9ec33446f130c3473964ab9f8b4778a6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 23 Apr 2009 21:43:01 +0000 Subject: CURLOPT_POSTQUOTE commands only run when no error --- docs/libcurl/curl_easy_setopt.3 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9de7ab651..0c93e7fa4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1078,11 +1078,11 @@ rename, rm, rmdir, symlink (see .BR curl (1)) (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 -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. +Pass a pointer to a linked list of FTP or SFTP commands to pass to the server +after your FTP transfer request. The commands will only be run if no error +occurred. 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. .IP CURLOPT_PREQUOTE Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. The linked list should be a fully valid list of -- cgit v1.2.1 From e01b7c1ede6f8b91f458259dbed96acce7bf3779 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 28 Apr 2009 11:19:10 +0000 Subject: - Bug report #2709004 (http://curl.haxx.se/bug/view.cgi?id=2709004) by Tim Chen pointed out how curl couldn't upload with resume when reading from a pipe. This ended up with the introduction of a new return code for the CURLOPT_SEEKFUNCTION callback that basically says that the seek failed but that libcurl may try to resolve the situation anyway. In our case this means libcurl will attempt to instead read that much data from the stream instead of seeking and that way curl can now upload with resume when data is read from a stream! --- docs/libcurl/curl_easy_setopt.3 | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0c93e7fa4..06e3a11b9 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -189,8 +189,11 @@ uploaded bytes with the normal read function/callback). It is also called to rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET, SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl -only passes SEEK_SET. The callback must return 0 on success as returning -something else will cause the upload operation to fail. +only passes SEEK_SET. The callback must return 0 (CURL_SEEKFUNC_OK) on +success, 1 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2 +(CURL_SEEKFUNC_CANTSEEK) to indicate that while the seek failed, libcurl is +free to work around the problem if possible. The latter can sometimes be done +by instead reading from the input or similar. If you forward the input arguments directly to "fseek" or "lseek", note that the data type for \fIoffset\fP is not the same as defined for curl_off_t on -- cgit v1.2.1 From dbf371344bd5c3cb0a4c0d903f1fb12b224cbab6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 29 Apr 2009 11:41:29 +0000 Subject: mention the new CURL_SEEKFUNC_ symbols --- docs/libcurl/symbols-in-versions | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index e429f2e98..0fc2189f0 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -295,6 +295,9 @@ CURL_IPRESOLVE_WHATEVER 7.10.8 CURL_NETRC_IGNORED 7.9.8 CURL_NETRC_OPTIONAL 7.9.8 CURL_NETRC_REQUIRED 7.9.8 +CURL_SEEKFUNC_CANTSEEK 7.19.5 +CURL_SEEKFUNC_FAIL 7.19.5 +CURL_SEEKFUNC_OK 7.19.5 CURL_SSLVERSION_DEFAULT 7.9.2 CURL_SSLVERSION_SSLv2 7.9.2 CURL_SSLVERSION_SSLv3 7.9.2 -- cgit v1.2.1 From 22e2ecb003eb942cfbf78a206b9daff370d74b17 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 30 Apr 2009 08:30:52 +0000 Subject: provide some track record of the SONAME bumps --- docs/libcurl/ABI | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI index f38c87888..6e19554a7 100644 --- a/docs/libcurl/ABI +++ b/docs/libcurl/ABI @@ -52,3 +52,18 @@ Downgrades that doesn't support the options your application needs. Or possibly you even downgrade so far so you cross an ABI break border and thus a different soname, and then your application may need to adapt to the modified ABI. + +History + + The previous major library soname number bumps (breaking backwards + compatibility) have happened the following times: + + 0 - libcurl 7.1, August 200 + + 1 - libcurl 7.5 December 2000 + + 2 - libcurl 7.7 March 2001 + + 3 - libcurl 7.12.0 June 2004 + + 4 - libcurl 7.16.0 October 2006 -- cgit v1.2.1 From 2788aa366c8a70ef55f5905e9454c3d163efdd41 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 1 May 2009 20:20:54 +0000 Subject: Jose Goncalves fixed my crappy spelling! --- docs/libcurl/ABI | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/ABI b/docs/libcurl/ABI index 6e19554a7..3ec0e04de 100644 --- a/docs/libcurl/ABI +++ b/docs/libcurl/ABI @@ -13,7 +13,7 @@ ABI - Application Binary Interface conventions, function arguments, return values, struct sizes/defines and more. - For a longer descricption, see + For a longer description, see http://en.wikipedia.org/wiki/Application_binary_interface Upgrades @@ -36,7 +36,7 @@ Soname Bumps breakage, that may require your application to get attention or possibly be changed to adhere to new things, we will bump the soname. Then the library will get a different output name and thus can in fact be installed in - parallell with an older installed lib (on most systems). Thus, old + parallel with an older installed lib (on most systems). Thus, old applications built against the previous ABI version will remain working and using the older lib, while newer applications build and use the newer one. @@ -58,7 +58,7 @@ History The previous major library soname number bumps (breaking backwards compatibility) have happened the following times: - 0 - libcurl 7.1, August 200 + 0 - libcurl 7.1, August 2000 1 - libcurl 7.5 December 2000 -- cgit v1.2.1 From bd4fd9c28c2a12650f20d3a1d707b22adea64ffd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 May 2009 13:01:27 +0000 Subject: Philippe Vaucher reported this typo --- docs/libcurl/libcurl-tutorial.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index bb5f6628b..7bbdc8a4a 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -557,7 +557,7 @@ post handle: curl_easy_perform(easyhandle); /* post away! */ curl_formfree(post); /* free post */ - curl_slist_free_all(post); /* free custom header list */ + curl_slist_free_all(headers); /* free custom header list */ .fi Since all options on an easyhandle are "sticky", they remain the same until -- cgit v1.2.1 From bdf71e26857c0a44b1d883ff48d0d0717797f869 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 May 2009 14:50:29 +0000 Subject: a busload symbols added --- docs/libcurl/symbols-in-versions | 123 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 120 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 0fc2189f0..0ea7deb35 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -19,6 +19,91 @@ CURLAUTH_DIGEST 7.10.6 CURLAUTH_DIGEST_IE 7.19.3 CURLAUTH_GSSNEGOTIATE 7.10.6 CURLAUTH_NTLM 7.10.6 +CURLCLOSEPOLICY_CALLBACK 7.7 +CURLCLOSEPOLICY_LEAST_RECENTLY_USED 7.7 +CURLCLOSEPOLICY_LEAST_TRAFFIC 7.7 +CURLCLOSEPOLICY_OLDEST 7.7 +CURLCLOSEPOLICY_SLOWEST 7.7 +CURLE_ABORTED_BY_CALLBACK 7.1 +CURLE_BAD_CALLING_ORDER 7.1 7.17.0 +CURLE_BAD_CONTENT_ENCODING 7.10 +CURLE_BAD_FUNCTION_ARGUMENT 7.1 +CURLE_BAD_PASSWORD_ENTERED - 7.17.0 +CURLE_COULDNT_CONNECT 7.1 +CURLE_COULDNT_RESOLVE_HOST 7.1 +CURLE_COULDNT_RESOLVE_PROXY 7.1 +CURLE_FAILED_INIT 7.1 +CURLE_FILESIZE_EXCEEDED 7.10.8 +CURLE_FILE_COULDNT_READ_FILE 7.1 +CURLE_FTP_ACCESS_DENIED 7.1 +CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 +CURLE_FTP_CANT_GET_HOST 7.1 +CURLE_FTP_CANT_RECONNECT 7.1 7.17.0 +CURLE_FTP_COULDNT_GET_SIZE 7.1 7.17.0 +CURLE_FTP_COULDNT_RETR_FILE 7.1 +CURLE_FTP_COULDNT_SET_ASCII 7.1 7.17.0 +CURLE_FTP_COULDNT_SET_BINARY 7.1 7.17.0 +CURLE_FTP_COULDNT_SET_TYPE 7.17.0 +CURLE_FTP_COULDNT_STOR_FILE 7.1 +CURLE_FTP_COULDNT_USE_REST 7.1 +CURLE_FTP_PORT_FAILED 7.1 +CURLE_FTP_QUOTE_ERROR 7.1 7.17.0 +CURLE_FTP_SSL_FAILED - 7.17.0 +CURLE_FTP_USER_PASSWORD_INCORRECT 7.1 7.17.0 +CURLE_FTP_WEIRD_227_FORMAT 7.1 +CURLE_FTP_WEIRD_PASS_REPLY 7.1 +CURLE_FTP_WEIRD_PASV_REPLY 7.1 +CURLE_FTP_WEIRD_SERVER_REPLY 7.1 +CURLE_FTP_WEIRD_USER_REPLY 7.1 7.17.0 +CURLE_FTP_WRITE_ERROR 7.1 7.17.0 +CURLE_FUNCTION_NOT_FOUND 7.1 +CURLE_GOT_NOTHING 7.9.1 +CURLE_HTTP_NOT_FOUND 7.1 +CURLE_HTTP_PORT_FAILED - 7.12.0 +CURLE_HTTP_POST_ERROR 7.1 +CURLE_HTTP_RANGE_ERROR 7.1 7.17.0 +CURLE_INTERFACE_FAILED 7.12.0 +CURLE_LDAP_CANNOT_BIND 7.1 +CURLE_LDAP_INVALID_URL 7.10.8 +CURLE_LDAP_SEARCH_FAILED 7.1 +CURLE_LIBRARY_NOT_FOUND 7.1 7.17.0 +CURLE_MALFORMAT_USER 7.1 7.17.0 +CURLE_OK 7.1 +CURLE_OPERATION_TIMEDOUT 7.17.0 +CURLE_OPERATION_TIMEOUTED 7.1 7.17.0 +CURLE_OUT_OF_MEMORY 7.1 +CURLE_PARTIAL_FILE 7.1 +CURLE_PEER_FAILED_VERIFICATION - 7.17.1 +CURLE_QUOTE_ERROR 7.17.0 +CURLE_RANGE_ERROR 7.17.0 +CURLE_READ_ERROR 7.1 +CURLE_RECV_ERROR 7.13.0 +CURLE_REMOTE_ACCESS_DENIED 7.17.0 +CURLE_REMOTE_DISK_FULL 7.17.0 +CURLE_SEND_ERROR 7.13.0 +CURLE_SHARE_IN_USE - 7.17.0 +CURLE_SSH 7.16.1 +CURLE_SSL_CACERT 7.10 +CURLE_SSL_CERTPROBLEM 7.10 +CURLE_SSL_CIPHER 7.10 +CURLE_SSL_CONNECT_ERROR 7.1 +CURLE_SSL_ENGINE_INITFAILED 7.13.0 +CURLE_SSL_ENGINE_NOTFOUND 7.9.3 +CURLE_SSL_ENGINE_SETFAILED 7.9.3 +CURLE_SSL_PEER_CERTIFICATE 7.17.1 +CURLE_TELNET_OPTION_SYNTAX 7.7 +CURLE_TFTP_DISKFULL 7.15.0 7.17.0 +CURLE_TFTP_EXISTS 7.15.0 7.17.0 +CURLE_TFTP_ILLEGAL 7.15.0 +CURLE_TFTP_NOSUCHUSER 7.15.0 +CURLE_TFTP_UNKNOWNID 7.15.0 +CURLE_TOO_MANY_REDIRECTS 7.5 +CURLE_UNKNOWN_TELNET_OPTION 7.7 +CURLE_UNSUPPORTED_PROTOCOL 7.1 +CURLE_URL_MALFORMAT 7.1 +CURLE_URL_MALFORMAT_USER 7.1 7.17.0 +CURLE_USE_SSL_FAILED 7.17.0 +CURLE_WRITE_ERROR 7.1 CURLFTPAUTH_DEFAULT 7.12.2 CURLFTPAUTH_DEFAULT 7.12.2 CURLFTPAUTH_SSL 7.12.2 @@ -28,9 +113,13 @@ CURLFTPAUTH_TLS 7.12.2 CURLFTPMETHOD_MULTICWD 7.15.1 CURLFTPMETHOD_NOCWD 7.15.1 CURLFTPMETHOD_SINGLECWD 7.15.1 +CURLFTPSSL_ALL - 7.17.0 CURLFTPSSL_CCC_ACTIVE 7.16.1 CURLFTPSSL_CCC_NONE 7.16.1 CURLFTPSSL_CCC_PASSIVE 7.16.1 +CURLFTPSSL_CONTROL 7.11.0 7.17.0 +CURLFTPSSL_NONE 7.11.0 7.17.0 +CURLFTPSSL_TRY 7.11.0 7.17.0 CURLFTP_CREATE_DIR 7.19.4 CURLFTP_CREATE_DIR_NONE 7.19.4 CURLFTP_CREATE_DIR_RETRY 7.19.4 @@ -44,6 +133,7 @@ CURLINFO_CONTENT_TYPE 7.9.4 CURLINFO_COOKIELIST 7.14.1 CURLINFO_DATA_IN 7.9.6 CURLINFO_DATA_OUT 7.9.6 +CURLINFO_EFFECTIVE_URL 7.3 CURLINFO_FILETIME 7.5 CURLINFO_FTP_ENTRY_PATH 7.15.4 CURLINFO_HEADER_IN 7.9.6 @@ -75,6 +165,14 @@ CURLINFO_SSL_VERIFYRESULT 7.5 CURLINFO_STARTTRANSFER_TIME 7.9.2 CURLINFO_TEXT 7.9.6 CURLINFO_TOTAL_TIME 7.4.1 +CURLMSG_DONE 7.9.6 +CURLM_BAD_EASY_HANDLE 7.9.6 +CURLM_BAD_HANDLE 7.9.6 +CURLM_CALL_MULTI_PERFORM 7.9.6 +CURLM_CALL_MULTI_SOCKET 7.15.5 +CURLM_INTERNAL_ERROR 7.9.6 +CURLM_OK 7.9.6 +CURLM_OUT_OF_MEMORY 7.9.6 CURLOPT_ADDRESS_SCOPE 7.19.0 CURLOPT_APPEND 7.16.4 CURLOPT_AUTOREFERER 7.1 @@ -150,9 +248,9 @@ CURLOPT_IOCTLDATA 7.12.3 CURLOPT_IOCTLFUNCTION 7.12.3 CURLOPT_IPRESOLVE 7.10.8 CURLOPT_ISSUERCERT 7.19.0 -CURLOPT_KEYPASSWD 7.17.0 -CURLOPT_KRB4LEVEL 7.3 -CURLOPT_KRBLEVEL 7.16.4 +CURLOPT_KEYPASSWD - 7.17.0 +CURLOPT_KRB4LEVEL 7.3 7.17.0 +CURLOPT_KRBLEVEL 7.17.0 CURLOPT_LOCALPORT 7.15.2 CURLOPT_LOCALPORTRANGE 7.15.2 CURLOPT_LOW_SPEED_LIMIT 7.1 @@ -230,11 +328,13 @@ CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 7.17.1 CURLOPT_SSH_PRIVATE_KEYFILE 7.16.1 CURLOPT_SSH_PUBLIC_KEYFILE 7.16.1 CURLOPT_SSLCERT 7.1 +CURLOPT_SSLCERTPASSWD 7.17.0 CURLOPT_SSLCERTTYPE 7.9.3 CURLOPT_SSLENGINE 7.9.3 CURLOPT_SSLENGINE_DEFAULT 7.9.3 CURLOPT_SSLKEY 7.9.3 CURLOPT_SSLKEYPASSWD 7.17.0 +CURLOPT_SSLKEYPASSWD 7.17.0 CURLOPT_SSLKEYTYPE 7.9.3 CURLOPT_SSLVERSION 7.1 CURLOPT_SSL_CIPHER_LIST 7.9 @@ -282,10 +382,24 @@ CURLPROXY_SOCKS4 7.10 CURLPROXY_SOCKS4A 7.18.0 CURLPROXY_SOCKS5 7.10 CURLPROXY_SOCKS5_HOSTNAME 7.18.0 +CURLSSH_AUTH_DEFAULT 7.16.1 +CURLSSH_AUTH_HOST 7.16.1 +CURLSSH_AUTH_KEYBOARD 7.16.1 +CURLSSH_AUTH_NONE 7.16.1 +CURLSSH_AUTH_PASSWORD 7.16.1 +CURLSSH_AUTH_PUBLICKEY 7.16.1 +CURLUSESSL_ALL 7.17.0 CURLUSESSL_ALL 7.17.0 CURLUSESSL_CONTROL 7.17.0 +CURLUSESSL_CONTROL 7.17.0 CURLUSESSL_NONE 7.17.0 +CURLUSESSL_NONE 7.17.0 +CURLUSESSL_TRY 7.17.0 CURLUSESSL_TRY 7.17.0 +CURLVERSION_FIRST 7.10 +CURLVERSION_NOW 7.10 +CURLVERSION_SECOND 7.11.1 +CURLVERSION_THIRD 7.12.0 CURL_HTTP_VERSION_1_0 7.9.1 CURL_HTTP_VERSION_1_1 7.9.1 CURL_HTTP_VERSION_NONE 7.9.1 @@ -302,6 +416,9 @@ CURL_SSLVERSION_DEFAULT 7.9.2 CURL_SSLVERSION_SSLv2 7.9.2 CURL_SSLVERSION_SSLv3 7.9.2 CURL_SSLVERSION_TLSv1 7.9.2 +CURL_TIMECOND_IFMODSINCE 7.9.7 +CURL_TIMECOND_IFUNMODSINCE 7.9.7 +CURL_TIMECOND_LASTMOD 7.9.7 CURL_VERSION_ASYNCHDNS 7.10.7 CURL_VERSION_CONV 7.15.4 CURL_VERSION_DEBUG 7.10.6 -- cgit v1.2.1 From 644482fc990a55f0cce2837bd29d2c5dad7f7b35 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 May 2009 21:36:53 +0000 Subject: more return codes added --- docs/libcurl/symbols-in-versions | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 0ea7deb35..e2db2fa33 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -25,6 +25,7 @@ CURLCLOSEPOLICY_LEAST_TRAFFIC 7.7 CURLCLOSEPOLICY_OLDEST 7.7 CURLCLOSEPOLICY_SLOWEST 7.7 CURLE_ABORTED_BY_CALLBACK 7.1 +CURLE_AGAIN 7.18.2 CURLE_BAD_CALLING_ORDER 7.1 7.17.0 CURLE_BAD_CONTENT_ENCODING 7.10 CURLE_BAD_FUNCTION_ARGUMENT 7.1 @@ -87,10 +88,13 @@ CURLE_SSL_CACERT 7.10 CURLE_SSL_CERTPROBLEM 7.10 CURLE_SSL_CIPHER 7.10 CURLE_SSL_CONNECT_ERROR 7.1 +CURLE_SSL_CRL_BADFILE 7.19.0 CURLE_SSL_ENGINE_INITFAILED 7.13.0 CURLE_SSL_ENGINE_NOTFOUND 7.9.3 CURLE_SSL_ENGINE_SETFAILED 7.9.3 +CURLE_SSL_ISSUER_ERROR 7.19.0 CURLE_SSL_PEER_CERTIFICATE 7.17.1 +CURLE_SSL_SHUTDOWN_FAILED 7.16.1 CURLE_TELNET_OPTION_SYNTAX 7.7 CURLE_TFTP_DISKFULL 7.15.0 7.17.0 CURLE_TFTP_EXISTS 7.15.0 7.17.0 -- cgit v1.2.1 From e93c81196f6ef8aa38fc330f3b50143160e28bc0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 7 May 2009 09:31:24 +0000 Subject: - Man page *roff problems fixed thanks to input from Colin Watson. Problems reported in the Debian package. --- docs/libcurl/curl_easy_getinfo.3 | 4 ++-- docs/libcurl/curl_easy_setopt.3 | 4 ++-- docs/libcurl/curl_multi_info_read.3 | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index afb087084..29f0f44ad 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -209,7 +209,7 @@ this returns a 1 you know that the reason you didn't get data in return is because it didn't fulfill the condition. The long ths argument points to will get a zero stored if the condition instead was met. (Added in 7.19.4) .SH TIMES -.NF +.nf An overview of the six time values available from curl_easy_getinfo() curl_easy_perform() @@ -221,7 +221,7 @@ curl_easy_perform() |--|--|--|--|--STARTTRANSFER |--|--|--|--|--|--TOTAL |--|--|--|--|--|--REDIRECT -.FI +.fi .IP NAMELOOKUP \fICURLINFO_NAMELOOKUP_TIME\fP. The time it took from the start until the name resolving was completed. diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 06e3a11b9..49d9cdd04 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -235,9 +235,9 @@ at the user's discretion. \fICURL_SOCKET_BAD\fP return value from the callback function will signal an unrecoverable error to the library and it will return \fICURLE_COULDNT_CONNECT\fP. This return code can be used for IP address blacklisting. The default behavior is: -.Bd -literal -offset indent +.nf return socket(addr->family, addr->socktype, addr->protocol); -.Ed +.fi (Option added in 7.17.1.) .IP CURLOPT_OPENSOCKETDATA Pass a pointer that will be untouched by libcurl and passed as the first diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index e5539c1dc..3a58c642e 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -34,7 +34,7 @@ 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): -.NF +.nf struct CURLMsg { CURLMSG msg; /* what this message means */ CURL *easy_handle; /* the handle it concerns */ @@ -43,7 +43,7 @@ present in that struct and can thus be used in subsequent regular CURLcode result; /* return code for transfer */ } data; }; - +.fi 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. -- cgit v1.2.1 From 197830a57ddac917a527cab50c25871b1cff3d62 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 May 2009 20:24:14 +0000 Subject: TELNET transfers and SOCKS handshakes are blocking too --- docs/libcurl/libcurl-multi.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 0b70ae943..0e75bde03 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -136,6 +136,8 @@ the future, you should be aware of the following current restrictions: - GnuTLS SSL connections - Active FTP connections - HTTP proxy CONNECT operations + - SOCKS proxy handshakes - TFTP transfers - file:// transfers + - TELNET transfers .fi -- cgit v1.2.1 From 78c674a6852a4ef6ccec2b13d2d1f655a8c18549 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 May 2009 20:31:17 +0000 Subject: curl_multi_socket_action() is the one we favor! --- docs/libcurl/libcurl-multi.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 0e75bde03..af2198498 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -124,7 +124,7 @@ applications to not only avoid being forced to use select(), but it also 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 +\fIcurl_multi_socket_action(3)\fP is then used instead of \fIcurl_multi_perform(3)\fP. .SH "BLOCKING" A few areas in the code are still using blocking code, even when used from the -- cgit v1.2.1 From 8f9d4b2b50da3702a5b3fe1fea2e599746596f16 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 11 May 2009 20:32:50 +0000 Subject: split off curl_multi_socket_action() into its own separate man page as this is the function we should use, while both curl_multi_socket() and curl_multi_socket_all() should be killed! --- docs/libcurl/Makefile.am | 75 +++++++++--------- docs/libcurl/curl_multi_socket.3 | 23 +----- docs/libcurl/curl_multi_socket_action.3 | 132 ++++++++++++++++++++++++++++++++ 3 files changed, 173 insertions(+), 57 deletions(-) create mode 100644 docs/libcurl/curl_multi_socket_action.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index c2b5f92c5..032f8d344 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -19,44 +19,47 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \ - curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 + curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 \ + curl_multi_socket_action.3 -HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ - curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ - curl_easy_duphandle.html curl_formadd.html curl_formfree.html \ - curl_getdate.html curl_getenv.html curl_slist_append.html \ - curl_slist_free_all.html curl_version.html curl_version_info.html \ - curl_escape.html curl_unescape.html curl_free.html curl_strequal.html \ - curl_mprintf.html curl_global_init.html curl_global_cleanup.html \ - curl_multi_add_handle.html curl_multi_cleanup.html curl_multi_fdset.html \ - curl_multi_info_read.html curl_multi_init.html curl_multi_perform.html \ - curl_multi_remove_handle.html curl_share_cleanup.html \ - curl_share_init.html curl_share_setopt.html libcurl.html \ - libcurl-multi.html libcurl-easy.html libcurl-share.html \ - libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ - curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \ - curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \ - curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \ - curl_formget.html curl_multi_assign.html curl_easy_pause.html \ - curl_easy_recv.html curl_easy_send.html +HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ + curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ + curl_easy_duphandle.html curl_formadd.html curl_formfree.html \ + curl_getdate.html curl_getenv.html curl_slist_append.html \ + curl_slist_free_all.html curl_version.html curl_version_info.html \ + curl_escape.html curl_unescape.html curl_free.html curl_strequal.html \ + curl_mprintf.html curl_global_init.html curl_global_cleanup.html \ + curl_multi_add_handle.html curl_multi_cleanup.html \ + curl_multi_fdset.html curl_multi_info_read.html curl_multi_init.html \ + curl_multi_perform.html curl_multi_remove_handle.html \ + curl_share_cleanup.html curl_share_init.html curl_share_setopt.html \ + libcurl.html libcurl-multi.html libcurl-easy.html libcurl-share.html \ + libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ + curl_share_strerror.html curl_global_init_mem.html \ + libcurl-tutorial.html curl_easy_reset.html curl_easy_escape.html \ + curl_easy_unescape.html curl_multi_setopt.html curl_multi_socket.html \ + curl_multi_timeout.html curl_formget.html curl_multi_assign.html \ + curl_easy_pause.html curl_easy_recv.html curl_easy_send.html \ + curl_multi_socket_action.html -PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ - curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \ - curl_formadd.pdf curl_formfree.pdf curl_getdate.pdf curl_getenv.pdf \ - curl_slist_append.pdf curl_slist_free_all.pdf curl_version.pdf \ - curl_version_info.pdf curl_escape.pdf curl_unescape.pdf curl_free.pdf \ - curl_strequal.pdf curl_mprintf.pdf curl_global_init.pdf \ - curl_global_cleanup.pdf curl_multi_add_handle.pdf curl_multi_cleanup.pdf \ - curl_multi_fdset.pdf curl_multi_info_read.pdf curl_multi_init.pdf \ - curl_multi_perform.pdf curl_multi_remove_handle.pdf \ - curl_share_cleanup.pdf curl_share_init.pdf curl_share_setopt.pdf \ - libcurl.pdf libcurl-multi.pdf libcurl-easy.pdf libcurl-share.pdf \ - libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ - curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ - curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \ - curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \ - curl_formget.pdf curl_multi_assign.pdf curl_easy_pause.pdf \ - curl_easy_recv.pdf curl_easy_send.pdf +PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ + curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ + curl_easy_duphandle.pdf curl_formadd.pdf curl_formfree.pdf \ + curl_getdate.pdf curl_getenv.pdf curl_slist_append.pdf \ + curl_slist_free_all.pdf curl_version.pdf curl_version_info.pdf \ + curl_escape.pdf curl_unescape.pdf curl_free.pdf curl_strequal.pdf \ + curl_mprintf.pdf curl_global_init.pdf curl_global_cleanup.pdf \ + curl_multi_add_handle.pdf curl_multi_cleanup.pdf curl_multi_fdset.pdf \ + curl_multi_info_read.pdf curl_multi_init.pdf curl_multi_perform.pdf \ + curl_multi_remove_handle.pdf curl_share_cleanup.pdf curl_share_init.pdf \ + curl_share_setopt.pdf libcurl.pdf libcurl-multi.pdf libcurl-easy.pdf \ + libcurl-share.pdf libcurl-errors.pdf curl_easy_strerror.pdf \ + curl_multi_strerror.pdf curl_share_strerror.pdf \ + curl_global_init_mem.pdf libcurl-tutorial.pdf curl_easy_reset.pdf \ + curl_easy_escape.pdf curl_easy_unescape.pdf curl_multi_setopt.pdf \ + curl_multi_socket.pdf curl_multi_timeout.pdf curl_formget.pdf \ + curl_multi_assign.pdf curl_easy_pause.pdf curl_easy_recv.pdf \ + curl_easy_send.pdf curl_multi_socket_action.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index a38532d23..2029e4311 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -6,14 +6,6 @@ curl_multi_socket \- reads/writes available data .SH SYNOPSIS .nf #include - -CURLMcode curl_multi_socket_action(CURLM * multi_handle, - curl_socket_t sockfd, int ev_bitmask, - int *running_handles); -.fi - -.B "Now deprecated versions:" -.nf CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd, int *running_handles); @@ -21,19 +13,8 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle, int *running_handles); .fi .SH DESCRIPTION -Alternative versions of \fIcurl_multi_perform(3)\fP that allows the -application to pass in the file descriptor/socket that has been detected to -have \&"action" on it and let libcurl perform. This lets libcurl avoid having -to scan through all possible file descriptors to check for action. - -When the application has detected action on a socket handled by libcurl, it -should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument -set to the socket with the action. When the events on a socket are known, they -can be passed as an events bitmask \fBev_bitmask\fP by first setting -\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of -events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or -CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and -libcurl will test the descriptor internally. +These functions are deprecated. Do not use! See +\fIcurl_multi_socket_action(3)\fP instead! At return, the integer \fBrunning_handles\fP points to will contain the number of still running easy handles within the multi handle. When this number diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 new file mode 100644 index 000000000..5287b44c3 --- /dev/null +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -0,0 +1,132 @@ +.\" $Id$ +.\" +.TH curl_multi_socket_action 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" +.SH NAME +curl_multi_socket_action \- reads/writes available data given an action +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_socket_action(CURLM * multi_handle, + curl_socket_t sockfd, int ev_bitmask, + int *running_handles); +.fi +.SH DESCRIPTION +When the application has detected action on a socket handled by libcurl, it +should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument +set to the socket with the action. When the events on a socket are known, they +can be passed as an events bitmask \fBev_bitmask\fP by first setting +\fBev_bitmask\fP to 0, and then adding using bitwise OR (|) any combination of +events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or +CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and +libcurl will test the descriptor internally. + +At return, the integer \fBrunning_handles\fP points to will contain the number +of still running easy handles within the multi handle. When this number +reaches zero, all transfers are complete/done. Note that when you call +\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter +decreases by one, it DOES NOT necessarily mean that this exact socket/transfer +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 +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. + +Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION\fP option with +\fIcurl_multi_setopt(3)\fP. Your application will then get called with +information on how long to wait for socket actions at most before doing the +timeout action: call the \fBcurl_multi_socket_action(3)\fP function with the +\fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the +\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but +for an event-based system using the callback is far better than relying on +polling the timeout value. +.SH "CALLBACK DETAILS" + +The socket \fBcallback\fP function uses a prototype like this +.nf + + int curl_socket_callback(CURL *easy, /* easy handle */ + curl_socket_t s, /* socket */ + int action, /* see values below */ + void *userp, /* private callback pointer */ + void *socketp); /* private socket pointer */ + +.fi +The callback MUST return 0. + +The \fIeasy\fP argument is a pointer to the easy handle that deals with this +particular socket. Note that a single handle may work with several sockets +simultaneously. + +The \fIs\fP argument is the actual socket value as you use it within your +system. + +The \fIaction\fP argument to the callback has one of five values: +.RS +.IP "CURL_POLL_NONE (0)" +register, not interested in readiness (yet) +.IP "CURL_POLL_IN (1)" +register, interested in read readiness +.IP "CURL_POLL_OUT (2)" +register, interested in write readiness +.IP "CURL_POLL_INOUT (3)" +register, interested in both read and write readiness +.IP "CURL_POLL_REMOVE (4)" +unregister +.RE + +The \fIsocketp\fP argument is a private pointer you have previously set with +\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no +pointer has been set, socketp will be NULL. This argument is of course a +service to applications that want to keep certain data or structs that are +strictly associated to the given socket. + +The \fIuserp\fP argument is a private pointer you have previously set with +\fIcurl_multi_setopt(3)\fP and the CURLMOPT_SOCKETDATA option. +.SH "RETURN VALUE" +CURLMcode type, general libcurl multi interface error code. + +Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means +that you should call \fIcurl_multi_socket_action(3)\fP again, before you wait +for more actions on libcurl's sockets. 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". + +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. Problems still might have +occurred on individual transfers even when one of these functions +return OK. +.SH "TYPICAL USAGE" +1. Create a multi handle + +2. Set the socket callback with CURLMOPT_SOCKETFUNCTION + +3. Set the timeout callback with CURLMOPT_TIMERFUNCTION, to get to know what +timeout value to use when waiting for socket activities. + +4. Add easy handles with curl_multi_add_handle() + +5. Provide some means to manage the sockets libcurl is using, so you can check +them for activity. This can be done through your application code, or by way +of an external library such as libevent or glib. + +6. Wait for activity on any of libcurl's sockets, use the timeout value your +callback has been told + +7, When activity is detected, call curl_multi_socket_action() for the +socket(s) that got action. If no activity is detected and the timeout expires, +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, and is deemed stable since 7.16.0. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " +.BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " +.BR "the hiperfifo.c example" -- cgit v1.2.1 From dd3c1874846d65ffd3233708ccc86d0d7e621a48 Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Tue, 19 May 2009 12:48:14 +0000 Subject: Force revision update, to force CVS to update the $Id date string format --- docs/libcurl/curl_easy_escape.3 | 94 +++++++++++++++++----------------- docs/libcurl/curl_easy_unescape.3 | 104 +++++++++++++++++++------------------- docs/libcurl/curl_escape.3 | 62 +++++++++++------------ docs/libcurl/curl_unescape.3 | 62 +++++++++++------------ 4 files changed, 161 insertions(+), 161 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3 index d9ff6222a..de3059397 100644 --- a/docs/libcurl/curl_easy_escape.3 +++ b/docs/libcurl/curl_easy_escape.3 @@ -1,47 +1,47 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. -.\" * -.\" * This software is licensed as described in the file COPYING, which -.\" * you should have received as part of this distribution. The terms -.\" * are also available at http://curl.haxx.se/docs/copyright.html. -.\" * -.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell -.\" * copies of the Software, and permit persons to whom the Software is -.\" * furnished to do so, under the terms of the COPYING file. -.\" * -.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -.\" * KIND, either express or implied. -.\" * -.\" * $Id$ -.\" ************************************************************************** -.\" -.TH curl_easy_escape 3 "7 April 2006" "libcurl 7.15.4" "libcurl Manual" -.SH NAME -curl_easy_escape - URL encodes the given string -.SH SYNOPSIS -.B #include -.sp -.BI "char *curl_easy_escape( CURL *" curl ", char *" url ", int "length " );" -.ad -.SH DESCRIPTION -This function converts the given input string to an URL encoded string and -returns that as a new allocated string. All input characters that are not a-z, -A-Z or 0-9 are converted to their "URL escaped" version (%NN where NN is a -two-digit hexadecimal number). - -If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_escape(3)\fP -uses strlen() on the input \fBurl\fP to find out the size. - -You must \fIcurl_free(3)\fP the returned string when you're done with it. -.SH AVAILABILITY -Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function. -.SH RETURN VALUE -A pointer to a zero terminated string or NULL if it failed. -.SH "SEE ALSO" -.BR curl_easy_unescape "(3), " curl_free "(3), " RFC 2396 +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** +.\" +.TH curl_easy_escape 3 "7 April 2006" "libcurl 7.15.4" "libcurl Manual" +.SH NAME +curl_easy_escape - URL encodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_easy_escape( CURL *" curl ", char *" url ", int "length " );" +.ad +.SH DESCRIPTION +This function converts the given input string to an URL encoded string and +returns that as a new allocated string. All input characters that are not a-z, +A-Z or 0-9 are converted to their "URL escaped" version (%NN where NN is a +two-digit hexadecimal number). + +If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_escape(3)\fP +uses strlen() on the input \fBurl\fP to find out the size. + +You must \fIcurl_free(3)\fP the returned string when you're done with it. +.SH AVAILABILITY +Added in 7.15.4 and replaces the old \fIcurl_escape(3)\fP function. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.BR curl_easy_unescape "(3), " curl_free "(3), " RFC 2396 diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3 index b3fe5f02b..2aef6b098 100644 --- a/docs/libcurl/curl_easy_unescape.3 +++ b/docs/libcurl/curl_easy_unescape.3 @@ -1,52 +1,52 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. -.\" * -.\" * This software is licensed as described in the file COPYING, which -.\" * you should have received as part of this distribution. The terms -.\" * are also available at http://curl.haxx.se/docs/copyright.html. -.\" * -.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell -.\" * copies of the Software, and permit persons to whom the Software is -.\" * furnished to do so, under the terms of the COPYING file. -.\" * -.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -.\" * KIND, either express or implied. -.\" * -.\" * $Id$ -.\" ************************************************************************** -.\" -.TH curl_easy_unescape 3 "7 April 2006" "libcurl 7.15.4" "libcurl Manual" -.SH NAME -curl_easy_unescape - URL decodes the given string -.SH SYNOPSIS -.B #include -.sp -.BI "char *curl_easy_unescape( CURL *" curl ", char *" url ", int "inlength -.BI ", int *" outlength " );" -.ad -.SH DESCRIPTION -This function converts the given URL encoded input string to a "plain string" -and returns that in an allocated memory area. All input characters that are -URL encoded (%XX where XX is a two-digit hexadecimal number) are converted to -their binary versions. - -If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP -will use strlen() on the input \fIurl\fP string to find out the size. - -If \fBoutlength\fP is non-NULL, the function will write the length of the -returned string in the integer it points to. This allows an escaped string -containing %00 to still get used properly after unescaping. - -You must \fIcurl_free(3)\fP the returned string when you're done with it. -.SH AVAILABILITY -Added in 7.15.4 and replaces the old \fIcurl_unescape(3)\fP function. -.SH RETURN VALUE -A pointer to a zero terminated string or NULL if it failed. -.SH "SEE ALSO" -.I curl_easy_escape(3), curl_free(3), RFC 2396 +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * $Id$ +.\" ************************************************************************** +.\" +.TH curl_easy_unescape 3 "7 April 2006" "libcurl 7.15.4" "libcurl Manual" +.SH NAME +curl_easy_unescape - URL decodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_easy_unescape( CURL *" curl ", char *" url ", int "inlength +.BI ", int *" outlength " );" +.ad +.SH DESCRIPTION +This function converts the given URL encoded input string to a "plain string" +and returns that in an allocated memory area. All input characters that are +URL encoded (%XX where XX is a two-digit hexadecimal number) are converted to +their binary versions. + +If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP +will use strlen() on the input \fIurl\fP string to find out the size. + +If \fBoutlength\fP is non-NULL, the function will write the length of the +returned string in the integer it points to. This allows an escaped string +containing %00 to still get used properly after unescaping. + +You must \fIcurl_free(3)\fP the returned string when you're done with it. +.SH AVAILABILITY +Added in 7.15.4 and replaces the old \fIcurl_unescape(3)\fP function. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.I curl_easy_escape(3), curl_free(3), RFC 2396 diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 2007d69ef..1c2774401 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -1,31 +1,31 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ -.\" -.TH curl_escape 3 "6 March 2002" "libcurl 7.9" "libcurl Manual" -.SH NAME -curl_escape - URL encodes the given string -.SH SYNOPSIS -.B #include -.sp -.BI "char *curl_escape( char *" url ", int "length " );" -.ad -.SH DESCRIPTION -Obsolete function. Use \fIcurl_easy_escape(3)\fP instead! - -This function will convert the given input string to an URL encoded string and -return that as a new allocated string. All input characters that are not a-z, -A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a -two-digit hexadecimal number). - -If the 'length' argument is set to 0, curl_escape() will use strlen() on the -input 'url' string to find out the size. - -You must curl_free() the returned string when you're done with it. -.SH AVAILABILITY -Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function will -be removed in a future release. -.SH RETURN VALUE -A pointer to a zero terminated string or NULL if it failed. -.SH "SEE ALSO" -.BR curl_unescape "(3), " curl_free "(3), " RFC 2396 +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_escape 3 "6 March 2002" "libcurl 7.9" "libcurl Manual" +.SH NAME +curl_escape - URL encodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_escape( char *" url ", int "length " );" +.ad +.SH DESCRIPTION +Obsolete function. Use \fIcurl_easy_escape(3)\fP instead! + +This function will convert the given input string to an URL encoded string and +return that as a new allocated string. All input characters that are not a-z, +A-Z or 0-9 will be converted to their "URL escaped" version (%NN where NN is a +two-digit hexadecimal number). + +If the 'length' argument is set to 0, curl_escape() will use strlen() on the +input 'url' string to find out the size. + +You must curl_free() the returned string when you're done with it. +.SH AVAILABILITY +Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function will +be removed in a future release. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.BR curl_unescape "(3), " curl_free "(3), " RFC 2396 diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index d4c5797b0..561ef8f07 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -1,31 +1,31 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" $Id$ -.\" -.TH curl_unescape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" -.SH NAME -curl_unescape - URL decodes the given string -.SH SYNOPSIS -.B #include -.sp -.BI "char *curl_unescape( char *" url ", int "length " );" -.ad -.SH DESCRIPTION -Obsolete function. Use \fIcurl_easy_unescape(3)\fP instead! - -This function will convert the given URL encoded input string to a "plain -string" and return that as a new allocated string. All input characters that -are URL encoded (%XX where XX is a two-digit hexadecimal number) will be -converted to their plain text versions. - -If the 'length' argument is set to 0, curl_unescape() will use strlen() on the -input 'url' string to find out the size. - -You must curl_free() the returned string when you're done with it. -.SH AVAILABILITY -Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function will -be removed in a future release. -.SH RETURN VALUE -A pointer to a zero terminated string or NULL if it failed. -.SH "SEE ALSO" -.I curl_easy_escape(3), curl_easy_unescape(3), curl_free(3), RFC 2396 +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_unescape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" +.SH NAME +curl_unescape - URL decodes the given string +.SH SYNOPSIS +.B #include +.sp +.BI "char *curl_unescape( char *" url ", int "length " );" +.ad +.SH DESCRIPTION +Obsolete function. Use \fIcurl_easy_unescape(3)\fP instead! + +This function will convert the given URL encoded input string to a "plain +string" and return that as a new allocated string. All input characters that +are URL encoded (%XX where XX is a two-digit hexadecimal number) will be +converted to their plain text versions. + +If the 'length' argument is set to 0, curl_unescape() will use strlen() on the +input 'url' string to find out the size. + +You must curl_free() the returned string when you're done with it. +.SH AVAILABILITY +Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function will +be removed in a future release. +.SH RETURN VALUE +A pointer to a zero terminated string or NULL if it failed. +.SH "SEE ALSO" +.I curl_easy_escape(3), curl_easy_unescape(3), curl_free(3), RFC 2396 -- cgit v1.2.1 From 15eaf27bc7b4ad33af275b9cd0601ef19d54ac9c Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Thu, 28 May 2009 21:32:31 +0000 Subject: Fixed a few comment typos (from the FreeBSD ports) --- docs/libcurl/libcurl-tutorial.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 7bbdc8a4a..9b2cb043c 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -754,7 +754,7 @@ to another language and execute that. - Read the Javascript code and rewrite the same logic in another language. -- Implement a Javascript interpreted, people have successfully used the +- Implement a Javascript interpreter; people have successfully used the Mozilla Javascript engine in the past. - Ask your admins to stop this, for a static proxy setup or similar. -- cgit v1.2.1 From 2c166812253c28cdfbffdd4de069f5c11db3c7a8 Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Wed, 10 Jun 2009 02:49:42 +0000 Subject: Adjusted to take in account that... With the curl memory tracking feature decoupled from the debug build feature, CURLDEBUG and DEBUGBUILD preprocessor symbol definitions are used as follows: CURLDEBUG used for curl debug memory tracking specific code (--enable-curldebug) DEBUGBUILD used for debug enabled specific code (--enable-debug) --- docs/libcurl/curl_version_info.3 | 10 ++++++---- docs/libcurl/symbols-in-versions | 1 + 2 files changed, 7 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index e090e6066..ea4214c1b 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2006, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_version_info 3 "2 Nov 2006" "libcurl 7.16.1" "libcurl Manual" +.TH curl_version_info 3 "10 June 2009" "libcurl 7.19.6" "libcurl Manual" .SH NAME curl_version_info - returns run-time libcurl version info .SH SYNOPSIS @@ -105,8 +105,10 @@ supports HTTP NTLM (added in 7.10.6) .IP CURL_VERSION_GSSNEGOTIATE supports HTTP GSS-Negotiate (added in 7.10.6) .IP CURL_VERSION_DEBUG -libcurl was built with extra debug capabilities built-in. This is mainly of -interest for libcurl hackers. (added in 7.10.6) +libcurl was built with debug capabilities (added in 7.10.6) +.IP CURL_VERSION_CURLDEBUG +libcurl was built with memory tracking debug capabilities. This is mainly of +interest for libcurl hackers. (added in 7.19.6) .IP CURL_VERSION_ASYNCHDNS libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index e2db2fa33..1b53eeaf7 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -425,6 +425,7 @@ CURL_TIMECOND_IFUNMODSINCE 7.9.7 CURL_TIMECOND_LASTMOD 7.9.7 CURL_VERSION_ASYNCHDNS 7.10.7 CURL_VERSION_CONV 7.15.4 +CURL_VERSION_CURLDEBUG 7.19.6 CURL_VERSION_DEBUG 7.10.6 CURL_VERSION_GSSNEGOTIATE 7.10.6 CURL_VERSION_IDN 7.12.0 -- cgit v1.2.1 From 9d18c0b15658adcdb6743107be0db4745d2b8073 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 10 Jun 2009 18:43:07 +0000 Subject: extended the CURLOPT_HEADERFUNCTION description with Aaron Oneal's help --- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 49d9cdd04..eee750b57 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -282,6 +282,13 @@ NULL, the function used to accept response data will be used instead. That is, it will be the function specified with \fICURLOPT_WRITEFUNCTION\fP, or if it is not specified or NULL - the default, stream-writing function. +It's important to note that the callback will be invoked for the headers of +all responses received after initiating a request and not just the final +response. This includes all responses which occur during authentication +negotiation. If you need to operate on only the headers from the final +response, you will need to collect headers in the callback yourself and use +HTTP status lines, for example, to delimit response boundaries. + Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a trailer. That trailer is identical to a HTTP header and if such a trailer is received it is passed to the application using this callback as well. There -- cgit v1.2.1 From 7ae624e7004338683c659fe881c1847fe9ee708a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 15 Jun 2009 20:49:23 +0000 Subject: curl_multi_socket_action() is the one to use nowadays, as Mohun Biswas pointed out! --- docs/libcurl/libcurl-multi.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index af2198498..17041f576 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -119,10 +119,10 @@ If you want to re-use an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it 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 +Since 7.16.0, the \fIcurl_multi_socket_action(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-performance API that will make a significant difference -for applications using large numbers of simultaneous connections. +offers a much more high-performance API that will make a significant +difference for applications using large numbers of simultaneous connections. \fIcurl_multi_socket_action(3)\fP is then used instead of \fIcurl_multi_perform(3)\fP. -- cgit v1.2.1 From 4f551259ddf79163660fdf44ec57b6ed2f409e50 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 29 Jun 2009 20:46:01 +0000 Subject: - Markus Koetter made CURLOPT_FTPPORT (and curl's -P/--ftpport) support a port range if given colon-separated after the host name/address part. Like "192.168.0.1:2000-10000" --- docs/libcurl/curl_easy_setopt.3 | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index eee750b57..e1ffeade1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1070,6 +1070,12 @@ 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. +Starting in 7.19.5, you can append \&":[start]-[end]\&" to the right of the +address, to tell libcurl what TCP port range to use. That means you specify a +port range, from a lower to a higher number. A single number works as well, +but do not that it increases the risk of failure since the port may not be +available. + You disable PORT again and go back to using the passive version by setting this option to NULL. .IP CURLOPT_QUOTE -- cgit v1.2.1 From 3050f1067624c1607bf638d20dd02ba692ff6289 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 30 Jun 2009 21:32:52 +0000 Subject: silly typo, pointed out by Fabian Keil --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e1ffeade1..434ccf973 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1073,7 +1073,7 @@ address. Default FTP operations are passive, and thus won't use PORT. Starting in 7.19.5, you can append \&":[start]-[end]\&" to the right of the address, to tell libcurl what TCP port range to use. That means you specify a port range, from a lower to a higher number. A single number works as well, -but do not that it increases the risk of failure since the port may not be +but do note that it increases the risk of failure since the port may not be available. You disable PORT again and go back to using the passive version by setting -- cgit v1.2.1 From f3403d4c5bde46cccda95c1c38a7f55129536bae Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 8 Jul 2009 07:20:42 +0000 Subject: Markus Koetter's man page updates for the FTPPORT ranges --- docs/libcurl/curl_easy_setopt.3 | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 434ccf973..94c1fc971 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1070,11 +1070,22 @@ 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. -Starting in 7.19.5, you can append \&":[start]-[end]\&" to the right of the -address, to tell libcurl what TCP port range to use. That means you specify a -port range, from a lower to a higher number. A single number works as well, -but do note that it increases the risk of failure since the port may not be -available. +The address can be followed by a ':' to specify a port, optionally followed by +a '-' to specify a port range. If the port specified is 0, the operating +system will pick a free port. If a range is provided and all ports in the +range are not available, libcurl will report CURLE_FTP_PORT_FAILED for the +handle. Invalid port/range settings are ignored. IPv6 addresses followed by +a port or portrange have to be in brackets. IPv6 addresses without port/range +specifier can be in brackets. (added in 7.19.5) + +Examples with specified ports: + +.nf + eth0:0 + 192.168.1.2:32000-33000 + curl.se:32123 + [::1]:1234-4567 +.fi You disable PORT again and go back to using the passive version by setting this option to NULL. -- cgit v1.2.1 From 08d95bff5e919a59f91417af091a34cea6004e3d Mon Sep 17 00:00:00 2001 From: Michal Marek Date: Wed, 15 Jul 2009 11:49:12 +0000 Subject: - Changed the description of CURLINFO_OS_ERRNO to make it clear that the errno is not reset on success. --- docs/libcurl/curl_easy_getinfo.3 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 29f0f44ad..e227f0790 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -159,7 +159,8 @@ Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available for your proxy authentication. (Added in 7.10.8) .IP CURLINFO_OS_ERRNO Pass a pointer to a long to receive the errno variable from a connect failure. -(Added in 7.12.2) +Note that the value is only set on failure, it is not reset upon a +successfull operation. (Added in 7.12.2) .IP CURLINFO_NUM_CONNECTS Pass a pointer to a long to receive how many new connections libcurl had to create to achieve the previous transfer (only the successful connects are -- cgit v1.2.1 From 47c392e135f17d400acc5d7e99b88d16578cb406 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 22 Jul 2009 22:49:01 +0000 Subject: - Added CURLOPT_SSH_KNOWNHOSTS, CURLOPT_SSH_KEYFUNCTION, CURLOPT_SSH_KEYDATA. They introduce known_host support for SSH keys to libcurl. See docs for details. --- docs/libcurl/curl_easy_setopt.3 | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 94c1fc971..b30e04f06 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1743,6 +1743,44 @@ Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to using \fB~/.ssh/id_dsa\fP. If the file is password-protected, set the password with \fICURLOPT_KEYPASSWD\fP. (Added in 7.16.1) +.IP CURLOPT_SSH_KNOWNHOSTS +Pass a pointer to a zero terminated string holding the file name of the +known_host file to use. The known_hosts file should use the OpenSSH file +format as supported by libssh2. If this file is specified, libcurl will only +accept connections with hosts that are known and present in that file, with a +matching public key. Use \fICURLOPT_SSH_KEYFUNCTION\fP to alter the default +behavior on host and key (mis)matching. (Added in 7.19.6) +.IP CURLOPT_SSH_KEYFUNCTION +Pass a pointer to a curl_sshkeycallback function. It gets called when the +known_host matching has been done, to allow the application to act and decide +for libcurl how to proceed. It gets passed the CURL handle, the key from the +known_hosts file, the key from the remote site, info from libcurl on the +matching status and a custom pointer (set with \fICURLOPT_SSH_KEYDATA\fP). It +MUST return one of the following return codes to tell libcurl how to act: +.RS +.IP CURLKHSTAT_FINE_ADD_TO_FILE +The host+key is accepted and libcurl will append it to the known_hosts file +before continuing with the connection. This will also add the host+key combo +to the known_host pool kept in memory if it wasn't already present there. Note +that the adding of data to the file is done by completely replacing the file +with a new copy, so the permissions of the file must allow this. +.IP CURLKHSTAT_FINE +The host+key is accepted libcurl will continue with the connection. This will +also add the host+key combo to the known_host pool kept in memory if it wasn't +already present there. +.IP CURLKHSTAT_REJECT +The host+key is rejected. libcurl will deny the connection to continue and it +will be closed. +.IP CURLKHSTAT_DEFER +The host+key is rejected, but the SSH connection is asked to be kept alive. +This feature could be used when the app wants to somehow return back and act +on the host+key situation and then retry without needing the overhead of +setting it up from scratch again. +.RE + (Added in 7.19.6) +.IP CURLOPT_SSH_KEYDATA +Pass a void * as parameter. This pointer will be passed along verbatim to the +callback set with \fICURLOPT_SSH_KEYFUNCTION\fP. (Added in 7.19.6) .SH OTHER OPTIONS .IP CURLOPT_PRIVATE Pass a void * as parameter, pointing to data that should be associated with -- cgit v1.2.1 From 37d509f04fc9d54beb3185b866b8fe40a6af6cfb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 Aug 2009 12:02:27 +0000 Subject: RFC1867 was updated by RFC2388 --- docs/libcurl/curl_easy_setopt.3 | 2 +- docs/libcurl/curl_formadd.3 | 2 +- docs/libcurl/libcurl-tutorial.3 | 15 ++++++++------- 3 files changed, 10 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b30e04f06..40447caa9 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -870,7 +870,7 @@ data using the read callback! Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. -To make multipart/formdata posts (aka rfc1867-posts), check out the +To make multipart/formdata posts (aka RFC2388-posts), check out the \fICURLOPT_HTTPPOST\fP option. .IP CURLOPT_POSTFIELDSIZE If you want to post data to the server without letting libcurl do a strlen() diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 190a6b20d..cf692ea52 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -13,7 +13,7 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata -HTTP POST (sometimes referred to as rfc1867-style posts). Append one section at +HTTP POST (sometimes referred to as RFC2388-style posts). Append one section at a time until you've added all the sections you want included and then you pass the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. \fIlastitem\fP is set after each call and on repeated invokes it should be diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 9b2cb043c..497551633 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -502,13 +502,14 @@ 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 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 -that you build a formpost yourself and provide to libcurl. To make that -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. +and were first documented in the RFC1867 (updated in RFC2388). They're called +multi-part because they're built by a chain of parts, each part being a single +unit of data. 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 that you build a formpost yourself and provide +to libcurl. To make that 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 uploads the whole thing. -- cgit v1.2.1 From a0bbe25eef78808a54d014b8c9b7a4c01ac02d4d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 2 Sep 2009 14:57:05 +0000 Subject: spell out that when running_handles is zero, there is no longer any transfers going on --- docs/libcurl/curl_multi_perform.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 087f46466..746ff3de0 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -23,6 +23,9 @@ you've added to the multi handle), you know that there is one or more transfers less "running". You can then call \fIcurl_multi_info_read(3)\fP to get information about each individual completed transfer, and that returned info includes CURLcode and more. + +When \fIrunning_handles\fP is set to zero (0) on the return of this function, +there is no longer any transfers in progress. .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. -- cgit v1.2.1 From f60cb60fc61cf2e0c99f989785e930f83024509c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 11 Sep 2009 20:19:21 +0000 Subject: point to the current functions, not the deprecated ones --- docs/libcurl/curl_multi_setopt.3 | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index da4a8d367..2cf468314 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -20,14 +20,14 @@ You can only set one option in each function call. .SH OPTIONS .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 -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 -is NULL, no callback will be called. Set the callback's \fBuserp\fP argument -with \fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more -callback details. +prototype. The \fIcurl_multi_socket_action(3)\fP function informs the +application 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 is NULL, no callback will be called. Set the callback's \fBuserp\fP +argument with \fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for +more callback details. .IP CURLMOPT_SOCKETDATA Pass a pointer to whatever you want passed to the \fBcurl_socket_callback\fP's forth argument, the userp pointer. This is not used by libcurl but only @@ -45,13 +45,13 @@ Pass a pointer to a function matching the \fBcurl_multi_timer_callback\fP prototype. This function will then be called when the timeout value changes. The timeout value is at what latest time the application should call one of the \&"performing" functions of the multi interface -(\fIcurl_multi_socket(3)\fP, \fIcurl_multi_socket_all(3)\fP and -\fIcurl_multi_perform(3)\fP) - to allow libcurl to keep timeouts and retries -etc to work. A timeout value of -1 means that there is no timeout at all, and -0 means that the timeout is already reached. Libcurl attempts to limit calling -this only when the fixed future timeout time actually changes. See also -\fICURLMOPT_TIMERDATA\fP. This callback can be used instead of, or in addition -to, \fIcurl_multi_timeout(3)\fP. (Added in 7.16.0) +(\fIcurl_multi_socket_action(3)\fP and \fIcurl_multi_perform(3)\fP) - to allow +libcurl to keep timeouts and retries etc to work. A timeout value of -1 means +that there is no timeout at all, and 0 means that the timeout is already +reached. Libcurl attempts to limit calling this only when the fixed future +timeout time actually changes. See also \fICURLMOPT_TIMERDATA\fP. This +callback can be used instead of, or in addition to, +\fIcurl_multi_timeout(3)\fP. (Added in 7.16.0) .IP CURLMOPT_TIMERDATA Pass a pointer to whatever you want passed to the \fBcurl_multi_timer_callback\fP's third argument, the userp pointer. This is -- cgit v1.2.1 From b3e8cf539d0105c2d1cbcab6b0090d3d034fd8ae Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 11 Nov 2009 14:54:45 +0000 Subject: NSS SSL connections are also blocking --- docs/libcurl/libcurl-multi.3 | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 17041f576..df4416f3f 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -134,6 +134,7 @@ the future, you should be aware of the following current restrictions: .nf - Name resolves on non-windows unless c-ares is used - GnuTLS SSL connections + - NSS SSL connections - Active FTP connections - HTTP proxy CONNECT operations - SOCKS proxy handshakes -- cgit v1.2.1 From c80b593e5b3ba60279dbbbcfffc5b5b62a35a75e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Nov 2009 09:31:55 +0000 Subject: fixed CURLOPT_TFTP_BLKSIZE typo --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 40447caa9..ed6f1642a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1054,7 +1054,7 @@ transfer decoding will be disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. (added in 7.16.2) .SH TFTP OPTIONS -.IP CURLOPT_TFTPBLKSIZE +.IP CURLOPT_TFTP_BLKSIZE Specify block size to use for TFTP data transmission. Valid range as per RFC 2348 is 8-65464 bytes. The default of 512 bytes will be used if this option is not specified. The specified block size will only be used pending support by -- cgit v1.2.1 From e20f3ecd7e00944c59dd3bd6dfbe7d4876b0df21 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 24 Nov 2009 10:10:59 +0000 Subject: clarify what a modern version of libcurl means --- docs/libcurl/curl_multi_socket_action.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index 5287b44c3..cc53dbbb0 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -95,13 +95,13 @@ for more actions on libcurl's sockets. 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". -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. +In modern libcurls (from around 7.19.0 or later), +\fICURLM_CALL_MULTI_PERFORM\fP or \fICURLM_CALL_MULTI_SOKCET\fP will not be +returned and no application needs to care about them. -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. +NOTE that the return code from this function 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 -- cgit v1.2.1 From b6ac8d62a1f020bd55cde971250bd4e677ce5248 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 26 Dec 2009 18:42:25 +0000 Subject: symbols added in the CVS version meant for 7.20.0 --- docs/libcurl/symbols-in-versions | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 1b53eeaf7..7b6ec3064 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -259,6 +259,8 @@ CURLOPT_LOCALPORT 7.15.2 CURLOPT_LOCALPORTRANGE 7.15.2 CURLOPT_LOW_SPEED_LIMIT 7.1 CURLOPT_LOW_SPEED_TIME 7.1 +CURLOPT_MAIL_FROM 7.20.0 +CURLOPT_MAIL_RCPT 7.20.0 CURLOPT_MAXCONNECTS 7.7 CURLOPT_MAXFILESIZE 7.10.8 CURLOPT_MAXFILESIZE_LARGE 7.11.0 @@ -374,10 +376,16 @@ CURLPROTO_FTP 7.19.4 CURLPROTO_FTPS 7.19.4 CURLPROTO_HTTP 7.19.4 CURLPROTO_HTTPS 7.19.4 +CURLPROTO_IMAP 7.20.0 +CURLPROTO_IMAPS 7.20.0 CURLPROTO_LDAP 7.19.4 CURLPROTO_LDAPS 7.19.4 +CURLPROTO_POP3 7.20.0 +CURLPROTO_POP3S 7.20.0 CURLPROTO_SCP 7.19.4 CURLPROTO_SFTP 7.19.4 +CURLPROTO_SMTP 7.20.0 +CURLPROTO_SMTPS 7.20.0 CURLPROTO_TELNET 7.19.4 CURLPROTO_TFTP 7.19.4 CURLPROXY_HTTP 7.10 -- cgit v1.2.1 From 1bd5784a1386513e0a1cc7c8f28e0e8368421f67 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 27 Dec 2009 20:54:26 +0000 Subject: Julien Chaffraix's clarifications --- docs/libcurl/curl_multi_fdset.3 | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 7e54dfeac..9b06a3c08 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -21,6 +21,11 @@ but be sure to FD_ZERO them before calling this function as 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. +To be sure to have up-to-date results, you should call +\fIcurl_multi_perform\fP until it does not return CURLM_CALL_MULTI_PERFORM +prior to calling \fIcurl_multi_fdset\fP. This will make sure that libcurl has +updated the handles' socket states. + 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 libcurl set. @@ -37,5 +42,5 @@ figure out how long to wait for action. CURLMcode type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP .SH "SEE ALSO" -.BR curl_multi_cleanup "(3)," curl_multi_init "(3), " -.BR curl_multi_timeout "(3) " +.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " +.BR curl_multi_timeout "(3), " curl_multi_perform "(3) " -- cgit v1.2.1 From 97141d08f71c82062fb619e5272090b08841c92a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 30 Dec 2009 23:14:30 +0000 Subject: CURLOPT_HEADERDATA was added in 7.10 --- docs/libcurl/symbols-in-versions | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 7b6ec3064..c2d4521d6 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -232,6 +232,7 @@ CURLOPT_FTP_SSL_CCC 7.16.1 CURLOPT_FTP_USE_EPRT 7.10.5 CURLOPT_FTP_USE_EPSV 7.9.2 CURLOPT_HEADER 7.1 +CURLOPT_HEADERDATA 7.10 CURLOPT_HEADERFUNCTION 7.7.2 CURLOPT_HTTP200ALIASES 7.10.3 CURLOPT_HTTPAUTH 7.10.6 -- cgit v1.2.1 From 42d365f199f9637820de4ecdee21bc7d4668f138 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 31 Dec 2009 22:38:10 +0000 Subject: added descriptions for CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT --- docs/libcurl/curl_easy_setopt.3 | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ed6f1642a..697d49b0e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1053,6 +1053,19 @@ Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. (added in 7.16.2) +.SH SMTP OPTIONS +.IP CURLOPT_MAIL_FROM +Pass a pointer to a zero terminated string as parameter. It will be used to +specify the sender address in a mail when sending an SMTP mail with libcurl. + +(Added in 7.20.0) +.IP CURLOPT_MAIL_RCPT +Pass a pointer to a linked list of recipients to pass to the server in your +SMTP mail request. The linked list should be a fully valid list of \fBstruct +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. + +(Added in 7.20.0) .SH TFTP OPTIONS .IP CURLOPT_TFTP_BLKSIZE Specify block size to use for TFTP data transmission. Valid range as per RFC -- cgit v1.2.1 From 605bbfc4c0fa838f50bf9d18e69e417168f524c0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 1 Jan 2010 14:44:44 +0000 Subject: - Ingmar Runge enhanced libcurl's FTP engine to support the PRET command. This command is a special "hack" used by the drftpd server, but even though it is a custom extension I've deemed it fine to add to libcurl since this server seems to survive and people keep using it and want libcurl to support it. The new libcurl option is named CURLOPT_FTP_USE_PRET, and it is also usable from the curl tool with --ftp-pret. Using this option on a server that doesn't support this command will make libcurl fail. --- docs/libcurl/curl_easy_setopt.3 | 6 ++++++ docs/libcurl/libcurl-errors.3 | 4 ++++ 2 files changed, 10 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 697d49b0e..7377ef3ee 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1160,6 +1160,12 @@ means that it will first attempt to use EPSV before using PASV, but if you pass zero to this option, it will not try using EPSV, only plain PASV. If the server is an IPv6 host, this option will have no effect as of 7.12.3. +.IP CURLOPT_FTP_USE_PRET +Pass a long. If the value is 1, it tells curl to send a PRET command +before PASV (and EPSV). Certain FTP servers, mainly drftpd, require this +non-standard command for directory listings as well as up and downloads in +PASV mode. Has no effect when using the active FTP transfers mode. +(Added in 7.20.x) .IP CURLOPT_FTP_CREATE_MISSING_DIRS Pass a long. If the value is 1, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 6a3d74ac6..7447996f4 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -70,6 +70,10 @@ either a PASV or a EPSV command. The server is flawed. .IP "CURLE_FTP_WEIRD_227_FORMAT (14)" FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back. +.IP "CURLE_FTP_PRET_FAILED (84)" +The FTP server does not understand the PRET command at all or does not +support the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST\fP, +a custom LIST command will be sent with PRET CMD before PASV as well. .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)" -- cgit v1.2.1 From 241c0ad5bdb1178f460963671f972d7e2bbb9015 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 1 Jan 2010 14:52:12 +0000 Subject: added CURLOPT_FTP_USE_PRET --- docs/libcurl/symbols-in-versions | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index c2d4521d6..448d2d21d 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -231,6 +231,7 @@ CURLOPT_FTP_SSL 7.11.0 7.16.4 CURLOPT_FTP_SSL_CCC 7.16.1 CURLOPT_FTP_USE_EPRT 7.10.5 CURLOPT_FTP_USE_EPSV 7.9.2 +CURLOPT_FTP_USE_PRET 7.20.0 CURLOPT_HEADER 7.1 CURLOPT_HEADERDATA 7.10 CURLOPT_HEADERFUNCTION 7.7.2 -- cgit v1.2.1 From a62f32d3c2012a4e2e48dac3d9ec780733c4a844 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 1 Jan 2010 14:52:50 +0000 Subject: update copyright year since we are in 2010 now --- docs/libcurl/curl_easy_setopt.3 | 13 ++++++------- docs/libcurl/libcurl-errors.3 | 11 ++++++----- 2 files changed, 12 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7377ef3ee..97baa359a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "11 Dec 2008" "libcurl 7.19.3" "libcurl Manual" +.TH curl_easy_setopt 3 "1 Jan 2010" "libcurl 7.20.0" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -1161,11 +1161,10 @@ pass zero to this option, it will not try using EPSV, only plain PASV. If the server is an IPv6 host, this option will have no effect as of 7.12.3. .IP CURLOPT_FTP_USE_PRET -Pass a long. If the value is 1, it tells curl to send a PRET command -before PASV (and EPSV). Certain FTP servers, mainly drftpd, require this -non-standard command for directory listings as well as up and downloads in -PASV mode. Has no effect when using the active FTP transfers mode. -(Added in 7.20.x) +Pass a long. If the value is 1, it tells curl to send a PRET command before +PASV (and EPSV). Certain FTP servers, mainly drftpd, require this non-standard +command for directory listings as well as up and downloads in PASV mode. Has +no effect when using the active FTP transfers mode. (Added in 7.20.0) .IP CURLOPT_FTP_CREATE_MISSING_DIRS Pass a long. If the value is 1, curl will attempt to create any remote directory that it fails to CWD into. CWD is the command that changes working diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 7447996f4..6ffb71238 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH libcurl-errors 3 "8 Jun 2008" "libcurl 7.19.0" "libcurl errors" +.TH libcurl-errors 3 "1 Jan 2010" "libcurl 7.20.0" "libcurl errors" .SH NAME libcurl-errors \- error codes in libcurl .SH DESCRIPTION @@ -71,9 +71,10 @@ either a PASV or a EPSV command. The server is flawed. FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back. .IP "CURLE_FTP_PRET_FAILED (84)" -The FTP server does not understand the PRET command at all or does not -support the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST\fP, -a custom LIST command will be sent with PRET CMD before PASV as well. +The FTP server does not understand the PRET command at all or does not support +the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST\fP, a +custom LIST command will be sent with PRET CMD before PASV as well. (Added in +7.20.0) .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)" -- cgit v1.2.1 From 9bd03483ce6983852d41f5f69cb74827c9defc26 Mon Sep 17 00:00:00 2001 From: Claes Jakobsson Date: Wed, 6 Jan 2010 16:01:48 +0000 Subject: Julien Chaffraix fixed so that the fragment part in an URL is not sent to the server anymore --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 97baa359a..dd1a38ae4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -449,6 +449,9 @@ on which protocols are supported. The string given to CURLOPT_URL must be url-encoded and follow RFC 2396 (http://curl.haxx.se/rfc/rfc2396.txt). +Please note that starting with version 7.20.0, the fragment part of the URI will +not be send as part of the path, which was the case previously. + \fICURLOPT_URL\fP is the only option that \fBmust\fP be set before \fIcurl_easy_perform(3)\fP is called. -- cgit v1.2.1 From bc4582b68a673d3b0f5a2e7d971605de2c8b3730 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 21 Jan 2010 13:58:30 +0000 Subject: Chris Conroy brought support for RTSP transfers, and with it comes 8(!) new libcurl options for controlling what to get and how to receive posssibly interleaved RTP data. Initial commit. --- docs/libcurl/curl_easy_getinfo.3 | 22 ++++++ docs/libcurl/curl_easy_setopt.3 | 145 +++++++++++++++++++++++++++++++++++++-- docs/libcurl/libcurl.m4 | 3 +- 3 files changed, 164 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index e227f0790..91fb9a760 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -209,6 +209,28 @@ the previous request didn't match (see \fICURLOPT_TIMECONDITION\fP). Alas, if this returns a 1 you know that the reason you didn't get data in return is because it didn't fulfill the condition. The long ths argument points to will get a zero stored if the condition instead was met. (Added in 7.19.4) +.IP CURLINFO_RTSP_SESSION_ID +Pass a pointer to a char pointer to receive a pointer to a string holding the +most recent RTSP Session ID. + +Applications wishing to resume an RTSP session on another connection should +retreive this info before closing the active connection. +.IP CURLINFO_RTSP_CLIENT_CSEQ +Pass a pointer to a long to receive the next CSeq that will be used by the +application. +.IP CURLINFO_RTSP_SERVER_CSEQ +Pass a pointer to a long to receive the next server CSeq that will be expected +by the application. + +\fI(NOTE: listening for server initiated requests is currently +unimplemented).\fP + +Applications wishing to resume an RTSP session on another connection should +retreive this info before closing the active connection. +.IP CURLINFO_RTSP_CSEQ_RECV +Pass a pointer to a long to receive the most recently received CSeq from the +server. If your application encounters a \fICURLE_RTSP_CSEQ_ERROR\fP then you +may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this value. .SH TIMES .nf An overview of the six time values available from curl_easy_getinfo() diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index dd1a38ae4..f577f5cd0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -401,6 +401,34 @@ follows: You will need to override these definitions if they are different on your system. +.IP CURLOPT_RTPFUNCTION +Function pointer that should match the following prototype: \fIsize_t +function( void *ptr, size_t size, size_t nmemb, void *stream)\fP. This +function gets called by libcurl as soon as it has received interleaved RTP +data. This function gets called for each $ block and therefore contains +exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the +interleaved header as well as the included data for each call. The first byte +is always an ASCII dollar sign. The dollar sign is followed by a one byte +channel identifier and then a 2 byte integer length in network byte order. See +\fIRFC 2326 Section 10.12\fP for more information on how RTP interleaving +behaves. + +Interleaved RTP poses some challeneges for the client application. Since the +stream data is sharing the RTSP control connection, it is critical to service +the RTP in a timely fashion. If the RTP data is not handled quickly, +subsequent response processing may become unreasonably delayed and the +connection may close. The application may use \fICURL_RTSPREQ_RECEIVE\fP to +service RTP data when no requests are desired. If the application makes a +request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler will +process any pending RTP data before marking the request as finished. (Added +in 7.20.0) +.IP CURLOPT_RTPDATA +This is the stream that will be passed to \fICURLOPT_RTPFUNCTION\fP when +interleaved RTP data is received. Since the application is required to provide +a custom function for RTP data, there is no requirement that the stream +pointer be a valid FILE pointer. An application may wish to pass a cookie +containing information about many streams to assist in demultiplexing the +different RTP channels. (Added in 7.20.0) .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error @@ -1275,6 +1303,107 @@ file \&"normally" (like in the multicwd case). This is somewhat more standards compliant than 'nocwd' but without the full penalty of 'multicwd'. .RE (Added in 7.15.1) +.SH RTSP OPTIONS +.IP CURLOPT_RTSP_REQUEST +Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP +enum values. Unless noted otherwise, commands require the Session ID to be +initialized. (Added in 7.20.0) +.RS +.IP CURL_RTSPREQ_OPTIONS +Used to retrieve the available methods of the server. The application is +responsbile for parsing and obeying the response. \fB(The session ID is not +needed for this method.)\fP (Added in 7.20.0) +.IP CURL_RTSPREQ_DESCRIBE +Used to get the low level description of a stream. The application should note +what formats it understands in the \fI'Accept:'\fP header. Unless set +manually, libcurl will automatically fill in \fI'Accept: +application/sdp'\fP. Time-condition headers will be added to Describe requests +if the \fICURLOPT_TIMECONDITION\fP option is active. \fB(The session ID is not +needed for this method)\fP (Added in 7.20.0) +.IP CURL_RTSPREQ_ANNOUNCE +When sent by a client, this method changes the description of the session. For +example, if a client is using the server to record a meeting, the client can +use Announce to inform the server of all the meta-information about the +session. ANNOUNCE acts like an HTTP PUT or POST just like +\fICURL_RTSPREQ_SET_PARAMETER\fP (Added in 7.20.0) +.IP CURL_RTSPREQ_SETUP +Setup is used to initialize the transport layer for the session. The +application must set the desired Transport options for a session by using the +\fICURLOPT_RTSP_TRANSPORT\fP option prior to calling setup. If no session ID +is currently set with \fICURLOPT_RTSP_SESSION_ID\fP, libcurl will extract and +use the session ID in the response to this request. \fB(The session ID is not +needed for this method).\fP (Added in 7.20.0) +.IP CURL_RTSPREQ_PLAY +Send a Play command to the server. Use the \fICURLOPT_RANGE\fP option to +modify the playback time (e.g. 'npt=10-15'). (Added in 7.20.0) +.IP CURL_RTSPREQ_PAUSE +Send a Pause command to the server. Use the \fICURLOPT_RANGE\fP option with a +single value to indicate when the stream should be halted. (e.g. npt='25') +(Added in 7.20.0) +.IP CURL_RTSPREQ_TEARDOWN +This command terminates an RTSP session. Note that simply closing a connection +does not terminate the RTSP session since it is valid to control an RTSP +session over different connections. (Added in 7.20.0) +.IP CURL_RTSPREQ_GET_PARAMETER +Retrieve a parameter from the server. By default, libcurl will automatically +include an \fIAccept: text/parameters\fP header unless a custom one is set. +Applications wishing to send a heartbeat message (e.g. in the presence of a +server-specified timeout) should send use an empty GET_PARAMETER request. +(Added in 7.20.0) +.IP CURL_RTSPREQ_SET_PARAMETER +Set a parameter on the server. By default, libcurl will automatically include +a \fIContent-Type: text/parameters\fP header unless a custom one is set. The +interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application +may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like an HTTP +PUT, or it may use \fICURLOPT_POSTFIELDS\fP like an HTTP POST. Note that no +chunked transfers are allowed, so the application must set the +\fICURLOPT_INFILESIZE\fP in the former and \fICURLOPT_POSTFIELDSIZE\fP in the +latter. Also, there is no use of multi-part POSTs within RTSP. (Added in +7.20.0) +.IP CURL_RTSPREQ_RECORD +Used to tell the server to record a session. Use the \fICURLOPT_RANGE\fP +option to modify the record time. (Added in 7.20.0) +.IP CURL_RTSPREQ_RECEIVE +This is a special request because it does not send any data to the server. The +application may call this function in order to receive interleaved RTP +data. It will return after processing one read buffer of data in order to give +the application a chance to run. (Added in 7.20.0) +.RE +.IP CURLOPT_RTSP_SESSION_ID +Pass a char * as a parameter to set the value of the current RTSP Session ID +for the handle. Useful for resuming an in-progress session. Once this value is +set to any non-NULL value, libcurl will return \fICURLE_RTSP_SESSION_ERROR\fP +if ID received from the server does not match. If unset (or set to NULL), +libcurl will automatically set the ID the first time the server sets it in a +response. (Added in 7.20.0) +.IP CURLOPT_RTSP_STREAM_URI +Set the stream URI to operate on by passing a char * . For example, a single +session may be controlling \fIrtsp://foo/twister/audio\fP and +\fIrtsp://foo/twister/video\fP and the application can switch to the +appropriate stream using this option. If unset, libcurl will default to +operating on generic server options by passing '*' in the place of the RTSP +Stream URI. Note that this option is distinct from \fICURLOPT_URL\fP. When +working with RTSP, the \fICURLOPT_STREAM_URI\fP indicates what URL to send to +the server in the request header while the \fICURLOPT_URL\fP indicates where +to make the connection to. (e.g. the \fICURLOPT_URL\fP for the above examples +might be set to \fIrtsp://foo/twister\fP (Added in 7.20.0) +.IP CURLOPT_RTSP_TRANSPORT +Pass a char * to tell libcurl what to pass for the Transport: header for this +RTSP session. This is mainly a convenience method to avoid needing to set a +custom Transport: header for every SETUP request. The application must set a +Transport: header before issuing a SETUP request. (Added in 7.20.0) +.IP CURLOPT_RTSP_HEADER +This option is simply an alias for \fICURLOPT_HTTP_HEADER\fP. Use this to +replace the standard headers that RTSP and HTTP share. It is also valid to use +the shortcuts such as \fICURLOPT_USERAGENT\fP. (Added in 7.20.0) +.IP CURLOPT_RTSP_CLIENT_CSEQ +Manually set the the CSEQ number to issue for the next RTSP request. Useful if +the application is resuming a previously broken connection. The CSEQ will +increment from this new number henceforth. (Added in 7.20.0) +.IP CURLOPT_RTSP_SERVER_CSEQ +Manually set the CSEQ number to expect for the next RTSP Server->Client +request. At the moment, this feature (listening for Server requests) is +unimplemented. (Added in 7.20.0) .SH PROTOCOL OPTIONS .IP CURLOPT_TRANSFERTEXT A parameter set to 1 tells the library to use ASCII mode for FTP transfers, @@ -1301,9 +1430,14 @@ want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in \fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation -techniques). Pass a NULL to this option to disable the use of ranges. +techniques). For RTSP, the formatting of a range should follow RFC 2326 Section +12.29. Note that for RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges +should be given in npt, utc, or smpte formats. + +Pass a NULL to this option to disable the use of ranges. -Ranges work on HTTP, FTP and FILE (since 7.18.0) transfers only. +Ranges work on HTTP, FTP, FILE (since 7.18.0), and RTSP (since 7.20.0) +transfers only. .IP CURLOPT_RESUME_FROM Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. Set this option to 0 to make the transfer @@ -1408,7 +1542,8 @@ given limit. This concerns both FTP and HTTP transfers. .IP CURLOPT_TIMECONDITION Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time 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. +or \fICURL_TIMECOND_IFUNMODSINCE\fP. This feature applies to HTTP, FTP, and +RTSP. 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 not @@ -1629,8 +1764,8 @@ 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 needs to enforce that the peer certificate is -from a specific branch of the tree. +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 \fICURLOPT_SSL_VERIFYPEER\fP option. Otherwise, the result of the check is not diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index f54a5f2d1..74299b8fa 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -55,6 +55,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], AH_TEMPLATE([LIBCURL_PROTOCOL_LDAP],[Defined if libcurl supports LDAP]) AH_TEMPLATE([LIBCURL_PROTOCOL_DICT],[Defined if libcurl supports DICT]) AH_TEMPLATE([LIBCURL_PROTOCOL_TFTP],[Defined if libcurl supports TFTP]) + AH_TEMPLATE([LIBCURL_PROTOCOL_RTSP],[Defined if libcurl supports RTSP]) AC_ARG_WITH(libcurl, AC_HELP_STRING([--with-libcurl=DIR],[look for the curl library in DIR]), @@ -194,7 +195,7 @@ x=CURLOPT_VERBOSE; # We don't have --protocols, so just assume that all # protocols are available - _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT" + _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP RTSP" if test x$libcurl_feature_SSL = xyes ; then _libcurl_protocols="$_libcurl_protocols HTTPS" -- cgit v1.2.1 From 4a8570313aa22d9d1b78e1e4d8ce01239a2021c7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 22 Jan 2010 09:19:10 +0000 Subject: keep lines shorter than 80 columns, and reduce/remove the use of the word 'note' in most description as it is mostly useless. --- docs/libcurl/curl_easy_setopt.3 | 127 ++++++++++++++++++++-------------------- 1 file changed, 63 insertions(+), 64 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f577f5cd0..d668085e5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -49,8 +49,8 @@ thus the string storage associated to the pointer argument may be overwritten after curl_easy_setopt() returns. Exceptions to this rule are described in the option details below. -NOTE: before 7.17.0 strings were not copied. Instead the user was forced keep -them available until libcurl no longer needed them. +Before version 7.17.0, strings were not copied. Instead the user was forced +keep them available until libcurl no longer needed them. The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. @@ -347,9 +347,9 @@ 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. 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 +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 and trust file settings. .IP CURLOPT_SSL_CTX_DATA @@ -477,8 +477,8 @@ on which protocols are supported. The string given to CURLOPT_URL must be url-encoded and follow RFC 2396 (http://curl.haxx.se/rfc/rfc2396.txt). -Please note that starting with version 7.20.0, the fragment part of the URI will -not be send as part of the path, which was the case previously. +Starting with version 7.20.0, the fragment part of the URI will not be send as +part of the path, which was the case previously. \fICURLOPT_URL\fP is the only option that \fBmust\fP be set before \fIcurl_easy_perform(3)\fP is called. @@ -568,23 +568,23 @@ name. 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 the only valid port numbers are 1 - 65535. (Added in 7.15.2) +set. Valid port numbers are 1 - 65535. (Added in 7.15.2) .IP CURLOPT_LOCALPORTRANGE Pass a long. This is the number of attempts libcurl should make to find a 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 -by nature are scarce resources that will be busy at times so setting this -value to something too low might cause unnecessary connection setup -failures. (Added in 7.15.2) +make libcurl do only one try for the exact port number. Port numbers by nature +are scarce resources that will be busy at times so setting this value to +something too low might cause unnecessary connection setup failures. (Added in +7.15.2) .IP CURLOPT_DNS_CACHE_TIMEOUT Pass a long, this sets the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero to completely disable 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 (for example, by calling +The name resolve functions of various libc implementations don't re-read 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. @@ -705,12 +705,12 @@ 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 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. +\fICURLOPT_PROXYUSERPWD\fP is used. In comparison to +\fICURLOPT_PROXYUSERPWD\fP the CURLOPT_PROXYUSERNAME allows the username to +contain a colon, like in the following example: "sip:user@example.com". 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. In order to specify the password to be used in conjunction with the user name use the \fICURLOPT_PROXYPASSWORD\fP option. (Added in 7.19.1) @@ -767,8 +767,8 @@ it finds suitable. libcurl will automatically select the one it finds most secure. .IP CURLAUTH_ANYSAFE This is a convenience macro that sets all bits except Basic and thus makes -libcurl pick any it finds suitable. libcurl will automatically select the one it -finds most secure. +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 which @@ -806,7 +806,7 @@ and follow new Location: headers all the way until no more such headers are returned. \fICURLOPT_MAXREDIRS\fP can be used to limit the number of redirects libcurl will follow. -NOTE: since 7.19.4, libcurl can limit to what protocols it will automatically +Since 7.19.4, libcurl can limit what protocols it will automatically follow. The accepted protocols are set with \fICURLOPT_REDIR_PROTOCOLS\fP and it excludes the FILE protocol by default. .IP CURLOPT_UNRESTRICTED_AUTH @@ -882,7 +882,7 @@ re-used handle, you must explicitly set the new request type using Pass a void * as parameter, which should be the full data to post in an HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most -web servers will assume this data to be url-encoded. Take note. +web servers will assume this data to be url-encoded. The pointed data are NOT copied by the library: as a consequence, they must be preserved by the calling application until the transfer finishes. @@ -1001,9 +1001,9 @@ option and thus you need to concatenate them all in one single string. Set multiple cookies in one string like this: "name1=content1; name2=content2;" etc. -Note that this option sets the cookie header explictly in the outgoing -request(s). If multiple requests are done due to authentication, followed -redirections or similar, they will all get this cookie passed on. +This option sets the cookie header explictly in the outgoing request(s). If +multiple requests are done due to authentication, followed redirections or +similar, they will all get this cookie passed on. Using this option multiple times will only make the latest string override the previous ones. @@ -1076,9 +1076,9 @@ progress, and will simply stop the download when the server ends the connection. (added in 7.14.1) .IP CURLOPT_HTTP_CONTENT_DECODING Pass a long to tell libcurl how to act on content decoding. If set to zero, -content decoding will be disabled. If set to 1 it is enabled. Note however -that libcurl has no default content decoding but requires you to use -\fICURLOPT_ENCODING\fP for that. (added in 7.16.2) +content decoding will be disabled. If set to 1 it is enabled. Libcurl has no +default content decoding but requires you to use \fICURLOPT_ENCODING\fP for +that. (added in 7.16.2) .IP CURLOPT_HTTP_TRANSFER_DECODING Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding will be disabled, if set to 1 it is enabled @@ -1341,9 +1341,9 @@ Send a Pause command to the server. Use the \fICURLOPT_RANGE\fP option with a single value to indicate when the stream should be halted. (e.g. npt='25') (Added in 7.20.0) .IP CURL_RTSPREQ_TEARDOWN -This command terminates an RTSP session. Note that simply closing a connection -does not terminate the RTSP session since it is valid to control an RTSP -session over different connections. (Added in 7.20.0) +This command terminates an RTSP session. Simply closing a connection does not +terminate the RTSP session since it is valid to control an RTSP session over +different connections. (Added in 7.20.0) .IP CURL_RTSPREQ_GET_PARAMETER Retrieve a parameter from the server. By default, libcurl will automatically include an \fIAccept: text/parameters\fP header unless a custom one is set. @@ -1355,8 +1355,8 @@ Set a parameter on the server. By default, libcurl will automatically include a \fIContent-Type: text/parameters\fP header unless a custom one is set. The interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like an HTTP -PUT, or it may use \fICURLOPT_POSTFIELDS\fP like an HTTP POST. Note that no -chunked transfers are allowed, so the application must set the +PUT, or it may use \fICURLOPT_POSTFIELDS\fP like an HTTP POST. No chunked +transfers are allowed, so the application must set the \fICURLOPT_INFILESIZE\fP in the former and \fICURLOPT_POSTFIELDSIZE\fP in the latter. Also, there is no use of multi-part POSTs within RTSP. (Added in 7.20.0) @@ -1382,11 +1382,11 @@ session may be controlling \fIrtsp://foo/twister/audio\fP and \fIrtsp://foo/twister/video\fP and the application can switch to the appropriate stream using this option. If unset, libcurl will default to operating on generic server options by passing '*' in the place of the RTSP -Stream URI. Note that this option is distinct from \fICURLOPT_URL\fP. When -working with RTSP, the \fICURLOPT_STREAM_URI\fP indicates what URL to send to -the server in the request header while the \fICURLOPT_URL\fP indicates where -to make the connection to. (e.g. the \fICURLOPT_URL\fP for the above examples -might be set to \fIrtsp://foo/twister\fP (Added in 7.20.0) +Stream URI. This option is distinct from \fICURLOPT_URL\fP. When working with +RTSP, the \fICURLOPT_STREAM_URI\fP indicates what URL to send to the server in +the request header while the \fICURLOPT_URL\fP indicates where to make the +connection to. (e.g. the \fICURLOPT_URL\fP for the above examples might be +set to \fIrtsp://foo/twister\fP (Added in 7.20.0) .IP CURLOPT_RTSP_TRANSPORT Pass a char * to tell libcurl what to pass for the Transport: header for this RTSP session. This is mainly a convenience method to avoid needing to set a @@ -1430,8 +1430,8 @@ want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in \fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation -techniques). For RTSP, the formatting of a range should follow RFC 2326 Section -12.29. Note that for RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges +techniques). For RTSP, the formatting of a range should follow RFC 2326 +Section 12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in npt, utc, or smpte formats. Pass a NULL to this option to disable the use of ranges. @@ -1496,8 +1496,8 @@ as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE\fP is mandatory. -Note that this option does not limit how much data libcurl will actually send, -as that is controlled entirely by what the read callback returns. +This option does not limit how much data libcurl will actually send, as that +is controlled entirely by what the read callback returns. .IP CURLOPT_INFILESIZE_LARGE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed @@ -1505,8 +1505,8 @@ as a curl_off_t. (Added in 7.11.0) For uploading using SCP, this option or \fICURLOPT_INFILESIZE\fP is mandatory. -Note that this option does not limit how much data libcurl will actually send, -as that is controlled entirely by what the read callback returns. +This option does not limit how much data libcurl will actually send, as that +is controlled entirely by what the read callback returns. .IP CURLOPT_UPLOAD A parameter set to 1 tells the library to prepare for an upload. The \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP or @@ -1603,9 +1603,9 @@ 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 -acknowledged, and you must instead use \fIcurl_multi_setopt(3)\fP and -the \fICURLMOPT_MAXCONNECTS\fP option. +If you add this easy handle to a multi handle, this setting is not +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. .IP CURLOPT_FRESH_CONNECT @@ -1705,10 +1705,9 @@ operations. If the crypto device cannot be set, \fICURLE_SSL_ENGINE_SETFAILED\fP is returned. -Note that even though this option doesn't need any parameter, in some -configurations \fIcurl_easy_setopt\fP might be defined as a macro taking -exactly three arguments. Therefore, it's recommended to pass 1 as parameter to -this option. +Even though this option doesn't need any parameter, in some configurations +\fIcurl_easy_setopt\fP might be defined as a macro taking exactly three +arguments. Therefore, it's recommended to pass 1 as parameter to this option. .IP CURLOPT_SSLVERSION Pass a long as parameter to control what version of SSL/TLS to attempt to use. The available options are: @@ -1754,8 +1753,8 @@ combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If \fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAINFO\fP need not 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. +This 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 database resides in. @@ -1800,8 +1799,8 @@ This option makes sense only when used in combination with the A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. -Note that a failure in certificate verification due to a revocation information -found in the CRL does not trigger this specific error. (Added in 7.19.0) +A failure in certificate verification due to a revocation information 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 @@ -1868,7 +1867,7 @@ You'll find more details about the NSS cipher lists on this URL: .IP CURLOPT_SSL_SESSIONID_CACHE Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set this to 1 to enable it. By default all transfers are done using the -cache. Note that while nothing ever should get hurt by attempting to reuse SSL +cache. While nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0) .IP CURLOPT_KRBLEVEL @@ -1896,9 +1895,9 @@ libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP. (Added in 7.16.1) .IP CURLOPT_SSH_PRIVATE_KEYFILE Pass a char * pointing to a file name for your private key. If not used, -libcurl defaults to using \fB~/.ssh/id_dsa\fP. -If the file is password-protected, set the password with \fICURLOPT_KEYPASSWD\fP. -(Added in 7.16.1) +libcurl defaults to using \fB~/.ssh/id_dsa\fP. If the file is +password-protected, set the password with \fICURLOPT_KEYPASSWD\fP. (Added in +7.16.1) .IP CURLOPT_SSH_KNOWNHOSTS Pass a pointer to a zero terminated string holding the file name of the known_host file to use. The known_hosts file should use the OpenSSH file @@ -1917,9 +1916,9 @@ MUST return one of the following return codes to tell libcurl how to act: .IP CURLKHSTAT_FINE_ADD_TO_FILE The host+key is accepted and libcurl will append it to the known_hosts file before continuing with the connection. This will also add the host+key combo -to the known_host pool kept in memory if it wasn't already present there. Note -that the adding of data to the file is done by completely replacing the file -with a new copy, so the permissions of the file must allow this. +to the known_host pool kept in memory if it wasn't already present there. The +adding of data to the file is done by completely replacing the file with a new +copy, so the permissions of the file must allow this. .IP CURLKHSTAT_FINE The host+key is accepted libcurl will continue with the connection. This will also add the host+key combo to the known_host pool kept in memory if it wasn't -- cgit v1.2.1 From 844c19cc5b5a62e572f4fb9e00c5c6a61c2fb581 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 22 Jan 2010 12:17:03 +0000 Subject: s/RTPFUNCTION/INTERLEAVEFUNCTION/ s/RTPDATA/INTERLEAVEDATA/ --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d668085e5..21f4d904d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -401,7 +401,7 @@ follows: You will need to override these definitions if they are different on your system. -.IP CURLOPT_RTPFUNCTION +.IP CURLOPT_INTERLEAVEFUNCTION Function pointer that should match the following prototype: \fIsize_t function( void *ptr, size_t size, size_t nmemb, void *stream)\fP. This function gets called by libcurl as soon as it has received interleaved RTP @@ -422,8 +422,8 @@ service RTP data when no requests are desired. If the application makes a request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler will process any pending RTP data before marking the request as finished. (Added in 7.20.0) -.IP CURLOPT_RTPDATA -This is the stream that will be passed to \fICURLOPT_RTPFUNCTION\fP when +.IP CURLOPT_INTERLEAVEDATA +This is the stream that will be passed to \fICURLOPT_INTERLEAVEFUNCTION\fP when interleaved RTP data is received. Since the application is required to provide a custom function for RTP data, there is no requirement that the stream pointer be a valid FILE pointer. An application may wish to pass a cookie -- cgit v1.2.1 From e45eefcb903b040c2b3705abcc52676332a14e19 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 22 Jan 2010 12:27:38 +0000 Subject: expanded to provide info about the newer protocols too --- docs/libcurl/libcurl.m4 | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 74299b8fa..ce8e476fa 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -56,6 +56,9 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], AH_TEMPLATE([LIBCURL_PROTOCOL_DICT],[Defined if libcurl supports DICT]) AH_TEMPLATE([LIBCURL_PROTOCOL_TFTP],[Defined if libcurl supports TFTP]) AH_TEMPLATE([LIBCURL_PROTOCOL_RTSP],[Defined if libcurl supports RTSP]) + AH_TEMPLATE([LIBCURL_PROTOCOL_POP3],[Defined if libcurl supports POP3]) + AH_TEMPLATE([LIBCURL_PROTOCOL_IMAP],[Defined if libcurl supports IMAP]) + AH_TEMPLATE([LIBCURL_PROTOCOL_SMTP],[Defined if libcurl supports SMTP]) AC_ARG_WITH(libcurl, AC_HELP_STRING([--with-libcurl=DIR],[look for the curl library in DIR]), @@ -195,17 +198,23 @@ x=CURLOPT_VERBOSE; # We don't have --protocols, so just assume that all # protocols are available - _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP RTSP" + _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP if test x$libcurl_feature_SSL = xyes ; then _libcurl_protocols="$_libcurl_protocols HTTPS" # FTPS wasn't standards-compliant until version - # 7.11.0 + # 7.11.0 (0x070b00 == 461568) if test $_libcurl_version -ge 461568; then _libcurl_protocols="$_libcurl_protocols FTPS" fi fi + + # RTSP, IMAP, POP3 and SMTP were added in + # 7.20.0 (0x071400 == 463872) + if test $_libcurl_version -ge 463872; then + _libcurl_protocols="$_libcurl_protocols RTSP IMAP POP3 SMTP" + fi fi for _libcurl_protocol in $_libcurl_protocols ; do -- cgit v1.2.1 From bc253a4d5ff8c744f34d0fa013ec812073253ac3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 22 Jan 2010 13:14:51 +0000 Subject: cleanups by Julien Chaffraix --- docs/libcurl/libcurl-errors.3 | 12 +++++------- docs/libcurl/symbols-in-versions | 7 ++++--- 2 files changed, 9 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 6ffb71238..e11b1f3b7 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -92,15 +92,13 @@ returned an error code that was 400 or higher (for FTP) or otherwise indicated unsuccessful completion of the command. .IP "CURLE_HTTP_RETURNED_ERROR (22)" This is returned if CURLOPT_FAILONERROR is set TRUE and the HTTP server -returns an error code that is >= 400. (This error code was formerly known as -CURLE_HTTP_NOT_FOUND.) +returns an error code that is >= 400. .IP "CURLE_WRITE_ERROR (23)" 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 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. @@ -125,8 +123,9 @@ A problem occurred somewhere in the SSL/TLS handshake. You really want the error buffer and read the message there as it pinpoints the problem slightly more. Could be certificates (file formats, paths, permissions), passwords, and others. -.IP "CURLE_FTP_BAD_DOWNLOAD_RESUME (36)" -Attempting FTP resume beyond file size. +.IP "CURLE_BAD_DOWNLOAD_RESUME (36)" +The download could not be resumed because the specified offset was out of the +file boundary. .IP "CURLE_FILE_COULDNT_READ_FILE (37)" A file given with FILE:// couldn't be opened. Most likely because the file path doesn't identify an existing file. Did you check file permissions? @@ -143,8 +142,7 @@ Internal error. A function was called with a bad parameter. .IP "CURLE_INTERFACE_FAILED (45)" Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections' source IP address with -CURLOPT_INTERFACE. (This error code was formerly known as -CURLE_HTTP_PORT_FAILED.) +CURLOPT_INTERFACE. .IP "CURLE_TOO_MANY_REDIRECTS (47)" Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS. diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 448d2d21d..8cdf511a6 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -37,7 +37,7 @@ CURLE_FAILED_INIT 7.1 CURLE_FILESIZE_EXCEEDED 7.10.8 CURLE_FILE_COULDNT_READ_FILE 7.1 CURLE_FTP_ACCESS_DENIED 7.1 -CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 +CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 7.1 CURLE_FTP_CANT_GET_HOST 7.1 CURLE_FTP_CANT_RECONNECT 7.1 7.17.0 CURLE_FTP_COULDNT_GET_SIZE 7.1 7.17.0 @@ -47,6 +47,7 @@ CURLE_FTP_COULDNT_SET_BINARY 7.1 7.17.0 CURLE_FTP_COULDNT_SET_TYPE 7.17.0 CURLE_FTP_COULDNT_STOR_FILE 7.1 CURLE_FTP_COULDNT_USE_REST 7.1 +CURLE_FTP_PARTIAL_FILE 7.1 7.1 CURLE_FTP_PORT_FAILED 7.1 CURLE_FTP_QUOTE_ERROR 7.1 7.17.0 CURLE_FTP_SSL_FAILED - 7.17.0 @@ -74,7 +75,7 @@ CURLE_OPERATION_TIMEDOUT 7.17.0 CURLE_OPERATION_TIMEOUTED 7.1 7.17.0 CURLE_OUT_OF_MEMORY 7.1 CURLE_PARTIAL_FILE 7.1 -CURLE_PEER_FAILED_VERIFICATION - 7.17.1 +CURLE_PEER_FAILED_VERIFICATION 7.17.1 CURLE_QUOTE_ERROR 7.17.0 CURLE_RANGE_ERROR 7.17.0 CURLE_READ_ERROR 7.1 @@ -93,7 +94,7 @@ CURLE_SSL_ENGINE_INITFAILED 7.13.0 CURLE_SSL_ENGINE_NOTFOUND 7.9.3 CURLE_SSL_ENGINE_SETFAILED 7.9.3 CURLE_SSL_ISSUER_ERROR 7.19.0 -CURLE_SSL_PEER_CERTIFICATE 7.17.1 +CURLE_SSL_PEER_CERTIFICATE - 7.17.1 CURLE_SSL_SHUTDOWN_FAILED 7.16.1 CURLE_TELNET_OPTION_SYNTAX 7.7 CURLE_TFTP_DISKFULL 7.15.0 7.17.0 -- cgit v1.2.1 From 83e91586ef311072c0727bb97efecfeba4294775 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 26 Jan 2010 23:02:13 +0000 Subject: no need to take precautiono for how things were before 7.16.0 since that is now a very long time ago --- docs/libcurl/curl_multi_fdset.3 | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 9b06a3c08..1fdf3dbfd 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -30,14 +30,10 @@ 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 libcurl set. -You should also be aware that when doing select(), you should consider using a -rather small (single-digit number of seconds) timeout and call -\fIcurl_multi_perform\fP regularly - even if no activity has been seen on the -fd_sets - as otherwise libcurl-internal retries and timeouts may not work as -you'd think and want. - -Starting with libcurl 7.16.0, you should use \fBcurl_multi_timeout\fP to -figure out how long to wait for action. +When doing select(), you should use \fBcurl_multi_timeout\fP to figure out how +long to wait for action. Call \fIcurl_multi_perform\fP even if no activity has +been seen on the fd_sets after the timeout expires as otherwise internal +retries and timeouts may not work as you'd think and want. .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP -- cgit v1.2.1 From 2f3bce11939bbd4457d25292e29ffd4b5f891ed9 Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Thu, 28 Jan 2010 01:39:16 +0000 Subject: Chris Conroy's RTSP followup fixes --- docs/libcurl/curl_easy_setopt.3 | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 21f4d904d..b7276af66 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -411,7 +411,7 @@ interleaved header as well as the included data for each call. The first byte is always an ASCII dollar sign. The dollar sign is followed by a one byte channel identifier and then a 2 byte integer length in network byte order. See \fIRFC 2326 Section 10.12\fP for more information on how RTP interleaving -behaves. +behaves. If unset or set to NULL, curl will use the default write function. Interleaved RTP poses some challeneges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service @@ -424,11 +424,7 @@ process any pending RTP data before marking the request as finished. (Added in 7.20.0) .IP CURLOPT_INTERLEAVEDATA This is the stream that will be passed to \fICURLOPT_INTERLEAVEFUNCTION\fP when -interleaved RTP data is received. Since the application is required to provide -a custom function for RTP data, there is no requirement that the stream -pointer be a valid FILE pointer. An application may wish to pass a cookie -containing information about many streams to assist in demultiplexing the -different RTP channels. (Added in 7.20.0) +interleaved RTP data is received. (Added in 7.20.0) .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error -- cgit v1.2.1 From 55f1e787f34cd3d86aa3d6bf981f077de86be265 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 1 Feb 2010 21:42:44 +0000 Subject: We introduce a loop in lib/multi.c around all calls to multi_runsingle() and simply check for CURLM_CALL_MULTI_PERFORM internally. This has the added benefit that this goes in line with my long-term wishes to get rid of the CURLM_CALL_MULTI_PERFORM all together from the public API. --- docs/libcurl/curl_multi_perform.3 | 25 +++++++++++++------------ docs/libcurl/curl_multi_socket_action.3 | 25 +++++++++++-------------- 2 files changed, 24 insertions(+), 26 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 746ff3de0..daf15c478 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -22,25 +22,26 @@ changed from the previous call (or is less than the amount of easy handles you've added to the multi handle), you know that there is one or more transfers less "running". You can then call \fIcurl_multi_info_read(3)\fP to get information about each individual completed transfer, and that returned -info includes CURLcode and more. +info includes CURLcode and more. If an added handle fails very quickly, it may +never be counted as a running_handle. When \fIrunning_handles\fP is set to zero (0) on the return of this function, there is no longer any transfers in progress. .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. -If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you -should call \fIcurl_multi_perform\fP again, before you select() on more -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 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. +Before version 7.20.0: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this +basically means that you should call \fIcurl_multi_perform\fP again, before +you select() on more 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 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. Problems -still might have occurred on individual transfers even when this +This function 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_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index cc53dbbb0..65eef4e3f 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -22,8 +22,8 @@ CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and libcurl will test the descriptor internally. At return, the integer \fBrunning_handles\fP points to will contain the number -of still running easy handles within the multi handle. When this number -reaches zero, all transfers are complete/done. Note that when you call +of running easy handles within the multi handle. When this number reaches +zero, all transfers are complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out @@ -89,19 +89,16 @@ The \fIuserp\fP argument is a private pointer you have previously set with .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. -Legacy: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this basically means -that you should call \fIcurl_multi_socket_action(3)\fP again, before you wait -for more actions on libcurl's sockets. 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". +Before version 7.20.0: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this +basically means that you should call \fIcurl_multi_socket_action(3)\fP again +before you wait for more actions on libcurl's sockets. 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". -In modern libcurls (from around 7.19.0 or later), -\fICURLM_CALL_MULTI_PERFORM\fP or \fICURLM_CALL_MULTI_SOKCET\fP will not be -returned and no application needs to care about them. - -NOTE that the return code from this function is for the whole multi stack. -Problems still might have occurred on individual transfers even when one of -these functions return OK. +The return code from this function 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 -- cgit v1.2.1 From c9f46446d55b0debb92180a02a8bf9bf822bcc20 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 3 Feb 2010 18:18:13 +0000 Subject: more symbols added in 7.20.0 --- docs/libcurl/symbols-in-versions | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 8cdf511a6..549753b7b 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -49,6 +49,7 @@ CURLE_FTP_COULDNT_STOR_FILE 7.1 CURLE_FTP_COULDNT_USE_REST 7.1 CURLE_FTP_PARTIAL_FILE 7.1 7.1 CURLE_FTP_PORT_FAILED 7.1 +CURLE_FTP_PRET_FAILED 7.20.0 CURLE_FTP_QUOTE_ERROR 7.1 7.17.0 CURLE_FTP_SSL_FAILED - 7.17.0 CURLE_FTP_USER_PASSWORD_INCORRECT 7.1 7.17.0 @@ -82,6 +83,8 @@ CURLE_READ_ERROR 7.1 CURLE_RECV_ERROR 7.13.0 CURLE_REMOTE_ACCESS_DENIED 7.17.0 CURLE_REMOTE_DISK_FULL 7.17.0 +CURLE_RTSP_CSEQ_ERROR 7.20.0 +CURLE_RTSP_SESSION_ERROR 7.20.0 CURLE_SEND_ERROR 7.13.0 CURLE_SHARE_IN_USE - 7.17.0 CURLE_SSH 7.16.1 @@ -233,6 +236,14 @@ CURLOPT_FTP_SSL_CCC 7.16.1 CURLOPT_FTP_USE_EPRT 7.10.5 CURLOPT_FTP_USE_EPSV 7.9.2 CURLOPT_FTP_USE_PRET 7.20.0 +CURLOPT_RTSP_REQUEST 7.20.0 +CURLOPT_RTSP_SESSION_ID 7.20.0 +CURLOPT_RTSP_STREAM_URI 7.20.0 +CURLOPT_RTSP_TRANSPORT 7.20.0 +CURLOPT_RTSP_CLIENT_CSEQ 7.20.0 +CURLOPT_RTSP_SERVER_CSEQ 7.20.0 +CURLOPT_INTERLEAVEDATA 7.20.0 +CURLOPT_INTERLEAVEFUNCTION 7.20.0 CURLOPT_HEADER 7.1 CURLOPT_HEADERDATA 7.10 CURLOPT_HEADERFUNCTION 7.7.2 @@ -385,6 +396,7 @@ CURLPROTO_LDAP 7.19.4 CURLPROTO_LDAPS 7.19.4 CURLPROTO_POP3 7.20.0 CURLPROTO_POP3S 7.20.0 +CURLPROTO_RTSP 7.20.0 CURLPROTO_SCP 7.19.4 CURLPROTO_SFTP 7.19.4 CURLPROTO_SMTP 7.20.0 -- cgit v1.2.1 From b4ff6d3007be58423a1e6b8b8aa2e038dd1b04c0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 13 Feb 2010 21:30:16 +0000 Subject: - Martin Hager reported and fixed a problem with a missing quote in libcurl.m4 (http://curl.haxx.se/bug/view.cgi?id=2951319) --- docs/libcurl/libcurl.m4 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index ce8e476fa..50dc20d9f 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -198,7 +198,7 @@ x=CURLOPT_VERBOSE; # We don't have --protocols, so just assume that all # protocols are available - _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP + _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP" if test x$libcurl_feature_SSL = xyes ; then _libcurl_protocols="$_libcurl_protocols HTTPS" -- cgit v1.2.1 From a07bc79117971b96ebf3188c0a34a73ee0a3609b Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Sun, 14 Feb 2010 19:40:18 +0000 Subject: removed trailing whitespace --- docs/libcurl/curl_easy_getinfo.3 | 6 +++--- docs/libcurl/curl_easy_init.3 | 2 +- docs/libcurl/curl_easy_send.3 | 4 ++-- docs/libcurl/curl_easy_setopt.3 | 2 +- docs/libcurl/curl_formadd.3 | 2 +- docs/libcurl/curl_formget.3 | 2 +- docs/libcurl/curl_free.3 | 2 +- docs/libcurl/curl_multi_socket_action.3 | 2 +- docs/libcurl/curl_share_setopt.3 | 2 +- docs/libcurl/libcurl-tutorial.3 | 10 +++++----- docs/libcurl/symbols-in-versions | 2 +- 11 files changed, 18 insertions(+), 18 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 91fb9a760..7859d67c9 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -217,10 +217,10 @@ Applications wishing to resume an RTSP session on another connection should retreive this info before closing the active connection. .IP CURLINFO_RTSP_CLIENT_CSEQ Pass a pointer to a long to receive the next CSeq that will be used by the -application. +application. .IP CURLINFO_RTSP_SERVER_CSEQ Pass a pointer to a long to receive the next server CSeq that will be expected -by the application. +by the application. \fI(NOTE: listening for server initiated requests is currently unimplemented).\fP diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 083633627..9b7ef2f1d 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -14,7 +14,7 @@ handle that you must use as input to other easy-functions. curl_easy_init initializes curl and this call \fBMUST\fP have a corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is complete. -If you did not already call \fIcurl_global_init(3)\fP, +If you did not already call \fIcurl_global_init(3)\fP, \fIcurl_easy_init(3)\fP does it automatically. This may be lethal in multi-threaded cases, since \fIcurl_global_init(3)\fP is not thread-safe, and it may result in resource problems because there is diff --git a/docs/libcurl/curl_easy_send.3 b/docs/libcurl/curl_easy_send.3 index 60a97b29d..30bb7ad1e 100644 --- a/docs/libcurl/curl_easy_send.3 +++ b/docs/libcurl/curl_easy_send.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -23,7 +23,7 @@ .\" .TH curl_easy_send 3 "29 April 2008" "libcurl 7.18.2" "libcurl Manual" .SH NAME -curl_easy_send - sends raw data over an "easy" connection +curl_easy_send - sends raw data over an "easy" connection .SH SYNOPSIS .B #include .sp diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b7276af66..cbbbefe31 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -435,7 +435,7 @@ Therefore the (probably undefined) contents of the buffer is NOT copied by the library. You should keep the associated storage available until libcurl no longer needs it. Failing to do so will cause very odd behavior or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP -or you set the same option again to use a different pointer. +or you set the same option again to use a different pointer. Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better debug/trace why errors happen. diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index cf692ea52..906172227 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -152,7 +152,7 @@ to a CURL_FORMADD_* constant defined in /* Add simple name/content section */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", - CURLFORM_COPYCONTENTS, "content", CURLFORM_END); + CURLFORM_COPYCONTENTS, "content", CURLFORM_END); /* Add simple name/content/contenttype section */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode", diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index 83996cbe0..999208112 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -22,7 +22,7 @@ passed to the curl_formget_callback function. The curl_formget_callback will be executed for each part of the HTTP POST chain. The void *arg pointer will be the one passed as second argument to -curl_formget(). The character buffer passed to it must not be freed. The +curl_formget(). The character buffer passed to it must not be freed. The callback should return the buffer length passed to it on success. .SH RETURN VALUE 0 means everything was ok, non-zero means an error occurred diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 index faa1066d8..447259d4f 100644 --- a/docs/libcurl/curl_free.3 +++ b/docs/libcurl/curl_free.3 @@ -1,6 +1,6 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id: +.\" $Id$ .\" .TH curl_free 3 "12 Aug 2003" "libcurl 7.10" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index 65eef4e3f..c155c7e60 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -7,7 +7,7 @@ curl_multi_socket_action \- reads/writes available data given an action .nf #include -CURLMcode curl_multi_socket_action(CURLM * multi_handle, +CURLMcode curl_multi_socket_action(CURLM * multi_handle, curl_socket_t sockfd, int ev_bitmask, int *running_handles); .fi diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index 43d4b29c4..c3316cd24 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -48,7 +48,7 @@ be used! .RE .IP CURLSHOPT_UNSHARE 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 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 be passed diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 497551633..b435c4bfc 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -273,7 +273,7 @@ GnuTLS http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html NSS - + is claimed to be thread-safe already without anything required. yassl @@ -391,7 +391,7 @@ another option for this, the CURLOPT_PROXYUSERPWD. It is used quite similar to the CURLOPT_USERPWD option like this: curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); - + There's a long time UNIX "standard" way of storing ftp user names and passwords, namely in the $HOME/.netrc file. The file should be made private so that only the user may read it (see also the "Security Considerations" @@ -1200,7 +1200,7 @@ between requests. .IP "Dangerous URLs" SCP URLs can contain raw commands within the scp: URL, which is a side effect -of how the SCP protocol is designed. e.g. +of how the SCP protocol is designed. e.g. scp://user:pass@host/a;date >/tmp/test; Apps must not allow unsanitized SCP: URLs to be passed in for downloads. @@ -1223,7 +1223,7 @@ the CURLOPT_MAXFILESIZE_LARGE option is not sufficient to guard against this. Instead, the app should monitor the amount of data received within the write or progress callback and abort once the limit is reached. -A malicious HTTP server could cause an infinite redirection loop, causing a +A malicious HTTP server could cause an infinite redirection loop, causing a denial-of-service. This can be mitigated by using the CURLOPT_MAXREDIRS option. diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 549753b7b..9cc6e5c0a 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -224,7 +224,7 @@ CURLOPT_FTPAPPEND 7.1 7.16.4 CURLOPT_FTPASCII 7.1 7.11.1 7.15.4 CURLOPT_FTPLISTONLY 7.1 7.16.4 CURLOPT_FTPPORT 7.1 -CURLOPT_FTPSSLAUTH 7.12.2 +CURLOPT_FTPSSLAUTH 7.12.2 CURLOPT_FTP_ACCOUNT 7.13.1 CURLOPT_FTP_ALTERNATIVE_TO_USER 7.15.5 CURLOPT_FTP_CREATE_MISSING_DIRS 7.10.7 -- cgit v1.2.1 From 46b112bcd439f4413925a7300d66a3e6f148765e Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Tue, 16 Feb 2010 13:32:45 +0000 Subject: replaced tabs with spaces --- docs/libcurl/curl_formadd.3 | 4 +- docs/libcurl/libcurl.m4 | 100 ++++++++++++++++++++++---------------------- 2 files changed, 52 insertions(+), 52 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 906172227..90576ba9d 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -165,8 +165,8 @@ to a CURL_FORMADD_* constant defined in /* Add ptrname/ptrcontent section */ curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer, - CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, - namelength, CURLFORM_END); + CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, + namelength, CURLFORM_END); /* Add name/ptrcontent/contenttype section */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole", diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 50dc20d9f..f551e3026 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -78,30 +78,30 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], AC_PATH_PROG([_libcurl_config],[curl-config],["$withval/bin"], ["$withval/bin"]) else - AC_PATH_PROG([_libcurl_config],[curl-config]) + AC_PATH_PROG([_libcurl_config],[curl-config]) fi if test x$_libcurl_config != "x" ; then AC_CACHE_CHECK([for the version of libcurl], - [libcurl_cv_lib_curl_version], + [libcurl_cv_lib_curl_version], [libcurl_cv_lib_curl_version=`$_libcurl_config --version | $AWK '{print $[]2}'`]) - _libcurl_version=`echo $libcurl_cv_lib_curl_version | $_libcurl_version_parse` - _libcurl_wanted=`echo ifelse([$2],,[0],[$2]) | $_libcurl_version_parse` + _libcurl_version=`echo $libcurl_cv_lib_curl_version | $_libcurl_version_parse` + _libcurl_wanted=`echo ifelse([$2],,[0],[$2]) | $_libcurl_version_parse` if test $_libcurl_wanted -gt 0 ; then - AC_CACHE_CHECK([for libcurl >= version $2], - [libcurl_cv_lib_version_ok], + AC_CACHE_CHECK([for libcurl >= version $2], + [libcurl_cv_lib_version_ok], [ - if test $_libcurl_version -ge $_libcurl_wanted ; then - libcurl_cv_lib_version_ok=yes - else - libcurl_cv_lib_version_ok=no - fi + if test $_libcurl_version -ge $_libcurl_wanted ; then + libcurl_cv_lib_version_ok=yes + else + libcurl_cv_lib_version_ok=no + fi ]) fi - if test $_libcurl_wanted -eq 0 || test x$libcurl_cv_lib_version_ok = xyes ; then + if test $_libcurl_wanted -eq 0 || test x$libcurl_cv_lib_version_ok = xyes ; then if test x"$LIBCURL_CPPFLAGS" = "x" ; then LIBCURL_CPPFLAGS=`$_libcurl_config --cflags` fi @@ -109,8 +109,8 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], LIBCURL=`$_libcurl_config --libs` # This is so silly, but Apple actually has a bug in their - # curl-config script. Fixed in Tiger, but there are still - # lots of Panther installs around. + # curl-config script. Fixed in Tiger, but there are still + # lots of Panther installs around. case "${host}" in powerpc-apple-darwin7*) LIBCURL=`echo $LIBCURL | sed -e 's|-arch i386||g'` @@ -118,18 +118,18 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], esac fi - # All curl-config scripts support --feature - _libcurl_features=`$_libcurl_config --feature` + # All curl-config scripts support --feature + _libcurl_features=`$_libcurl_config --feature` # Is it modern enough to have --protocols? (7.12.4) - if test $_libcurl_version -ge 461828 ; then + if test $_libcurl_version -ge 461828 ; then _libcurl_protocols=`$_libcurl_config --protocols` fi - else + else _libcurl_try_link=no - fi + fi - unset _libcurl_wanted + unset _libcurl_wanted fi if test $_libcurl_try_link = yes ; then @@ -167,8 +167,8 @@ x=CURLOPT_VERBOSE; if test $libcurl_cv_lib_curl_usable = yes ; then - # Does curl_free() exist in this version of libcurl? - # If not, fake it with free() + # Does curl_free() exist in this version of libcurl? + # If not, fake it with free() _libcurl_save_cppflags=$CPPFLAGS CPPFLAGS="$CPPFLAGS $LIBCURL_CPPFLAGS" @@ -176,8 +176,8 @@ x=CURLOPT_VERBOSE; LIBS="$LIBS $LIBCURL" AC_CHECK_FUNC(curl_free,, - AC_DEFINE(curl_free,free, - [Define curl_free() as free() if our version of curl lacks curl_free.])) + AC_DEFINE(curl_free,free, + [Define curl_free() as free() if our version of curl lacks curl_free.])) CPPFLAGS=$_libcurl_save_cppflags LIBS=$_libcurl_save_libs @@ -190,40 +190,40 @@ x=CURLOPT_VERBOSE; AC_SUBST(LIBCURL) for _libcurl_feature in $_libcurl_features ; do - AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_feature_$_libcurl_feature),[1]) - eval AS_TR_SH(libcurl_feature_$_libcurl_feature)=yes + AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_feature_$_libcurl_feature),[1]) + eval AS_TR_SH(libcurl_feature_$_libcurl_feature)=yes done - if test "x$_libcurl_protocols" = "x" ; then + if test "x$_libcurl_protocols" = "x" ; then - # We don't have --protocols, so just assume that all - # protocols are available - _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP" + # We don't have --protocols, so just assume that all + # protocols are available + _libcurl_protocols="HTTP FTP FILE TELNET LDAP DICT TFTP" - if test x$libcurl_feature_SSL = xyes ; then - _libcurl_protocols="$_libcurl_protocols HTTPS" + if test x$libcurl_feature_SSL = xyes ; then + _libcurl_protocols="$_libcurl_protocols HTTPS" - # FTPS wasn't standards-compliant until version - # 7.11.0 (0x070b00 == 461568) - if test $_libcurl_version -ge 461568; then - _libcurl_protocols="$_libcurl_protocols FTPS" - fi - fi + # FTPS wasn't standards-compliant until version + # 7.11.0 (0x070b00 == 461568) + if test $_libcurl_version -ge 461568; then + _libcurl_protocols="$_libcurl_protocols FTPS" + fi + fi - # RTSP, IMAP, POP3 and SMTP were added in + # RTSP, IMAP, POP3 and SMTP were added in # 7.20.0 (0x071400 == 463872) - if test $_libcurl_version -ge 463872; then - _libcurl_protocols="$_libcurl_protocols RTSP IMAP POP3 SMTP" - fi - fi - - for _libcurl_protocol in $_libcurl_protocols ; do - AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_protocol_$_libcurl_protocol),[1]) - eval AS_TR_SH(libcurl_protocol_$_libcurl_protocol)=yes + if test $_libcurl_version -ge 463872; then + _libcurl_protocols="$_libcurl_protocols RTSP IMAP POP3 SMTP" + fi + fi + + for _libcurl_protocol in $_libcurl_protocols ; do + AC_DEFINE_UNQUOTED(AS_TR_CPP(libcurl_protocol_$_libcurl_protocol),[1]) + eval AS_TR_SH(libcurl_protocol_$_libcurl_protocol)=yes done - else - unset LIBCURL - unset LIBCURL_CPPFLAGS + else + unset LIBCURL + unset LIBCURL_CPPFLAGS fi fi -- cgit v1.2.1 From a4a60afabbd65e674222a6df6ccd09c1b358ab77 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 20 Feb 2010 22:29:59 +0000 Subject: - Fixed the SMTP compliance by making sure RCPT TO addresses are specified properly in angle brackets. Recipients provided with CURLOPT_MAIL_RCPT now get angle bracket wrapping automatically by libcurl unless the recipient starts with an angle bracket as then the app is assumed to deal with that properly on its own. --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index cbbbefe31..07c4c0a22 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1092,6 +1092,10 @@ SMTP mail request. The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. +Each recipient in SMTP lingo is specified with angle brackets (<>), but should +you not use an angle bracket as first letter libcurl will assume you provide a +single email address only and enclose that with angle brackets for you. + (Added in 7.20.0) .SH TFTP OPTIONS .IP CURLOPT_TFTP_BLKSIZE -- cgit v1.2.1 From 9ac65581bb08dd6f67d249d59bb834a1673d3a89 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 21 Feb 2010 14:40:22 +0000 Subject: TFTP transfers are not blocking since 7.20.0 --- docs/libcurl/libcurl-multi.3 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index df4416f3f..4ff5f4924 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2009, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -138,7 +138,6 @@ the future, you should be aware of the following current restrictions: - Active FTP connections - HTTP proxy CONNECT operations - SOCKS proxy handshakes - - TFTP transfers - file:// transfers - TELNET transfers .fi -- cgit v1.2.1 From a0fba2f66b8bf553633322c36d1c60366d6a9399 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 4 Mar 2010 16:06:00 +0000 Subject: Julien Chaffraix clarified CURLOPT_HEADERFUNCTION and made CURLOPT_HEADERFUNCTION and CURLOPT_WRITEFUNCTION more consistent --- docs/libcurl/curl_easy_setopt.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 07c4c0a22..a9d8ad45d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -94,7 +94,7 @@ function gets called by libcurl as soon as there is data received that needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP, it will not be zero terminated. Return the number of bytes actually taken care of. If that amount differs from the amount passed -to your function, it'll signal an error to the library and it will abort the +to your function, it'll signal an error to the library. This will abort the transfer and return \fICURLE_WRITE_ERROR\fP. From 7.18.0, the function can return CURL_WRITEFUNC_PAUSE which then will @@ -272,9 +272,9 @@ using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP. Do not assume that the header line is zero terminated! The pointer named \fIstream\fP is the one you set with the \fICURLOPT_WRITEHEADER\fP option. The callback function must return the number -of bytes actually taken care of, or return -1 to signal error to the library -(it will cause it to abort the transfer with a \fICURLE_WRITE_ERROR\fP return -code). +of bytes actually taken care of. If that amount differs from the amount passed +to your function, it'll signal an error to the library. This will abort the +transfer and return \fICURL_WRITE_ERROR\fP. If this option is not set, or if it is set to NULL, but \fICURLOPT_HEADERDATA\fP (\fICURLOPT_WRITEHEADER\fP) is set to anything but -- cgit v1.2.1 From 2309b4e330b96bc2e1f8e36b6184015e59544037 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 24 Mar 2010 11:02:54 +0100 Subject: remove the CVSish $Id$ lines --- docs/libcurl/Makefile.am | 1 - docs/libcurl/curl_easy_cleanup.3 | 1 - docs/libcurl/curl_easy_duphandle.3 | 1 - docs/libcurl/curl_easy_escape.3 | 1 - docs/libcurl/curl_easy_getinfo.3 | 1 - docs/libcurl/curl_easy_init.3 | 1 - docs/libcurl/curl_easy_pause.3 | 1 - docs/libcurl/curl_easy_perform.3 | 1 - docs/libcurl/curl_easy_recv.3 | 1 - docs/libcurl/curl_easy_reset.3 | 1 - docs/libcurl/curl_easy_send.3 | 1 - docs/libcurl/curl_easy_setopt.3 | 1 - docs/libcurl/curl_easy_strerror.3 | 1 - docs/libcurl/curl_easy_unescape.3 | 1 - docs/libcurl/curl_escape.3 | 1 - docs/libcurl/curl_formadd.3 | 1 - docs/libcurl/curl_formfree.3 | 1 - docs/libcurl/curl_formget.3 | 1 - docs/libcurl/curl_free.3 | 1 - docs/libcurl/curl_getdate.3 | 1 - docs/libcurl/curl_getenv.3 | 1 - docs/libcurl/curl_global_cleanup.3 | 1 - docs/libcurl/curl_global_init.3 | 1 - docs/libcurl/curl_mprintf.3 | 1 - docs/libcurl/curl_multi_add_handle.3 | 1 - docs/libcurl/curl_multi_assign.3 | 1 - docs/libcurl/curl_multi_cleanup.3 | 1 - docs/libcurl/curl_multi_fdset.3 | 1 - docs/libcurl/curl_multi_info_read.3 | 1 - docs/libcurl/curl_multi_init.3 | 1 - docs/libcurl/curl_multi_perform.3 | 1 - docs/libcurl/curl_multi_remove_handle.3 | 1 - docs/libcurl/curl_multi_setopt.3 | 1 - docs/libcurl/curl_multi_socket.3 | 1 - docs/libcurl/curl_multi_socket_action.3 | 1 - docs/libcurl/curl_multi_strerror.3 | 1 - docs/libcurl/curl_multi_timeout.3 | 1 - docs/libcurl/curl_share_cleanup.3 | 1 - docs/libcurl/curl_share_init.3 | 1 - docs/libcurl/curl_share_setopt.3 | 1 - docs/libcurl/curl_share_strerror.3 | 1 - docs/libcurl/curl_slist_append.3 | 1 - docs/libcurl/curl_slist_free_all.3 | 1 - docs/libcurl/curl_strequal.3 | 1 - docs/libcurl/curl_unescape.3 | 1 - docs/libcurl/curl_version.3 | 1 - docs/libcurl/curl_version_info.3 | 1 - docs/libcurl/libcurl-easy.3 | 1 - docs/libcurl/libcurl-errors.3 | 1 - docs/libcurl/libcurl-multi.3 | 1 - docs/libcurl/libcurl-share.3 | 1 - docs/libcurl/libcurl-tutorial.3 | 1 - docs/libcurl/libcurl.3 | 1 - 53 files changed, 53 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 032f8d344..3f949d66c 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -1,5 +1,4 @@ # -# $Id$ # AUTOMAKE_OPTIONS = foreign no-dependencies diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index c19291af2..75a370367 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH curl_easy_cleanup 3 "22 aug 2007" "libcurl 7.17.0" "libcurl Manual" diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 index 4afb40ed5..3fae30e6a 100644 --- a/docs/libcurl/curl_easy_duphandle.3 +++ b/docs/libcurl/curl_easy_duphandle.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_easy_duphandle 3 "18 September 2001" "libcurl 7.9" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3 index de3059397..2c09875cb 100644 --- a/docs/libcurl/curl_easy_escape.3 +++ b/docs/libcurl/curl_easy_escape.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH curl_easy_escape 3 "7 April 2006" "libcurl 7.15.4" "libcurl Manual" diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 7859d67c9..32f0ae996 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH curl_easy_getinfo 3 "11 Feb 2009" "libcurl 7.19.4" "libcurl Manual" diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 9b7ef2f1d..478db5c03 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_easy_init 3 "4 March 2002" "libcurl 7.8.1" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3 index 1eb89347f..4d16ecffe 100644 --- a/docs/libcurl/curl_easy_pause.3 +++ b/docs/libcurl/curl_easy_pause.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_easy_pause 3 "17 Dec 2007" "libcurl 7.18.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3 index ccc18c259..1ed006b0b 100644 --- a/docs/libcurl/curl_easy_perform.3 +++ b/docs/libcurl/curl_easy_perform.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_easy_perform 3 "5 Mar 2001" "libcurl 7.7" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_easy_recv.3 b/docs/libcurl/curl_easy_recv.3 index ea806ff66..1ede58944 100644 --- a/docs/libcurl/curl_easy_recv.3 +++ b/docs/libcurl/curl_easy_recv.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH curl_easy_recv 3 "29 April 2008" "libcurl 7.18.2" "libcurl Manual" diff --git a/docs/libcurl/curl_easy_reset.3 b/docs/libcurl/curl_easy_reset.3 index 30d031610..4652f7e60 100644 --- a/docs/libcurl/curl_easy_reset.3 +++ b/docs/libcurl/curl_easy_reset.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_easy_reset 3 "31 July 2004" "libcurl 7.12.1" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_easy_send.3 b/docs/libcurl/curl_easy_send.3 index 30bb7ad1e..17c4c1f54 100644 --- a/docs/libcurl/curl_easy_send.3 +++ b/docs/libcurl/curl_easy_send.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH curl_easy_send 3 "29 April 2008" "libcurl 7.18.2" "libcurl Manual" diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a9d8ad45d..e8b0e7feb 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH curl_easy_setopt 3 "1 Jan 2010" "libcurl 7.20.0" "libcurl Manual" diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 index be8f1b454..1afbd12bf 100644 --- a/docs/libcurl/curl_easy_strerror.3 +++ b/docs/libcurl/curl_easy_strerror.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_easy_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_easy_unescape.3 b/docs/libcurl/curl_easy_unescape.3 index 2aef6b098..9b03fd0f9 100644 --- a/docs/libcurl/curl_easy_unescape.3 +++ b/docs/libcurl/curl_easy_unescape.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH curl_easy_unescape 3 "7 April 2006" "libcurl 7.15.4" "libcurl Manual" diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 1c2774401..59906150e 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_escape 3 "6 March 2002" "libcurl 7.9" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 90576ba9d..06757ed0a 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 191cbc215..2fba295ab 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_formfree 3 "6 April 2001" "libcurl 7.7.1" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index 999208112..b0dd8fead 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_formget 3 "20 June 2006" "libcurl 7.15.5" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 index 447259d4f..f8546935f 100644 --- a/docs/libcurl/curl_free.3 +++ b/docs/libcurl/curl_free.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_free 3 "12 Aug 2003" "libcurl 7.10" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index d1152ebc0..73cd3ef1d 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_getdate 3 "12 Aug 2005" "libcurl 7.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index 5d672710d..74132921a 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_getenv 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3 index 4cb13a7da..9ca11d6ff 100644 --- a/docs/libcurl/curl_global_cleanup.3 +++ b/docs/libcurl/curl_global_cleanup.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_global_cleanup 3 "17 Feb 2006" "libcurl 7.8" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index fad153b6f..e732911f8 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_global_init 3 "11 May 2004" "libcurl 7.12" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index 8b27815c5..ade7f65f5 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_printf 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index 1553b4ec3..85f199ed9 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_add_handle 3 "4 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3 index 83dc7b72d..3e15d73e6 100644 --- a/docs/libcurl/curl_multi_assign.3 +++ b/docs/libcurl/curl_multi_assign.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_assign 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 index 128c03a0f..d40173c99 100644 --- a/docs/libcurl/curl_multi_cleanup.3 +++ b/docs/libcurl/curl_multi_cleanup.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_cleanup 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 1fdf3dbfd..79281056e 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_fdset 3 "2 Jan 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 3a58c642e..9ff08e707 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_info_read 3 "18 Dec 2004" "libcurl 7.10.3" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index 393d13ae7..0ac298efd 100644 --- a/docs/libcurl/curl_multi_init.3 +++ b/docs/libcurl/curl_multi_init.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_init 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index daf15c478..ede23905f 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_perform 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 index 45a77ffc9..efecb109e 100644 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_remove_handle 3 "6 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 2cf468314..a1cbb70dc 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_setopt 3 "10 Oct 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 2029e4311..18b571c1c 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index c155c7e60..ff86e3f26 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_socket_action 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 index a08243f1d..2d9801d6a 100644 --- a/docs/libcurl/curl_multi_strerror.3 +++ b/docs/libcurl/curl_multi_strerror.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_multi_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index b4da9af89..8ba8da7fb 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_multi_timeout 3 "2 Jan 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 index d45e0bbcc..222197cc8 100644 --- a/docs/libcurl/curl_share_cleanup.3 +++ b/docs/libcurl/curl_share_cleanup.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_share_cleanup 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index 70f307f7a..871519cb9 100644 --- a/docs/libcurl/curl_share_init.3 +++ b/docs/libcurl/curl_share_init.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_share_init 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index c3316cd24..351360da9 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_share_setopt 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 index b5199d57c..69087dbf2 100644 --- a/docs/libcurl/curl_share_strerror.3 +++ b/docs/libcurl/curl_share_strerror.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_share_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 index a20d2f9a4..5cca9b72e 100644 --- a/docs/libcurl/curl_slist_append.3 +++ b/docs/libcurl/curl_slist_append.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_slist_append 3 "19 Jun 2003" "libcurl 7.10.4" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_slist_free_all.3 b/docs/libcurl/curl_slist_free_all.3 index 079bdf105..ec1b3607b 100644 --- a/docs/libcurl/curl_slist_free_all.3 +++ b/docs/libcurl/curl_slist_free_all.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_slist_free_all 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index 1442a70f6..8ab4234bc 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH curl_strequal 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index 561ef8f07..9bb470f4e 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_unescape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_version.3 b/docs/libcurl/curl_version.3 index 4998c7556..24793caeb 100644 --- a/docs/libcurl/curl_version.3 +++ b/docs/libcurl/curl_version.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_version 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" .SH NAME diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index ea4214c1b..4481830a3 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH curl_version_info 3 "10 June 2009" "libcurl 7.19.6" "libcurl Manual" diff --git a/docs/libcurl/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 index 5280bf6ff..803e54244 100644 --- a/docs/libcurl/libcurl-easy.3 +++ b/docs/libcurl/libcurl-easy.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH libcurl 3 "12 Aug 2003" "libcurl 7.10.7" "libcurl easy interface" .SH NAME diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index e11b1f3b7..b4f2940b2 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH libcurl-errors 3 "1 Jan 2010" "libcurl 7.20.0" "libcurl errors" diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 4ff5f4924..d84bafcad 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH libcurl-multi 3 "3 Feb 2007" "libcurl 7.16.0" "libcurl multi interface" diff --git a/docs/libcurl/libcurl-share.3 b/docs/libcurl/libcurl-share.3 index 4745c122e..2e58c0ba6 100644 --- a/docs/libcurl/libcurl-share.3 +++ b/docs/libcurl/libcurl-share.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH libcurl-share 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl share interface" .SH NAME diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index b435c4bfc..3a1c6e509 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -18,7 +18,6 @@ .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY .\" * KIND, either express or implied. .\" * -.\" * $Id$ .\" ************************************************************************** .\" .TH libcurl-tutorial 3 "4 Mar 2009" "libcurl" "libcurl programming" diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index fb33a5e14..c0b221fe7 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -1,4 +1,3 @@ -.\" $Id$ .\" .TH libcurl 3 "19 March 2002" "libcurl 7.9.6" "libcurl overview" .SH NAME -- cgit v1.2.1 From 1ac168e576d8e78b58640e1e997249717529b482 Mon Sep 17 00:00:00 2001 From: Chris Conroy Date: Wed, 24 Mar 2010 01:35:03 -0400 Subject: Fix RTSP GET_PARAMETER empty and non-empty operation. Test coverage included. Thanks to Massimo Callegari for the bug report --- docs/libcurl/curl_easy_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e8b0e7feb..243180d00 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1345,7 +1345,9 @@ terminate the RTSP session since it is valid to control an RTSP session over different connections. (Added in 7.20.0) .IP CURL_RTSPREQ_GET_PARAMETER Retrieve a parameter from the server. By default, libcurl will automatically -include an \fIAccept: text/parameters\fP header unless a custom one is set. +include a \fIContent-Type: text/parameters\fP header on all non-empty requests +unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST +(see \fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat message (e.g. in the presence of a server-specified timeout) should send use an empty GET_PARAMETER request. (Added in 7.20.0) -- cgit v1.2.1 From 05de2cf18094ddfb461b70bd5e6af4b6098c408c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 25 Mar 2010 23:22:03 +0100 Subject: remove all .cvsignore files --- docs/libcurl/.cvsignore | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 docs/libcurl/.cvsignore (limited to 'docs/libcurl') diff --git a/docs/libcurl/.cvsignore b/docs/libcurl/.cvsignore deleted file mode 100644 index f7954dff0..000000000 --- a/docs/libcurl/.cvsignore +++ /dev/null @@ -1,5 +0,0 @@ -Makefile -Makefile.in -*html -*ps -*pdf -- cgit v1.2.1 From d18fb4a12968c6a8ed26488dfe6169fc294d10be Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 Apr 2010 11:08:06 +0200 Subject: refer to CURLMOPT_TIMERFUNCTION for multi_socket users curl_multi_timeout(3) is simply the wrong function to use if you're using the multi_socket API and this document now states this pretty clearly to help guiding users. --- docs/libcurl/curl_multi_timeout.3 | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index 8ba8da7fb..9e53d0b8a 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -22,6 +22,10 @@ of milliseconds at this very moment. If 0, it means you should proceed immediately without waiting for anything. If it returns -1, there's no timeout at all set. +An application that uses the multi_socket API SHOULD not use this function, but +SHOULD instead use \fIcurl_multi_setopt(3)\fP and its +\fPCURLMOPT_TIMERFUNCTION\fP option for proper and desired behavior. + Note: if libcurl returns a -1 timeout here, it just means that libcurl currently has no stored timeout value. You must not wait too long (more than a few seconds perhaps) before you call curl_multi_perform() again. @@ -34,7 +38,6 @@ by a previous call to \fBcurl_multi_socket(3)\fP. .SH AVAILABILITY This function was added in libcurl 7.15.4. .SH "SEE ALSO" -.BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " -.BR curl_multi_socket "(3) " +.BR curl_multi_socket "(3), " curl_multi_setopt "(3) " -- cgit v1.2.1 From a76fa1768103d075afd828a7f400390ddd4fd07b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 14 Apr 2010 17:34:57 +0200 Subject: IGNORE: files generated by maketgz --- docs/libcurl/.gitignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/libcurl/.gitignore (limited to 'docs/libcurl') diff --git a/docs/libcurl/.gitignore b/docs/libcurl/.gitignore new file mode 100644 index 000000000..23f832b73 --- /dev/null +++ b/docs/libcurl/.gitignore @@ -0,0 +1,2 @@ +*.html +*.pdf -- cgit v1.2.1 From 2c1b0624ac6ed2695e121bd9581a9eb9762a5c98 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 26 Apr 2010 15:37:39 +0200 Subject: progress callback: can be called more than once per sec --- docs/libcurl/curl_easy_setopt.3 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 243180d00..88b216c3d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -246,11 +246,11 @@ argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP. Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of its internal equivalent with a frequent interval during operation (roughly -once per second) no matter if data is being transfered or not. Unknown/unused -argument values passed to the callback will be set to zero (like if you only -download data, the upload size will remain 0). Returning a non-zero value from -this callback will cause libcurl to abort the transfer and return -\fICURLE_ABORTED_BY_CALLBACK\fP. +once per second or sooner) no matter if data is being transfered or not. +Unknown/unused argument values passed to the callback will be set to zero +(like if you only download data, the upload size will remain 0). Returning a +non-zero value from this callback will cause libcurl to abort the transfer and +return \fICURLE_ABORTED_BY_CALLBACK\fP. If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl -- cgit v1.2.1 From 0825cd80a62c21725fb3615f1fdd3aa6cc5f0f34 Mon Sep 17 00:00:00 2001 From: Pavel Raiskup Date: Wed, 12 May 2010 15:33:22 +0200 Subject: FTP: WILDCARDMATCH/CHUNKING/FNMATCH added --- docs/libcurl/curl_easy_setopt.3 | 85 +++++++++++++++++++++++++++++++++++++++++ docs/libcurl/libcurl-errors.3 | 10 +++++ 2 files changed, 95 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 88b216c3d..295eb749d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -84,6 +84,54 @@ 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 c-ares support to enable asynchronous DNS lookups, which enables nice timeouts for name resolves without signals. +.IP CURLOPT_WILDCARDMATCH +Set this option to 1 if you want to transfer multiple files according to a +file name pattern. The pattern can be specified as part of the \fICURLOPT_URL\fP +option, using an fnmatch-like pattern (Shell Pattern Matching) in the last part +of URL (file name). + +By default, libcurl uses its internal implementation of fnmatch(). You can +provide your own matching function by the \fICURLOPT_FNMATCH_FUNCTION\fR option. + +This feature is only supported by the FTP download for now. + +A brief introduction of its syntax follows: +.RS +.IP "\fB*\fR - ASTERISK" +\&ftp://example.com/some/path/\fB*.txt\fR (for all txt's from the root +directory) +.RE +.RS +.IP "\fB?\fR - QUESTION MARK" +Question mark matches any (exactly one) character. + +\&ftp://example.com/some/path/\fBphoto?.jpeg\fR +.RE +.RS +.IP "\fB[\fR - BRACKET EXPRESSION" +The left bracket opens a bracket expression. The question mark and asterisk have +no special meaning in a bracket expression. Each bracket expression ends by the +right bracket and matches exactly one character. Some examples follow: + +\fB[a-zA-Z0\-9]\fR or \fB[f\-gF\-G]\fR \- character interval + +\fB[abc]\fR - character enumeration + +\fB[^abc]\fR or \fB[!abc]\fR - negation + +\fB[[:\fR\fIname\fR\fB:]]\fR class expression. Supported classes are +\fBalnum\fR,\fBlower\fR, \fBspace\fR, \fBalpha\fR, \fBdigit\fR, \fBprint\fR, +\fBupper\fR, \fBblank\fR, \fBgraph\fR, \fBxdigit\fR. + +\fB[][-!^]\fR - special case \- matches only '\-', ']', '[', '!' or '^'. These +characters have no special purpose. + +\fB[\\[\\]\\\\]\fR - escape syntax. Matches '[', ']' or '\\'. + +Using the rules above, a file name pattern can be constructed: + +\&ftp://example.com/some/path/\fB[a-z[:upper:]\\\\].jpeg\fR +.RE .PP .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION @@ -424,6 +472,43 @@ in 7.20.0) .IP CURLOPT_INTERLEAVEDATA This is the stream that will be passed to \fICURLOPT_INTERLEAVEFUNCTION\fP when interleaved RTP data is received. (Added in 7.20.0) +.IP CURLOPT_CHUNK_BGN_FUNCTION +Function pointer that should match the following prototype: \fBlong function +(const void *transfer_info, void *ptr, int remains)\fR. This function +gets called by libcurl before a part of the stream is going to be transferred +(if the transfer supports chunks). + +This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH\fR +option for now. + +The target of transfer_info parameter is a "feature depended" structure. For the +FTP wildcard download, the target is curl_fileinfo structure (see +\fIcurl/curl.h\fR). +The parameter ptr is a pointer given by \fICURLOPT_CHUNK_DATA\fR. The parameter +remains contains number of chunks remaining per the transfer. If the feature is +not available, the parameter has zero value. + +Return \fICURL_CHUNK_BGN_FUNC_OK\fR if everything is fine, +\fICURL_CHUNK_BGN_FUNC_SKIP\fR if you want to skip the concrete chunk or +\fICURL_CHUNK_BGN_FUNC_FAIL\fR to tell libcurl to stop if some error occurred. +.IP CURLOPT_CHUNK_END_FUNCTION +Function pointer that should match the following prototype: +\fBlong function(void *ptr)\fR. This function gets called by libcurl as soon as +a part of the stream has been transferred (or skipped). + +Return \fICURL_CHUNK_END_FUNC_OK\fR if everything is fine or +\fBCURL_CHUNK_END_FUNC_FAIL\fR to tell the lib to stop if some error occurred. +.IP CURLOPT_CHUNK_DATA +Pass a pointer that will be untouched by libcurl and passed as the ptr argument +to the \fICURL_CHUNK_BGN_FUNTION\fR and \fICURL_CHUNK_END_FUNTION\fR. +.IP CURLOPT_FNMATCH_FUNCTION +Function pointer that should match \fBint function(const char *pattern, const +char *string)\fR prototype (see \fIcurl/curl.h\fR). It is used internally for +the wildcard matching feature. + +Return \fICURL_FNMATCHFUNC_MATCH\fR if pattern matches the string, +\fICURL_FNMATCHFUNC_NOMATCH\fR if not or \fICURL_FNMATCHFUNC_FAIL\fR if an error +occurred. .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index b4f2940b2..c3c854e90 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -218,6 +218,16 @@ return code is only returned from \fIcurl_easy_recv(3)\fP and 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_FTP_PRET_FAILED (84)" +PRET command failed +.IP "CURLE_RTSP_CSEQ_ERROR (85)" +Mismatch of RTSP CSeq numbers. +.IP "CURLE_RTSP_SESSION_ERROR (86)" +Mismatch of RTSP Session Identifiers. +.IP "CURLE_FTP_BAD_FILE_LIST (87)" +Unable to parse FTP file list (during FTP wildcard downloading). +.IP "CURLE_CHUNK_FAILED (88)" +Chunk callback reported error. .IP "CURLE_OBSOLETE*" These error codes will never be returned. They were used in an old libcurl version and are currently unused. -- cgit v1.2.1 From d62ce21249ac2aa1dbcb62c290a8774012adbb16 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 12 May 2010 23:18:22 +0200 Subject: syntax: cleanups --- docs/libcurl/curl_easy_setopt.3 | 48 ++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 24 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 295eb749d..06b6d2bd4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -474,41 +474,41 @@ This is the stream that will be passed to \fICURLOPT_INTERLEAVEFUNCTION\fP when interleaved RTP data is received. (Added in 7.20.0) .IP CURLOPT_CHUNK_BGN_FUNCTION Function pointer that should match the following prototype: \fBlong function -(const void *transfer_info, void *ptr, int remains)\fR. This function -gets called by libcurl before a part of the stream is going to be transferred -(if the transfer supports chunks). +(const void *transfer_info, void *ptr, int remains)\fP. This function gets +called by libcurl before a part of the stream is going to be transferred (if +the transfer supports chunks). -This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH\fR +This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH\fP option for now. -The target of transfer_info parameter is a "feature depended" structure. For the -FTP wildcard download, the target is curl_fileinfo structure (see -\fIcurl/curl.h\fR). -The parameter ptr is a pointer given by \fICURLOPT_CHUNK_DATA\fR. The parameter -remains contains number of chunks remaining per the transfer. If the feature is -not available, the parameter has zero value. +The target of transfer_info parameter is a "feature depended" structure. For +the FTP wildcard download, the target is curl_fileinfo structure (see +\fIcurl/curl.h\fP). The parameter ptr is a pointer given by +\fICURLOPT_CHUNK_DATA\fP. The parameter remains contains number of chunks +remaining per the transfer. If the feature is not available, the parameter has +zero value. -Return \fICURL_CHUNK_BGN_FUNC_OK\fR if everything is fine, -\fICURL_CHUNK_BGN_FUNC_SKIP\fR if you want to skip the concrete chunk or -\fICURL_CHUNK_BGN_FUNC_FAIL\fR to tell libcurl to stop if some error occurred. +Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine, +\fICURL_CHUNK_BGN_FUNC_SKIP\fP if you want to skip the concrete chunk or +\fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred. .IP CURLOPT_CHUNK_END_FUNCTION -Function pointer that should match the following prototype: -\fBlong function(void *ptr)\fR. This function gets called by libcurl as soon as -a part of the stream has been transferred (or skipped). +Function pointer that should match the following prototype: \fBlong +function(void *ptr)\fP. This function gets called by libcurl as soon as a part +of the stream has been transferred (or skipped). -Return \fICURL_CHUNK_END_FUNC_OK\fR if everything is fine or -\fBCURL_CHUNK_END_FUNC_FAIL\fR to tell the lib to stop if some error occurred. +Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or +\fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred. .IP CURLOPT_CHUNK_DATA -Pass a pointer that will be untouched by libcurl and passed as the ptr argument -to the \fICURL_CHUNK_BGN_FUNTION\fR and \fICURL_CHUNK_END_FUNTION\fR. +Pass a pointer that will be untouched by libcurl and passed as the ptr +argument to the \fICURL_CHUNK_BGN_FUNTION\fP and \fICURL_CHUNK_END_FUNTION\fP. .IP CURLOPT_FNMATCH_FUNCTION Function pointer that should match \fBint function(const char *pattern, const -char *string)\fR prototype (see \fIcurl/curl.h\fR). It is used internally for +char *string)\fP prototype (see \fIcurl/curl.h\fP). It is used internally for the wildcard matching feature. -Return \fICURL_FNMATCHFUNC_MATCH\fR if pattern matches the string, -\fICURL_FNMATCHFUNC_NOMATCH\fR if not or \fICURL_FNMATCHFUNC_FAIL\fR if an error -occurred. +Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, +\fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an +error occurred. .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error -- cgit v1.2.1 From a1a98d59081c7fac5e9cfe5c8a1d300facdcbe4c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 12 May 2010 23:59:11 +0200 Subject: ftp wildcards: mention they're added in 7.21.0 --- docs/libcurl/curl_easy_setopt.3 | 45 +++++++++++++++++++++++------------------ 1 file changed, 25 insertions(+), 20 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 06b6d2bd4..7fa4f7271 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -86,53 +86,55 @@ Consider building libcurl with c-ares support to enable asynchronous DNS lookups, which enables nice timeouts for name resolves without signals. .IP CURLOPT_WILDCARDMATCH Set this option to 1 if you want to transfer multiple files according to a -file name pattern. The pattern can be specified as part of the \fICURLOPT_URL\fP -option, using an fnmatch-like pattern (Shell Pattern Matching) in the last part -of URL (file name). +file name pattern. The pattern can be specified as part of the +\fICURLOPT_URL\fP option, using an fnmatch-like pattern (Shell Pattern +Matching) in the last part of URL (file name). -By default, libcurl uses its internal implementation of fnmatch(). You can -provide your own matching function by the \fICURLOPT_FNMATCH_FUNCTION\fR option. +By default, libcurl uses its internal wildcard matching implementation. You +can provide your own matching function by the \fICURLOPT_FNMATCH_FUNCTION\fP +option. This feature is only supported by the FTP download for now. A brief introduction of its syntax follows: .RS -.IP "\fB*\fR - ASTERISK" -\&ftp://example.com/some/path/\fB*.txt\fR (for all txt's from the root +.IP "\fB*\fP - ASTERISK" +\&ftp://example.com/some/path/\fB*.txt\fP (for all txt's from the root directory) .RE .RS -.IP "\fB?\fR - QUESTION MARK" +.IP "\fB?\fP - QUESTION MARK" Question mark matches any (exactly one) character. -\&ftp://example.com/some/path/\fBphoto?.jpeg\fR +\&ftp://example.com/some/path/\fBphoto?.jpeg\fP .RE .RS -.IP "\fB[\fR - BRACKET EXPRESSION" +.IP "\fB[\fP - BRACKET EXPRESSION" The left bracket opens a bracket expression. The question mark and asterisk have no special meaning in a bracket expression. Each bracket expression ends by the right bracket and matches exactly one character. Some examples follow: -\fB[a-zA-Z0\-9]\fR or \fB[f\-gF\-G]\fR \- character interval +\fB[a-zA-Z0\-9]\fP or \fB[f\-gF\-G]\fP \- character interval -\fB[abc]\fR - character enumeration +\fB[abc]\fP - character enumeration -\fB[^abc]\fR or \fB[!abc]\fR - negation +\fB[^abc]\fP or \fB[!abc]\fP - negation -\fB[[:\fR\fIname\fR\fB:]]\fR class expression. Supported classes are -\fBalnum\fR,\fBlower\fR, \fBspace\fR, \fBalpha\fR, \fBdigit\fR, \fBprint\fR, -\fBupper\fR, \fBblank\fR, \fBgraph\fR, \fBxdigit\fR. +\fB[[:\fP\fIname\fP\fB:]]\fP class expression. Supported classes are +\fBalnum\fP,\fBlower\fP, \fBspace\fP, \fBalpha\fP, \fBdigit\fP, \fBprint\fP, +\fBupper\fP, \fBblank\fP, \fBgraph\fP, \fBxdigit\fP. -\fB[][-!^]\fR - special case \- matches only '\-', ']', '[', '!' or '^'. These +\fB[][-!^]\fP - special case \- matches only '\-', ']', '[', '!' or '^'. These characters have no special purpose. -\fB[\\[\\]\\\\]\fR - escape syntax. Matches '[', ']' or '\\'. +\fB[\\[\\]\\\\]\fP - escape syntax. Matches '[', ']' or '\\'. Using the rules above, a file name pattern can be constructed: -\&ftp://example.com/some/path/\fB[a-z[:upper:]\\\\].jpeg\fR +\&ftp://example.com/some/path/\fB[a-z[:upper:]\\\\].jpeg\fP .RE .PP +(This was added in 7.21.0) .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t @@ -491,6 +493,7 @@ zero value. Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine, \fICURL_CHUNK_BGN_FUNC_SKIP\fP if you want to skip the concrete chunk or \fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred. +(This was added in 7.21.0) .IP CURLOPT_CHUNK_END_FUNCTION Function pointer that should match the following prototype: \fBlong function(void *ptr)\fP. This function gets called by libcurl as soon as a part @@ -498,9 +501,11 @@ of the stream has been transferred (or skipped). Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or \fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred. +(This was added in 7.21.0) .IP CURLOPT_CHUNK_DATA Pass a pointer that will be untouched by libcurl and passed as the ptr argument to the \fICURL_CHUNK_BGN_FUNTION\fP and \fICURL_CHUNK_END_FUNTION\fP. +(This was added in 7.21.0) .IP CURLOPT_FNMATCH_FUNCTION Function pointer that should match \fBint function(const char *pattern, const char *string)\fP prototype (see \fIcurl/curl.h\fP). It is used internally for @@ -508,7 +513,7 @@ the wildcard matching feature. Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, \fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an -error occurred. +error occurred. (This was added in 7.21.0) .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error -- cgit v1.2.1 From 7871fbad4dfb534e103c5b4beb2c9b53a5295bb0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 13 May 2010 00:07:37 +0200 Subject: updated with symbols added in recent commits for 7.21.0 --- docs/libcurl/symbols-in-versions | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 9cc6e5c0a..a9bebe229 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -188,6 +188,9 @@ CURLOPT_BUFFERSIZE 7.10 CURLOPT_CAINFO 7.4.2 CURLOPT_CAPATH 7.9.8 CURLOPT_CERTINFO 7.19.1 +CURLOPT_CHUNK_BGN_FUNCTION 7.21.0 +CURLOPT_CHUNK_DATA 7.21.0 +CURLOPT_CHUNK_END_FUNCTION 7.21.0 CURLOPT_CLOSEFUNCTION 7.7 7.11.1 7.15.4 CURLOPT_CLOSEPOLICY 7.7 7.16.1 CURLOPT_CONNECTTIMEOUT 7.7 @@ -217,6 +220,7 @@ CURLOPT_FAILONERROR 7.1 CURLOPT_FILE 7.1 7.9.7 CURLOPT_FILETIME 7.5 CURLOPT_FLAGS 7.1 - 7.9.2 +CURLOPT_FNMATCH_FUNCTION 7.21.0 CURLOPT_FOLLOWLOCATION 7.1 CURLOPT_FORBID_REUSE 7.7 CURLOPT_FRESH_CONNECT 7.7 @@ -236,14 +240,6 @@ CURLOPT_FTP_SSL_CCC 7.16.1 CURLOPT_FTP_USE_EPRT 7.10.5 CURLOPT_FTP_USE_EPSV 7.9.2 CURLOPT_FTP_USE_PRET 7.20.0 -CURLOPT_RTSP_REQUEST 7.20.0 -CURLOPT_RTSP_SESSION_ID 7.20.0 -CURLOPT_RTSP_STREAM_URI 7.20.0 -CURLOPT_RTSP_TRANSPORT 7.20.0 -CURLOPT_RTSP_CLIENT_CSEQ 7.20.0 -CURLOPT_RTSP_SERVER_CSEQ 7.20.0 -CURLOPT_INTERLEAVEDATA 7.20.0 -CURLOPT_INTERLEAVEFUNCTION 7.20.0 CURLOPT_HEADER 7.1 CURLOPT_HEADERDATA 7.10 CURLOPT_HEADERFUNCTION 7.7.2 @@ -262,6 +258,8 @@ CURLOPT_INFILE 7.1 7.9.7 CURLOPT_INFILESIZE 7.1 CURLOPT_INFILESIZE_LARGE 7.11.0 CURLOPT_INTERFACE 7.3 +CURLOPT_INTERLEAVEDATA 7.20.0 +CURLOPT_INTERLEAVEFUNCTION 7.20.0 CURLOPT_IOCTLDATA 7.12.3 CURLOPT_IOCTLFUNCTION 7.12.3 CURLOPT_IPRESOLVE 7.10.8 @@ -328,6 +326,12 @@ CURLOPT_REDIR_PROTOCOLS 7.19.4 CURLOPT_REFERER 7.1 CURLOPT_RESUME_FROM 7.1 CURLOPT_RESUME_FROM_LARGE 7.11.0 +CURLOPT_RTSP_CLIENT_CSEQ 7.20.0 +CURLOPT_RTSP_REQUEST 7.20.0 +CURLOPT_RTSP_SERVER_CSEQ 7.20.0 +CURLOPT_RTSP_SESSION_ID 7.20.0 +CURLOPT_RTSP_STREAM_URI 7.20.0 +CURLOPT_RTSP_TRANSPORT 7.20.0 CURLOPT_SEEKDATA 7.18.1 CURLOPT_SEEKFUNCTION 7.18.1 CURLOPT_SHARE 7.10 @@ -380,6 +384,7 @@ CURLOPT_USERNAME 7.19.1 CURLOPT_USERPWD 7.1 CURLOPT_USE_SSL 7.17.0 CURLOPT_VERBOSE 7.1 +CURLOPT_WILDCARDMATCH 7.21.0 CURLOPT_WRITEDATA 7.9.7 CURLOPT_WRITEFUNCTION 7.1 CURLOPT_WRITEHEADER 7.1 @@ -409,6 +414,12 @@ CURLPROXY_SOCKS4 7.10 CURLPROXY_SOCKS4A 7.18.0 CURLPROXY_SOCKS5 7.10 CURLPROXY_SOCKS5_HOSTNAME 7.18.0 +CURLPROTO_RTMP 7.21.0 +CURLPROTO_RTMPT 7.21.0 +CURLPROTO_RTMPE 7.21.0 +CURLPROTO_RTMPTE 7.21.0 +CURLPROTO_RTMPS 7.21.0 +CURLPROTO_RTMPTS 7.21.0 CURLSSH_AUTH_DEFAULT 7.16.1 CURLSSH_AUTH_HOST 7.16.1 CURLSSH_AUTH_KEYBOARD 7.16.1 @@ -427,6 +438,14 @@ CURLVERSION_FIRST 7.10 CURLVERSION_NOW 7.10 CURLVERSION_SECOND 7.11.1 CURLVERSION_THIRD 7.12.0 +CURL_CHUNK_BGN_FUNC_FAIL 7.21.0 +CURL_CHUNK_BGN_FUNC_OK 7.21.0 +CURL_CHUNK_BGN_FUNC_SKIP 7.21.0 +CURL_CHUNK_END_FUNC_FAIL 7.21.0 +CURL_CHUNK_END_FUNC_OK 7.21.0 +CURL_FNMATCHFUNC_FAIL 7.21.0 +CURL_FNMATCHFUNC_MATCH 7.21.0 +CURL_FNMATCHFUNC_NOMATCH 7.21.0 CURL_HTTP_VERSION_1_0 7.9.1 CURL_HTTP_VERSION_1_1 7.9.1 CURL_HTTP_VERSION_NONE 7.9.1 -- cgit v1.2.1 From 2ffe834bffa893efcd8942736ab14e311a0087b3 Mon Sep 17 00:00:00 2001 From: Kamil Dudka Date: Sun, 16 May 2010 02:49:08 +0200 Subject: ftp wildcard: a new option CURLOPT_FNMATCH_DATA --- docs/libcurl/curl_easy_setopt.3 | 9 ++++++--- docs/libcurl/symbols-in-versions | 1 + 2 files changed, 7 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7fa4f7271..a26898f1e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -507,13 +507,16 @@ Pass a pointer that will be untouched by libcurl and passed as the ptr argument to the \fICURL_CHUNK_BGN_FUNTION\fP and \fICURL_CHUNK_END_FUNTION\fP. (This was added in 7.21.0) .IP CURLOPT_FNMATCH_FUNCTION -Function pointer that should match \fBint function(const char *pattern, const -char *string)\fP prototype (see \fIcurl/curl.h\fP). It is used internally for -the wildcard matching feature. +Function pointer that should match \fBint function(void *ptr, const char +*pattern, const char *string)\fP prototype (see \fIcurl/curl.h\fP). It is used +internally for the wildcard matching feature. Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, \fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an error occurred. (This was added in 7.21.0) +.IP CURLOPT_FNMATCH_DATA +Pass a pointer that will be untouched by libcurl and passed as the ptr argument +to the \fICURL_FNMATCH_FUNCTION\fP. (This was added in 7.21.0) .SH ERROR OPTIONS .IP CURLOPT_ERRORBUFFER Pass a char * to a buffer that the libcurl may store human readable error diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index a9bebe229..b33619ee0 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -220,6 +220,7 @@ CURLOPT_FAILONERROR 7.1 CURLOPT_FILE 7.1 7.9.7 CURLOPT_FILETIME 7.5 CURLOPT_FLAGS 7.1 - 7.9.2 +CURLOPT_FNMATCH_DATA 7.21.0 CURLOPT_FNMATCH_FUNCTION 7.21.0 CURLOPT_FOLLOWLOCATION 7.1 CURLOPT_FORBID_REUSE 7.7 -- cgit v1.2.1 From 8098d9417c649272b9d6d2ad76abbde7dfbfcad1 Mon Sep 17 00:00:00 2001 From: Frank Meier Date: Sat, 5 Jun 2010 00:29:09 +0200 Subject: getinfo: added *_PRIMARY_PORT, *_LOCAL_IP and *_LOCAL_PORT --- docs/libcurl/curl_easy_getinfo.3 | 11 +++++++++++ docs/libcurl/symbols-in-versions | 15 +++++++++------ 2 files changed, 20 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 32f0ae996..b80eacf7d 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -173,6 +173,17 @@ string holding the IP address of the most recent connection done with this \fBcurl\fP handle. This string may be IPv6 if that's enabled. Note that you get a pointer to a memory area that will be re-used at next request so you need to copy the string if you want to keep the information. (Added in 7.19.0) +.IP CURLINFO_PRIMARY_PORT +Pass a pointer to a long to receive the destination port of the most recent +connection done with this \fBcurl\fP handle. (Added in 7.21.0) +.IP CURLINFO_LOCAL_IP +Pass a pointer to a char pointer to receive the pointer to a zero-terminated +string holding the local (source) IP address of the most recent connection done +with this \fBcurl\fP handle. This string may be IPv6 if that's enabled. The +same restrictions apply as to \fICURLINFO_PRIMARY_IP\fP. (Added in 7.21.0) +.IP CURLINFO_LOCAL_PORT +Pass a pointer to a long to receive the local (source) port of the most recent +connection done with this \fBcurl\fP handle. (Added in 7.21.0) .IP CURLINFO_COOKIELIST Pass a pointer to a 'struct curl_slist *' to receive a linked-list of all cookies cURL knows (expired ones, too). Don't forget to diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index b33619ee0..a02ead453 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -151,11 +151,14 @@ CURLINFO_HTTPAUTH_AVAIL 7.10.8 CURLINFO_HTTP_CODE 7.4.1 7.10.8 CURLINFO_HTTP_CONNECTCODE 7.10.7 CURLINFO_LASTSOCKET 7.15.2 +CURLINFO_LOCAL_IP 7.21.0 +CURLINFO_LOCAL_PORT 7.21.0 CURLINFO_NAMELOOKUP_TIME 7.4.1 CURLINFO_NUM_CONNECTS 7.12.3 CURLINFO_OS_ERRNO 7.12.2 CURLINFO_PRETRANSFER_TIME 7.4.1 CURLINFO_PRIMARY_IP 7.19.0 +CURLINFO_PRIMARY_PORT 7.21.0 CURLINFO_PRIVATE 7.10.3 CURLINFO_PRIVATE 7.10.3 CURLINFO_PROXYAUTH_AVAIL 7.10.8 @@ -402,6 +405,12 @@ CURLPROTO_LDAP 7.19.4 CURLPROTO_LDAPS 7.19.4 CURLPROTO_POP3 7.20.0 CURLPROTO_POP3S 7.20.0 +CURLPROTO_RTMP 7.21.0 +CURLPROTO_RTMPE 7.21.0 +CURLPROTO_RTMPS 7.21.0 +CURLPROTO_RTMPT 7.21.0 +CURLPROTO_RTMPTE 7.21.0 +CURLPROTO_RTMPTS 7.21.0 CURLPROTO_RTSP 7.20.0 CURLPROTO_SCP 7.19.4 CURLPROTO_SFTP 7.19.4 @@ -415,12 +424,6 @@ CURLPROXY_SOCKS4 7.10 CURLPROXY_SOCKS4A 7.18.0 CURLPROXY_SOCKS5 7.10 CURLPROXY_SOCKS5_HOSTNAME 7.18.0 -CURLPROTO_RTMP 7.21.0 -CURLPROTO_RTMPT 7.21.0 -CURLPROTO_RTMPE 7.21.0 -CURLPROTO_RTMPTE 7.21.0 -CURLPROTO_RTMPS 7.21.0 -CURLPROTO_RTMPTS 7.21.0 CURLSSH_AUTH_DEFAULT 7.16.1 CURLSSH_AUTH_HOST 7.16.1 CURLSSH_AUTH_KEYBOARD 7.16.1 -- cgit v1.2.1 From 53e47ca947312981fd5773bb618aa5e5b1f2e1e3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 30 Jul 2010 23:08:17 +0200 Subject: KNOWN_BUG: The SOCKET type in Win64 is 64 bits The SOCKET type in Win64 is 64 bits large (and thus so is curl_socket_t on that platform), and long is only 32 bits. It makes it impossible for curl_easy_getinfo() to return a socket properly with the CURLINFO_LASTSOCKET option as for all other operating systems. --- docs/libcurl/curl_easy_getinfo.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index b80eacf7d..9f298ed71 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -198,6 +198,9 @@ working with the socket, you must call curl_easy_cleanup() as usual and let libcurl close the socket and cleanup other resources associated with the handle. This is typically used in combination with \fICURLOPT_CONNECT_ONLY\fP. (Added in 7.15.2) + +NOTE: this API is not really working on win64, since the SOCKET type on win64 +is 64 bit large while its 'long' is only 32 bits. .IP CURLINFO_FTP_ENTRY_PATH Pass a pointer to a char pointer to receive a pointer to a string holding the path of the entry path. That is the initial path libcurl ended up in when -- cgit v1.2.1 From 5c2b6b2d3e60500bb6b47b57cfe4e65c2ba03751 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 7 Aug 2010 14:06:28 +0200 Subject: curl_easy_setopt.3: rename stream to userdata In some places where the name 'stream' has been used for naming a function argument that is in fact settable with a setopt() option we now call that argument 'userdata' to make it more obvious that it is in fact possible to set by the application. Suggested by: Jeff Pohlmeyer --- docs/libcurl/curl_easy_setopt.3 | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a26898f1e..1704f6ad0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -138,7 +138,7 @@ Using the rules above, a file name pattern can be constructed: .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t -function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This +function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP This function gets called by libcurl as soon as there is data received that needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP, it will not be zero terminated. Return the number @@ -157,7 +157,7 @@ Set this option to NULL to get the internal default function. The internal default function will write the data to the FILE * given with \fICURLOPT_WRITEDATA\fP. -Set the \fIstream\fP argument with the \fICURLOPT_WRITEDATA\fP option. +Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA\fP option. The callback function will be passed as much data as possible in all invokes, but you cannot possibly make any assumptions. It may be one byte, it may be @@ -180,7 +180,7 @@ This option is also known with the older name \fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA\fP was introduced in 7.9.7. .IP CURLOPT_READFUNCTION Function pointer that should match the following prototype: \fBsize_t -function( void *ptr, size_t size, size_t nmemb, void *stream);\fP This +function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP This function gets called by libcurl as soon as it needs to read data in order to send it to the peer. The data area pointed at by the pointer \fIptr\fP may be filled with at most \fIsize\fP multiplied with \fInmemb\fP number of @@ -201,9 +201,9 @@ 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 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. +If you set this callback pointer to NULL, or don't set it at all, the default +internal read function will be used. It is doing an fread() on the FILE * +userdata set with \fICURLOPT_READDATA\fP. .IP CURLOPT_READDATA Data pointer to pass to the file read function. If you use the \fICURLOPT_READFUNCTION\fP option, this is the pointer you'll get as input. If @@ -313,13 +313,13 @@ Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. .IP CURLOPT_HEADERFUNCTION Function pointer that should match the following prototype: \fIsize_t -function( void *ptr, size_t size, size_t nmemb, void *stream);\fP. This +function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP. This function gets called by libcurl as soon as it has received header data. The header callback will be called once for each header and only complete header lines are passed on to the callback. Parsing headers should be easy enough using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP. Do not assume that the header line is zero -terminated! The pointer named \fIstream\fP is the one you set with the +terminated! The pointer named \fIuserdata\fP is the one you set with the \fICURLOPT_WRITEHEADER\fP option. The callback function must return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the @@ -452,7 +452,7 @@ You will need to override these definitions if they are different on your system. .IP CURLOPT_INTERLEAVEFUNCTION Function pointer that should match the following prototype: \fIsize_t -function( void *ptr, size_t size, size_t nmemb, void *stream)\fP. This +function( void *ptr, size_t size, size_t nmemb, void *userdata)\fP. This function gets called by libcurl as soon as it has received interleaved RTP data. This function gets called for each $ block and therefore contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the @@ -472,8 +472,9 @@ request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler will process any pending RTP data before marking the request as finished. (Added in 7.20.0) .IP CURLOPT_INTERLEAVEDATA -This is the stream that will be passed to \fICURLOPT_INTERLEAVEFUNCTION\fP when -interleaved RTP data is received. (Added in 7.20.0) +This is the userdata pointer that will be passed to +\fICURLOPT_INTERLEAVEFUNCTION\fP when interleaved RTP data is received. (Added +in 7.20.0) .IP CURLOPT_CHUNK_BGN_FUNCTION Function pointer that should match the following prototype: \fBlong function (const void *transfer_info, void *ptr, int remains)\fP. This function gets -- cgit v1.2.1 From 625932d39814fdc3ed4c9f64c1db23328d788cbc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 10 Aug 2010 23:18:16 +0200 Subject: multi_socket_action: clarify how to kickstart it The callbacks are called when curl_multi_socket_action() is called, not when handles are added. This is now mentioned in the "TYPICAL USAGE" section. --- docs/libcurl/curl_multi_socket_action.3 | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index ff86e3f26..94e6f10a5 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -112,14 +112,15 @@ timeout value to use when waiting for socket activities. them for activity. This can be done through your application code, or by way of an external library such as libevent or glib. -6. Wait for activity on any of libcurl's sockets, use the timeout value your +6. Call curl_multi_socket_action() to kickstart everything. To get one or more +callbacks called. + +7. Wait for activity on any of libcurl's sockets, use the timeout value your callback has been told -7, When activity is detected, call curl_multi_socket_action() for the +8, When activity is detected, call curl_multi_socket_action() for the socket(s) that got action. If no activity is detected and the timeout expires, 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, and is deemed stable since 7.16.0. .SH "SEE ALSO" -- cgit v1.2.1 From cfdc4aca4560ffd71c0f549c4330f82a3b1fe23e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Aug 2010 00:36:11 +0200 Subject: RESUME_FROM: clarify what ftp uploads do The numerical value passed to CURLOPT_RESUME_FROM for FTP uploads is interpreted and used as position where to resume the _reading_ of the local file and it will "blindly" append that data on the remote file. This was certainly not clear in the docs previously. Reported by: catalin Bug: http://curl.haxx.se/bug/view.cgi?id=3048174 --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 1704f6ad0..aa2a3aff2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1539,6 +1539,10 @@ want the transfer to start from. Set this option to 0 to make the transfer start from the beginning (effectively disabling resume). For FTP, set this option to -1 to make the transfer start from the end of the target file (useful to continue an interrupted upload). + +When doing uploads with FTP, the resume position is where in the local/source +file libcurl should try to resume the upload from and it will then append the +source file to the remote target file. .IP CURLOPT_RESUME_FROM_LARGE Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) -- cgit v1.2.1 From 9a0b6e42af6b1c40e1817f4e2649deb748affa2f Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Mon, 23 Aug 2010 15:07:14 -0700 Subject: Mention PolarSSL in tutorial & add some URLs to INSTALL --- docs/libcurl/libcurl-tutorial.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 3a1c6e509..236eba056 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -275,6 +275,10 @@ NSS is claimed to be thread-safe already without anything required. +PolarSSL + + Required actions unknown. + yassl Required actions unknown. -- cgit v1.2.1 From 09cee1633b0dd6e079f53047f7a6fc97bb1b1ef8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 28 Aug 2010 23:07:21 +0200 Subject: CURLOPT_DIRLISTONLY: don't use with CURLOPT_WILDCARDMATCH --- docs/libcurl/curl_easy_setopt.3 | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index aa2a3aff2..6452c2a2c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1259,9 +1259,12 @@ A parameter set to 1 tells the library to just list the names of files in a directory, instead of doing a full directory listing that would include file sizes, dates etc. This works for FTP and SFTP URLs. -This causes an FTP NLST command to be sent on an FTP server. Beware -that some FTP servers list only files in their response to NLST; they -might not include subdirectories and symbolic links. +This causes an FTP NLST command to be sent on an FTP server. Beware that some +FTP servers list only files in their response to NLST; they might not include +subdirectories and symbolic links. + +Do NOT use this option if you also use \fICURLOPT_WILDCARDMATCH\fP as it will +effectively break that feature then. (This option was known as CURLOPT_FTPLISTONLY up to 7.16.4) .IP CURLOPT_APPEND -- cgit v1.2.1 From 3aef3ed8f6b894ec25cff7d4fe96084413dd049c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 1 Oct 2010 19:52:53 +0200 Subject: curl_easy_setopt.3: CURLOPT_DIRLISTONLY implies dir list Make it explicit that setting CURLOPT_DIRLISTONLY to 1 will make libcurl to list the directory. --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6452c2a2c..9da53792b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1263,6 +1263,9 @@ This causes an FTP NLST command to be sent on an FTP server. Beware that some FTP servers list only files in their response to NLST; they might not include subdirectories and symbolic links. +Setting this option to 1 also implies a directory listing even if the URL +doesn't end with a slash, which otherwise is necessary. + Do NOT use this option if you also use \fICURLOPT_WILDCARDMATCH\fP as it will effectively break that feature then. -- cgit v1.2.1 From 9bce615f4667907856244d37179d9ee13714118e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Oct 2010 11:50:43 +0200 Subject: libcurl.m4: mention argument is PREFIX The macro provides a --with-libcurl option that expects a PREFIX to be specified and not actually a "directory" in which libcurl will be found. This now spells that out more clearly. Reported by: Dan Locks Bug: http://curl.haxx.se/bug/view.cgi?id=3079891 --- docs/libcurl/libcurl.m4 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index f551e3026..c83658d35 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -61,7 +61,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], AH_TEMPLATE([LIBCURL_PROTOCOL_SMTP],[Defined if libcurl supports SMTP]) AC_ARG_WITH(libcurl, - AC_HELP_STRING([--with-libcurl=DIR],[look for the curl library in DIR]), + AC_HELP_STRING([--with-libcurl=PREFIX],[look for the curl library in PREFIX/lib and headers in PREFIX/include]), [_libcurl_with=$withval],[_libcurl_with=ifelse([$1],,[yes],[$1])]) if test "$_libcurl_with" != "no" ; then -- cgit v1.2.1 From cda02fb78b859dafe679624206aac39878db19fd Mon Sep 17 00:00:00 2001 From: Dan Locks Date: Thu, 7 Oct 2010 18:05:36 +0200 Subject: libcurl.m4: AC_PATH_PROG fixes The invocation of autoconf's AC_PATH_PROG( ) is not quite right for finding curl-config. This fix corrects the negative case (where curl-config is not found). --- docs/libcurl/libcurl.m4 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index c83658d35..952b79f4e 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -75,10 +75,10 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], if test -d "$_libcurl_with" ; then LIBCURL_CPPFLAGS="-I$withval/include" _libcurl_ldflags="-L$withval/lib" - AC_PATH_PROG([_libcurl_config],[curl-config],["$withval/bin"], + AC_PATH_PROG([_libcurl_config],[curl-config],[], ["$withval/bin"]) else - AC_PATH_PROG([_libcurl_config],[curl-config]) + AC_PATH_PROG([_libcurl_config],[curl-config],[],[$PATH]) fi if test x$_libcurl_config != "x" ; then -- cgit v1.2.1 From 2869b6ea2b96e36873f5c59660f1870387cca390 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Tue, 12 Oct 2010 11:22:18 -0700 Subject: Added section on server-supplied names to security considerations --- docs/libcurl/libcurl-tutorial.3 | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 236eba056..72f002963 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -1237,6 +1237,15 @@ are used to generate structured data. Characters like embedded carriage returns or ampersands could allow the user to create additional headers or fields that could cause malicious transactions. +.IP "Server-supplied Names" +A server can supply data which the application may, in some cases, use as +a file name. The curl command-line tool does this with --remote-header-name, +using the Content-disposition: header to generate a file name. An application +could also use CURLINFO_EFFECTIVE_URL to generate a file name from a +server-supplied redirect URL. Special care must be taken to sanitize such +names to avoid the possibility of a malicious server supplying one like +"/etc/passwd", "\autoexec.bat" or even ".bashrc". + .IP "Server Certificates" A secure application should never use the CURLOPT_SSL_VERIFYPEER option to disable certificate validation. There are numerous attacks that are enabled -- cgit v1.2.1 From 0f2e35b30576590fcbe441ad909973c085cc8509 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Oct 2010 14:06:07 +0200 Subject: curl_easy_setopt.3: clarify CURLOPT_CRLF The option takes a parameter that should be 1 or 0 to enable or disable the feature. URL: http://curl.haxx.se/bug/view.cgi?id=3086428 --- docs/libcurl/curl_easy_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9da53792b..60a496d1a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1524,7 +1524,9 @@ to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing FTP via a proxy. Beware that not all proxies support this feature. (Added in 7.18.0) .IP CURLOPT_CRLF -Convert Unix newlines to CRLF newlines on transfers. +Pass a long. If the value is set to 1 (one), libcurl converts Unix newlines to +CRLF newlines on transfers. Disable this option again by setting the value to +0 (zero). .IP CURLOPT_RANGE Pass a char * as parameter, which should contain the specified range you want. It should be in the format "X-Y", where X or Y may be left out. HTTP -- cgit v1.2.1 From 65ca4b547b8fb8cf677c6936409f4bf25585a49b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Oct 2010 17:48:51 +0200 Subject: curl_easy_setopt.3: CURLOPT_USE_SSL is not just for FTP It is for FTP, SMTP, POP3, IMAP at least. --- docs/libcurl/curl_easy_setopt.3 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 60a496d1a..e4bf8656f 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1339,7 +1339,9 @@ 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 transfer. (Added in 7.11.0) + +This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP erc. (This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants were known as CURLFTPSSL_*) -- cgit v1.2.1 From 6164d40fce532a6aa45b09789b28eae8ca7acf2a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Oct 2010 17:50:10 +0200 Subject: curl_easy_setopt.3: spellfix --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e4bf8656f..cfd7d30a8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1341,7 +1341,7 @@ This option has no effect if PORT, EPRT or EPSV is used instead of PASV. Pass a long using one of the values from below, to make libcurl use your desired level of SSL for the transfer. (Added in 7.11.0) -This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP erc. +This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. (This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants were known as CURLFTPSSL_*) -- cgit v1.2.1 From ca9f9cb8754b5b5010b76ec77b950eadbe42dc9b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Nov 2010 22:01:01 +0100 Subject: spellfix: CURLOPT_TFTP_BLKSIZE it is --- docs/libcurl/symbols-in-versions | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index a02ead453..9b01ffb05 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -374,7 +374,7 @@ CURLOPT_SSL_VERIFYPEER 7.4.2 CURLOPT_STDERR 7.1 CURLOPT_TCP_NODELAY 7.11.2 CURLOPT_TELNETOPTIONS 7.7 -CURLOPT_TFTPBLKSIZE 7.19.4 +CURLOPT_TFTP_BLKSIZE 7.19.4 CURLOPT_TIMECONDITION 7.1 CURLOPT_TIMEOUT 7.1 CURLOPT_TIMEOUT_MS 7.16.2 -- cgit v1.2.1 From 13e9571dd09171ea2cd9c1c265a3bb2d6d56d653 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 2 Nov 2010 23:35:12 +0100 Subject: symbols-in-versions: added missing symbols --- docs/libcurl/symbols-in-versions | 60 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 9b01ffb05..79f4bb807 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -30,6 +30,9 @@ CURLE_BAD_CALLING_ORDER 7.1 7.17.0 CURLE_BAD_CONTENT_ENCODING 7.10 CURLE_BAD_FUNCTION_ARGUMENT 7.1 CURLE_BAD_PASSWORD_ENTERED - 7.17.0 +CURLE_CHUNK_FAILED 7.20.1 +CURLE_CONV_FAILED 7.15.4 +CURLE_CONV_REQD 7.15.4 CURLE_COULDNT_CONNECT 7.1 CURLE_COULDNT_RESOLVE_HOST 7.1 CURLE_COULDNT_RESOLVE_PROXY 7.1 @@ -37,7 +40,9 @@ CURLE_FAILED_INIT 7.1 CURLE_FILESIZE_EXCEEDED 7.10.8 CURLE_FILE_COULDNT_READ_FILE 7.1 CURLE_FTP_ACCESS_DENIED 7.1 +CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 7.1 +CURLE_FTP_BAD_FILE_LIST 7.20.1 CURLE_FTP_CANT_GET_HOST 7.1 CURLE_FTP_CANT_RECONNECT 7.1 7.17.0 CURLE_FTP_COULDNT_GET_SIZE 7.1 7.17.0 @@ -65,11 +70,13 @@ CURLE_HTTP_NOT_FOUND 7.1 CURLE_HTTP_PORT_FAILED - 7.12.0 CURLE_HTTP_POST_ERROR 7.1 CURLE_HTTP_RANGE_ERROR 7.1 7.17.0 +CURLE_HTTP_RETURNED_ERROR 7.10.3 CURLE_INTERFACE_FAILED 7.12.0 CURLE_LDAP_CANNOT_BIND 7.1 CURLE_LDAP_INVALID_URL 7.10.8 CURLE_LDAP_SEARCH_FAILED 7.1 CURLE_LIBRARY_NOT_FOUND 7.1 7.17.0 +CURLE_LOGIN_DENIED 7.13.1 CURLE_MALFORMAT_USER 7.1 7.17.0 CURLE_OK 7.1 CURLE_OPERATION_TIMEDOUT 7.17.0 @@ -83,12 +90,16 @@ CURLE_READ_ERROR 7.1 CURLE_RECV_ERROR 7.13.0 CURLE_REMOTE_ACCESS_DENIED 7.17.0 CURLE_REMOTE_DISK_FULL 7.17.0 +CURLE_REMOTE_FILE_EXISTS 7.17.0 +CURLE_REMOTE_FILE_NOT_FOUND 7.16.1 CURLE_RTSP_CSEQ_ERROR 7.20.0 CURLE_RTSP_SESSION_ERROR 7.20.0 CURLE_SEND_ERROR 7.13.0 +CURLE_SEND_FAIL_REWIND 7.12.3 CURLE_SHARE_IN_USE - 7.17.0 CURLE_SSH 7.16.1 CURLE_SSL_CACERT 7.10 +CURLE_SSL_CACERT_BADFILE 7.16.0 CURLE_SSL_CERTPROBLEM 7.10 CURLE_SSL_CIPHER 7.10 CURLE_SSL_CONNECT_ERROR 7.1 @@ -104,10 +115,13 @@ CURLE_TFTP_DISKFULL 7.15.0 7.17.0 CURLE_TFTP_EXISTS 7.15.0 7.17.0 CURLE_TFTP_ILLEGAL 7.15.0 CURLE_TFTP_NOSUCHUSER 7.15.0 +CURLE_TFTP_NOTFOUND 7.15.0 +CURLE_TFTP_PERM 7.15.0 CURLE_TFTP_UNKNOWNID 7.15.0 CURLE_TOO_MANY_REDIRECTS 7.5 CURLE_UNKNOWN_TELNET_OPTION 7.7 CURLE_UNSUPPORTED_PROTOCOL 7.1 +CURLE_UPLOAD_FAILED 7.16.3 CURLE_URL_MALFORMAT 7.1 CURLE_URL_MALFORMAT_USER 7.1 7.17.0 CURLE_USE_SSL_FAILED 7.17.0 @@ -167,10 +181,16 @@ CURLINFO_REDIRECT_TIME 7.9.7 CURLINFO_REDIRECT_URL 7.18.2 CURLINFO_REQUEST_SIZE 7.4.1 CURLINFO_RESPONSE_CODE 7.10.8 +CURLINFO_RTSP_CLIENT_CSEQ 7.20.0 +CURLINFO_RTSP_CSEQ_RECV 7.20.0 +CURLINFO_RTSP_SERVER_CSEQ 7.20.0 +CURLINFO_RTSP_SESSION_ID 7.20.0 CURLINFO_SIZE_DOWNLOAD 7.4.1 CURLINFO_SIZE_UPLOAD 7.4.1 CURLINFO_SPEED_DOWNLOAD 7.4.1 CURLINFO_SPEED_UPLOAD 7.4.1 +CURLINFO_SSL_DATA_IN 7.12.1 +CURLINFO_SSL_DATA_OUT 7.12.1 CURLINFO_SSL_ENGINES 7.12.3 CURLINFO_SSL_VERIFYRESULT 7.5 CURLINFO_STARTTRANSFER_TIME 7.9.2 @@ -330,6 +350,7 @@ CURLOPT_REDIR_PROTOCOLS 7.19.4 CURLOPT_REFERER 7.1 CURLOPT_RESUME_FROM 7.1 CURLOPT_RESUME_FROM_LARGE 7.11.0 +CURLOPT_RTSPHEADER 7.20.0 CURLOPT_RTSP_CLIENT_CSEQ 7.20.0 CURLOPT_RTSP_REQUEST 7.20.0 CURLOPT_RTSP_SERVER_CSEQ 7.20.0 @@ -338,6 +359,7 @@ CURLOPT_RTSP_STREAM_URI 7.20.0 CURLOPT_RTSP_TRANSPORT 7.20.0 CURLOPT_SEEKDATA 7.18.1 CURLOPT_SEEKFUNCTION 7.18.1 +CURLOPT_SERVER_RESPONSE_TIMEOUT 7.20.0 CURLOPT_SHARE 7.10 CURLOPT_SOCKOPTDATA 7.16.0 CURLOPT_SOCKOPTFUNCTION 7.16.0 @@ -353,6 +375,9 @@ CURLOPT_SOURCE_URL 7.13.0 - 7.15.4 CURLOPT_SOURCE_USERPWD 7.12.1 - 7.15.4 CURLOPT_SSH_AUTH_TYPES 7.16.1 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 7.17.1 +CURLOPT_SSH_KEYDATA 7.19.6 +CURLOPT_SSH_KEYFUNCTION 7.19.6 +CURLOPT_SSH_KNOWNHOSTS 7.19.6 CURLOPT_SSH_PRIVATE_KEYFILE 7.16.1 CURLOPT_SSH_PUBLIC_KEYFILE 7.16.1 CURLOPT_SSLCERT 7.1 @@ -392,6 +417,7 @@ CURLOPT_WILDCARDMATCH 7.21.0 CURLOPT_WRITEDATA 7.9.7 CURLOPT_WRITEFUNCTION 7.1 CURLOPT_WRITEHEADER 7.1 +CURLOPT_WRITEINFO 7.1 CURLPROTO_ALL 7.19.4 CURLPROTO_DICT 7.19.4 CURLPROTO_FILE 7.19.4 @@ -424,6 +450,11 @@ CURLPROXY_SOCKS4 7.10 CURLPROXY_SOCKS4A 7.18.0 CURLPROXY_SOCKS5 7.10 CURLPROXY_SOCKS5_HOSTNAME 7.18.0 +CURLSHOPT_NONE 7.10.3 +CURLSHOPT_SHARE 7.10.3 +CURLSHOPT_UNLOCKFUNC 7.10.3 +CURLSHOPT_UNSHARE 7.10.3 +CURLSHOPT_USERDATA 7.10.3 CURLSSH_AUTH_DEFAULT 7.16.1 CURLSSH_AUTH_HOST 7.16.1 CURLSSH_AUTH_KEYBOARD 7.16.1 @@ -450,15 +481,44 @@ CURL_CHUNK_END_FUNC_OK 7.21.0 CURL_FNMATCHFUNC_FAIL 7.21.0 CURL_FNMATCHFUNC_MATCH 7.21.0 CURL_FNMATCHFUNC_NOMATCH 7.21.0 +CURL_FORMADD_DISABLED 7.12.1 +CURL_FORMADD_ILLEGAL_ARRAY 7.9.8 +CURL_FORMADD_INCOMPLETE 7.9.8 +CURL_FORMADD_MEMORY 7.9.8 +CURL_FORMADD_NULL 7.9.8 +CURL_FORMADD_OK 7.9.8 +CURL_FORMADD_OPTION_TWICE 7.9.8 +CURL_FORMADD_UNKNOWN_OPTION 7.9.8 CURL_HTTP_VERSION_1_0 7.9.1 CURL_HTTP_VERSION_1_1 7.9.1 CURL_HTTP_VERSION_NONE 7.9.1 CURL_IPRESOLVE_V4 7.10.8 CURL_IPRESOLVE_V6 7.10.8 CURL_IPRESOLVE_WHATEVER 7.10.8 +CURL_LOCK_ACCESS_NONE 7.10.3 +CURL_LOCK_ACCESS_SHARED 7.10.3 +CURL_LOCK_ACCESS_SINGLE 7.10.3 +CURL_LOCK_DATA_CONNECT 7.10.3 +CURL_LOCK_DATA_COOKIE 7.10.3 +CURL_LOCK_DATA_DNS 7.10.3 +CURL_LOCK_DATA_NONE 7.10.3 +CURL_LOCK_DATA_SHARE 7.10.4 +CURL_LOCK_DATA_SSL_SESSION 7.10.3 CURL_NETRC_IGNORED 7.9.8 CURL_NETRC_OPTIONAL 7.9.8 CURL_NETRC_REQUIRED 7.9.8 +CURL_RTSPREQ_ANNOUNCE 7.20.0 +CURL_RTSPREQ_DESCRIBE 7.20.0 +CURL_RTSPREQ_GET_PARAMETER 7.20.0 +CURL_RTSPREQ_NONE 7.20.0 +CURL_RTSPREQ_OPTIONS 7.20.0 +CURL_RTSPREQ_PAUSE 7.20.0 +CURL_RTSPREQ_PLAY 7.20.0 +CURL_RTSPREQ_RECEIVE 7.20.0 +CURL_RTSPREQ_RECORD 7.20.0 +CURL_RTSPREQ_SETUP 7.20.0 +CURL_RTSPREQ_SET_PARAMETER 7.20.0 +CURL_RTSPREQ_TEARDOWN 7.20.0 CURL_SEEKFUNC_CANTSEEK 7.19.5 CURL_SEEKFUNC_FAIL 7.19.5 CURL_SEEKFUNC_OK 7.19.5 -- cgit v1.2.1 From 52e3c60c8641323e95f7018650dc4ad8fc82e6e8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 3 Nov 2010 10:04:23 +0100 Subject: symbols-in-versions: added 119 missing symbols I've developed a script I call symbol-scan.pl that scans the curl.h and multi.h header files and compare the symbols it finds in there with the symbols symbols-in-versions documents and outputs a report on the differences. Using this I've dug through the history to fill up symbols-in-versions with all the symbols my script found mismatches for. I will commit symbol-scan.pl separatly and think of a way to put it to use in the build/tests so that we from now on will get this in-sync check automatically. --- docs/libcurl/symbols-in-versions | 119 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 79f4bb807..ada249efb 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -18,16 +18,20 @@ CURLAUTH_BASIC 7.10.6 CURLAUTH_DIGEST 7.10.6 CURLAUTH_DIGEST_IE 7.19.3 CURLAUTH_GSSNEGOTIATE 7.10.6 +CURLAUTH_NONE 7.10.6 CURLAUTH_NTLM 7.10.6 CURLCLOSEPOLICY_CALLBACK 7.7 CURLCLOSEPOLICY_LEAST_RECENTLY_USED 7.7 CURLCLOSEPOLICY_LEAST_TRAFFIC 7.7 +CURLCLOSEPOLICY_NONE 7.7 CURLCLOSEPOLICY_OLDEST 7.7 CURLCLOSEPOLICY_SLOWEST 7.7 CURLE_ABORTED_BY_CALLBACK 7.1 CURLE_AGAIN 7.18.2 +CURLE_ALREADY_COMPLETE 7.7.2 CURLE_BAD_CALLING_ORDER 7.1 7.17.0 CURLE_BAD_CONTENT_ENCODING 7.10 +CURLE_BAD_DOWNLOAD_RESUME 7.10 CURLE_BAD_FUNCTION_ARGUMENT 7.1 CURLE_BAD_PASSWORD_ENTERED - 7.17.0 CURLE_CHUNK_FAILED 7.20.1 @@ -126,12 +130,48 @@ CURLE_URL_MALFORMAT 7.1 CURLE_URL_MALFORMAT_USER 7.1 7.17.0 CURLE_USE_SSL_FAILED 7.17.0 CURLE_WRITE_ERROR 7.1 +CURLFILETYPE_DEVICE_BLOCK 7.21.0 +CURLFILETYPE_DEVICE_CHAR 7.21.0 +CURLFILETYPE_DIRECTORY 7.21.0 +CURLFILETYPE_DOOR 7.21.0 +CURLFILETYPE_FILE 7.21.0 +CURLFILETYPE_NAMEDPIPE 7.21.0 +CURLFILETYPE_SOCKET 7.21.0 +CURLFILETYPE_SYMLINK 7.21.0 +CURLFILETYPE_UNKNOWN 7.21.0 +CURLFINFOFLAG_KNOWN_FILENAME 7.21.0 +CURLFINFOFLAG_KNOWN_FILETYPE 7.21.0 +CURLFINFOFLAG_KNOWN_GID 7.21.0 +CURLFINFOFLAG_KNOWN_HLINKCOUNT 7.21.0 +CURLFINFOFLAG_KNOWN_PERM 7.21.0 +CURLFINFOFLAG_KNOWN_SIZE 7.21.0 +CURLFINFOFLAG_KNOWN_TIME 7.21.0 +CURLFINFOFLAG_KNOWN_UID 7.21.0 +CURLFORM_ARRAY 7.9.1 +CURLFORM_BUFFER 7.9.8 +CURLFORM_BUFFERLENGTH 7.9.8 +CURLFORM_BUFFERPTR 7.9.8 +CURLFORM_CONTENTHEADER 7.9.3 +CURLFORM_CONTENTSLENGTH 7.9.1 +CURLFORM_CONTENTTYPE 7.9.1 +CURLFORM_COPYCONTENTS 7.9.1 +CURLFORM_COPYNAME 7.9.1 +CURLFORM_END 7.9.1 +CURLFORM_FILE 7.9.1 +CURLFORM_FILECONTENT 7.9.1 +CURLFORM_FILENAME 7.9.6 +CURLFORM_NAMELENGTH 7.9.1 +CURLFORM_NOTHING 7.9.1 +CURLFORM_PTRCONTENTS 7.9.1 +CURLFORM_PTRNAME 7.9.1 +CURLFORM_STREAM 7.18.2 CURLFTPAUTH_DEFAULT 7.12.2 CURLFTPAUTH_DEFAULT 7.12.2 CURLFTPAUTH_SSL 7.12.2 CURLFTPAUTH_SSL 7.12.2 CURLFTPAUTH_TLS 7.12.2 CURLFTPAUTH_TLS 7.12.2 +CURLFTPMETHOD_DEFAULT 7.15.1 CURLFTPMETHOD_MULTICWD 7.15.1 CURLFTPMETHOD_NOCWD 7.15.1 CURLFTPMETHOD_SINGLECWD 7.15.1 @@ -155,7 +195,9 @@ CURLINFO_CONTENT_TYPE 7.9.4 CURLINFO_COOKIELIST 7.14.1 CURLINFO_DATA_IN 7.9.6 CURLINFO_DATA_OUT 7.9.6 +CURLINFO_DOUBLE 7.4.1 CURLINFO_EFFECTIVE_URL 7.3 +CURLINFO_END 7.4.1 CURLINFO_FILETIME 7.5 CURLINFO_FTP_ENTRY_PATH 7.15.4 CURLINFO_HEADER_IN 7.9.6 @@ -164,10 +206,14 @@ CURLINFO_HEADER_SIZE 7.4.1 CURLINFO_HTTPAUTH_AVAIL 7.10.8 CURLINFO_HTTP_CODE 7.4.1 7.10.8 CURLINFO_HTTP_CONNECTCODE 7.10.7 +CURLINFO_LASTONE 7.4.1 CURLINFO_LASTSOCKET 7.15.2 CURLINFO_LOCAL_IP 7.21.0 CURLINFO_LOCAL_PORT 7.21.0 +CURLINFO_LONG 7.4.1 +CURLINFO_MASK 7.4.1 CURLINFO_NAMELOOKUP_TIME 7.4.1 +CURLINFO_NONE 7.4.1 CURLINFO_NUM_CONNECTS 7.12.3 CURLINFO_OS_ERRNO 7.12.2 CURLINFO_PRETRANSFER_TIME 7.4.1 @@ -187,6 +233,7 @@ CURLINFO_RTSP_SERVER_CSEQ 7.20.0 CURLINFO_RTSP_SESSION_ID 7.20.0 CURLINFO_SIZE_DOWNLOAD 7.4.1 CURLINFO_SIZE_UPLOAD 7.4.1 +CURLINFO_SLIST 7.12.3 CURLINFO_SPEED_DOWNLOAD 7.4.1 CURLINFO_SPEED_UPLOAD 7.4.1 CURLINFO_SSL_DATA_IN 7.12.1 @@ -194,16 +241,47 @@ CURLINFO_SSL_DATA_OUT 7.12.1 CURLINFO_SSL_ENGINES 7.12.3 CURLINFO_SSL_VERIFYRESULT 7.5 CURLINFO_STARTTRANSFER_TIME 7.9.2 +CURLINFO_STRING 7.4.1 CURLINFO_TEXT 7.9.6 CURLINFO_TOTAL_TIME 7.4.1 +CURLINFO_TYPEMASK 7.4.1 +CURLIOCMD_NOP 7.12.3 +CURLIOCMD_RESTARTREAD 7.12.3 +CURLIOE_FAILRESTART 7.12.3 +CURLIOE_OK 7.12.3 +CURLIOE_UNKNOWNCMD 7.12.3 +CURLKHMATCH_MISMATCH 7.19.6 +CURLKHMATCH_MISSING 7.19.6 +CURLKHMATCH_OK 7.19.6 +CURLKHSTAT_DEFER 7.19.6 +CURLKHSTAT_FINE 7.19.6 +CURLKHSTAT_FINE_ADD_TO_FILE 7.19.6 +CURLKHSTAT_REJECT 7.19.6 +CURLKHTYPE_DSS 7.19.6 +CURLKHTYPE_RSA 7.19.6 +CURLKHTYPE_RSA1 7.19.6 +CURLKHTYPE_UNKNOWN 7.19.6 +CURLMOPT_MAXCONNECTS 7.16.3 +CURLMOPT_PIPELINING 7.16.0 +CURLMOPT_SOCKETDATA 7.15.4 +CURLMOPT_SOCKETFUNCTION 7.15.4 +CURLMOPT_TIMERDATA 7.16.0 +CURLMOPT_TIMERFUNCTION 7.16.0 CURLMSG_DONE 7.9.6 +CURLMSG_NONE 7.9.6 CURLM_BAD_EASY_HANDLE 7.9.6 CURLM_BAD_HANDLE 7.9.6 +CURLM_BAD_SOCKET 7.15.4 CURLM_CALL_MULTI_PERFORM 7.9.6 CURLM_CALL_MULTI_SOCKET 7.15.5 CURLM_INTERNAL_ERROR 7.9.6 CURLM_OK 7.9.6 CURLM_OUT_OF_MEMORY 7.9.6 +CURLM_UNKNOWN_OPTION 7.15.4 +CURLOPTTYPE_FUNCTIONPOINT 7.1 +CURLOPTTYPE_LONG 7.1 +CURLOPTTYPE_OBJECTPOINT 7.1 +CURLOPTTYPE_OFF_T 7.11.0 CURLOPT_ADDRESS_SCOPE 7.19.0 CURLOPT_APPEND 7.16.4 CURLOPT_AUTOREFERER 7.1 @@ -418,11 +496,18 @@ CURLOPT_WRITEDATA 7.9.7 CURLOPT_WRITEFUNCTION 7.1 CURLOPT_WRITEHEADER 7.1 CURLOPT_WRITEINFO 7.1 +CURLPAUSE_ALL 7.18.0 +CURLPAUSE_CONT 7.18.0 +CURLPAUSE_RECV 7.18.0 +CURLPAUSE_RECV_CONT 7.18.0 +CURLPAUSE_SEND 7.18.0 +CURLPAUSE_SEND_CONT 7.18.0 CURLPROTO_ALL 7.19.4 CURLPROTO_DICT 7.19.4 CURLPROTO_FILE 7.19.4 CURLPROTO_FTP 7.19.4 CURLPROTO_FTPS 7.19.4 +CURLPROTO_GOPHER 7.21.2 CURLPROTO_HTTP 7.19.4 CURLPROTO_HTTPS 7.19.4 CURLPROTO_IMAP 7.20.0 @@ -450,11 +535,19 @@ CURLPROXY_SOCKS4 7.10 CURLPROXY_SOCKS4A 7.18.0 CURLPROXY_SOCKS5 7.10 CURLPROXY_SOCKS5_HOSTNAME 7.18.0 +CURLSHE_BAD_OPTION 7.10.3 +CURLSHE_INVALID 7.10.3 +CURLSHE_IN_USE 7.10.3 +CURLSHE_NOMEM 7.10.3 +CURLSHE_OK 7.10.3 +CURLSHOPT_LOCKFUNC 7.10.3 CURLSHOPT_NONE 7.10.3 CURLSHOPT_SHARE 7.10.3 CURLSHOPT_UNLOCKFUNC 7.10.3 CURLSHOPT_UNSHARE 7.10.3 CURLSHOPT_USERDATA 7.10.3 +CURLSOCKTYPE_IPCXN 7.15.6 +CURLSSH_AUTH_ANY 7.16.1 CURLSSH_AUTH_DEFAULT 7.16.1 CURLSSH_AUTH_HOST 7.16.1 CURLSSH_AUTH_KEYBOARD 7.16.1 @@ -470,6 +563,7 @@ CURLUSESSL_NONE 7.17.0 CURLUSESSL_TRY 7.17.0 CURLUSESSL_TRY 7.17.0 CURLVERSION_FIRST 7.10 +CURLVERSION_FOURTH 7.16.1 CURLVERSION_NOW 7.10 CURLVERSION_SECOND 7.11.1 CURLVERSION_THIRD 7.12.0 @@ -478,6 +572,10 @@ CURL_CHUNK_BGN_FUNC_OK 7.21.0 CURL_CHUNK_BGN_FUNC_SKIP 7.21.0 CURL_CHUNK_END_FUNC_FAIL 7.21.0 CURL_CHUNK_END_FUNC_OK 7.21.0 +CURL_CSELECT_ERR 7.16.3 +CURL_CSELECT_IN 7.16.3 +CURL_CSELECT_OUT 7.16.3 +CURL_ERROR_SIZE 7.1 CURL_FNMATCHFUNC_FAIL 7.21.0 CURL_FNMATCHFUNC_MATCH 7.21.0 CURL_FNMATCHFUNC_NOMATCH 7.21.0 @@ -489,6 +587,11 @@ CURL_FORMADD_NULL 7.9.8 CURL_FORMADD_OK 7.9.8 CURL_FORMADD_OPTION_TWICE 7.9.8 CURL_FORMADD_UNKNOWN_OPTION 7.9.8 +CURL_GLOBAL_ALL 7.8 +CURL_GLOBAL_DEFAULT 7.8 +CURL_GLOBAL_NOTHING 7.8 +CURL_GLOBAL_SSL 7.8 +CURL_GLOBAL_WIN32 7.8.1 CURL_HTTP_VERSION_1_0 7.9.1 CURL_HTTP_VERSION_1_1 7.9.1 CURL_HTTP_VERSION_NONE 7.9.1 @@ -504,9 +607,22 @@ CURL_LOCK_DATA_DNS 7.10.3 CURL_LOCK_DATA_NONE 7.10.3 CURL_LOCK_DATA_SHARE 7.10.4 CURL_LOCK_DATA_SSL_SESSION 7.10.3 +CURL_MAX_HTTP_HEADER 7.19.7 +CURL_MAX_WRITE_SIZE 7.9.7 CURL_NETRC_IGNORED 7.9.8 CURL_NETRC_OPTIONAL 7.9.8 CURL_NETRC_REQUIRED 7.9.8 +CURL_POLL_IN 7.14.0 +CURL_POLL_INOUT 7.14.0 +CURL_POLL_NONE 7.14.0 +CURL_POLL_OUT 7.14.0 +CURL_POLL_REMOVE 7.14.0 +CURL_READFUNC_ABORT 7.12.1 +CURL_READFUNC_PAUSE 7.18.0 +CURL_REDIR_GET_ALL 7.19.1 +CURL_REDIR_POST_301 7.19.1 +CURL_REDIR_POST_302 7.19.1 +CURL_REDIR_POST_ALL 7.19.1 CURL_RTSPREQ_ANNOUNCE 7.20.0 CURL_RTSPREQ_DESCRIBE 7.20.0 CURL_RTSPREQ_GET_PARAMETER 7.20.0 @@ -522,6 +638,7 @@ CURL_RTSPREQ_TEARDOWN 7.20.0 CURL_SEEKFUNC_CANTSEEK 7.19.5 CURL_SEEKFUNC_FAIL 7.19.5 CURL_SEEKFUNC_OK 7.19.5 +CURL_SOCKET_TIMEOUT 7.14.0 CURL_SSLVERSION_DEFAULT 7.9.2 CURL_SSLVERSION_SSLv2 7.9.2 CURL_SSLVERSION_SSLv3 7.9.2 @@ -529,6 +646,7 @@ CURL_SSLVERSION_TLSv1 7.9.2 CURL_TIMECOND_IFMODSINCE 7.9.7 CURL_TIMECOND_IFUNMODSINCE 7.9.7 CURL_TIMECOND_LASTMOD 7.9.7 +CURL_TIMECOND_NONE 7.9.7 CURL_VERSION_ASYNCHDNS 7.10.7 CURL_VERSION_CONV 7.15.4 CURL_VERSION_CURLDEBUG 7.19.6 @@ -543,3 +661,4 @@ CURL_VERSION_NTLM 7.10.6 CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 +CURL_WRITEFUNC_PAUSE 7.18.0 -- cgit v1.2.1 From d95b67f4092c5f35ea615aba085b44ce9ae92243 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 4 Nov 2010 09:49:02 +0100 Subject: CURLOPT_NOSIGNAL: add blurb about SIGPIPE --- docs/libcurl/curl_easy_setopt.3 | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index cfd7d30a8..ea2630d6e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -84,6 +84,13 @@ 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 c-ares support to enable asynchronous DNS lookups, which enables nice timeouts for name resolves without signals. + +Setting \fICURLOPT_NOSIGNAL\fP to 1 makes libcurl NOT ask the system to ignore +SIGPIPE signals, which otherwise are sent by the system when trying to send +data to a socket which is closed in the other end. libcurl makes an effort to +never cause such SIGPIPEs to trigger, but some operating systems have no way +to avoid them and even on those that have there are some corner cases when +they may still happen, contrary to our desire. .IP CURLOPT_WILDCARDMATCH Set this option to 1 if you want to transfer multiple files according to a file name pattern. The pattern can be specified as part of the -- cgit v1.2.1 From 4bde456f7324df836aa57aaf477b43275aca174a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Nov 2010 09:46:48 +0100 Subject: CURLOPT_USE_SSL: move from FTP options to connection options --- docs/libcurl/curl_easy_setopt.3 | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ea2630d6e..9f1e1a9ab 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1344,24 +1344,6 @@ it already uses for the control connection. But it will use the port number 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 transfer. (Added in 7.11.0) - -This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. - -(This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants -were known as CURLFTPSSL_*) -.RS -.IP CURLUSESSL_NONE -Don't attempt to use SSL. -.IP CURLUSESSL_TRY -Try using SSL, proceed as normal otherwise. -.IP CURLUSESSL_CONTROL -Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. -.IP CURLUSESSL_ALL -Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. -.RE .IP CURLOPT_FTPSSLAUTH Pass a long using one of the values from below, to alter how libcurl issues \&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated (see @@ -1774,6 +1756,24 @@ This option is useful with the \fICURLINFO_LASTSOCKET\fP option to \fIcurl_easy_getinfo(3)\fP. The library can set up the connection and then the application can obtain the most recently used socket for special data transfers. (Added in 7.15.2) +.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 transfer. (Added in 7.11.0) + +This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. + +(This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants +were known as CURLFTPSSL_*) +.RS +.IP CURLUSESSL_NONE +Don't attempt to use SSL. +.IP CURLUSESSL_TRY +Try using SSL, proceed as normal otherwise. +.IP CURLUSESSL_CONTROL +Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. +.IP CURLUSESSL_ALL +Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. +.RE .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be -- cgit v1.2.1 From 0a41318f1d92ad9793de215c2e447af4093c70ef Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Nov 2010 09:53:35 +0100 Subject: CURLOPT_RESOLVE: documented --- docs/libcurl/curl_easy_setopt.3 | 23 +++++++++++++++++++++++ docs/libcurl/symbols-in-versions | 1 + 2 files changed, 24 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9f1e1a9ab..d005b3ffc 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1774,6 +1774,29 @@ Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. .IP CURLUSESSL_ALL Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. .RE +.IP CURLOPT_RESOLVE +Pass a pointer to a linked list of strings with host name resolve information +to use for requests with this handle. The linked list should be a fully valid +list of \fBstruct curl_slist\fP structs properly filled in. Use +\fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP +to clean up an entire list. + +Each single name resolve string should be written using the format +HOST:PORT:ADDRESS where HOST is the name libcurl will try to resolve, PORT is +the port number of the service where libcurl wants to connect to the HOST and +ADDRESS is the numerical IP address. If libcurl is built to support IPv6, +ADDRESS can of course be either IPv4 or IPv6 style addressing. + +This option effectively pre-populates the DNS cache with entries for the +host+port pair so redirects and everything that operations against the +HOST+PORT will instead use your provided ADDRESS. + +You can remove names from the DNS cache again, to stop providing these fake +resolves, by including a string in the linked list that uses the format +\&"-HOST:PORT". The host name must be prefixed with a dash, and the host name +and port number must exactly match what was already added previously. + +(Added in 7.12.3) .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index ada249efb..1884d3d33 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -428,6 +428,7 @@ CURLOPT_REDIR_PROTOCOLS 7.19.4 CURLOPT_REFERER 7.1 CURLOPT_RESUME_FROM 7.1 CURLOPT_RESUME_FROM_LARGE 7.11.0 +CURLOPT_RESOLVE 7.21.3 CURLOPT_RTSPHEADER 7.20.0 CURLOPT_RTSP_CLIENT_CSEQ 7.20.0 CURLOPT_RTSP_REQUEST 7.20.0 -- cgit v1.2.1 From 7d8343934be38c196ae02ac0516580dc98cceb87 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Nov 2010 14:20:23 +0100 Subject: symbols-in-version: add CURL_SOCKET_BAD I also documented the filtering logic in the symbol-scan.pl function to clarify why not all CURL_* symbols are included. --- docs/libcurl/symbols-in-versions | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 1884d3d33..a366ce2ab 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -426,9 +426,9 @@ CURLOPT_READDATA 7.9.7 CURLOPT_READFUNCTION 7.1 CURLOPT_REDIR_PROTOCOLS 7.19.4 CURLOPT_REFERER 7.1 +CURLOPT_RESOLVE 7.21.3 CURLOPT_RESUME_FROM 7.1 CURLOPT_RESUME_FROM_LARGE 7.11.0 -CURLOPT_RESOLVE 7.21.3 CURLOPT_RTSPHEADER 7.20.0 CURLOPT_RTSP_CLIENT_CSEQ 7.20.0 CURLOPT_RTSP_REQUEST 7.20.0 @@ -639,6 +639,7 @@ CURL_RTSPREQ_TEARDOWN 7.20.0 CURL_SEEKFUNC_CANTSEEK 7.19.5 CURL_SEEKFUNC_FAIL 7.19.5 CURL_SEEKFUNC_OK 7.19.5 +CURL_SOCKET_BAD 7.14.0 CURL_SOCKET_TIMEOUT 7.14.0 CURL_SSLVERSION_DEFAULT 7.9.2 CURL_SSLVERSION_SSLv2 7.9.2 -- cgit v1.2.1 From 8636742256c724bee50452d9ef92ffd25b76b8a1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 11 Nov 2010 16:41:59 +0100 Subject: HTTP Auth: Add CURLAUTH_ONLY This is a meta symbol. OR this value together with a single specific auth value to force libcurl to probe for un-restricted auth and if not, only that single auth algorithm is acceptable. For example you can use CURLAUTH_DIGEST|CURLAUTH_ONLY to make libcurl first probe for what method to use, but yet only consider Digest to be acceptable. Using _only_ CURLAUTH_DIGEST without the CURLAUTH_ONLY field, will make libcurl explicitly use Digest right away and not do any probing. --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ docs/libcurl/symbols-in-versions | 1 + 2 files changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d005b3ffc..3d76b6616 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -865,6 +865,10 @@ secure. This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most secure. +.IP CURLAUTH_ONLY +This is a meta symbol. Or this value together with a single specific auth +value to force libcurl to probe for un-restricted auth and if not, only that +single auth algorithm is acceptable. (Added in 7.21.3) .RE .IP CURLOPT_PROXYAUTH Pass a long as parameter, which is set to a bitmask, to tell libcurl which diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index a366ce2ab..fc5834d52 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -20,6 +20,7 @@ CURLAUTH_DIGEST_IE 7.19.3 CURLAUTH_GSSNEGOTIATE 7.10.6 CURLAUTH_NONE 7.10.6 CURLAUTH_NTLM 7.10.6 +CURLAUTH_ONLY 7.21.3 CURLCLOSEPOLICY_CALLBACK 7.7 CURLCLOSEPOLICY_LEAST_RECENTLY_USED 7.7 CURLCLOSEPOLICY_LEAST_TRAFFIC 7.7 -- cgit v1.2.1 From 012f9b7f048425c543af44b22eea8c210f269d39 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 9 Dec 2010 13:07:00 +0100 Subject: symbols-in-versions: CURLOPT_KEYPASSWD fixed It was added in 7.17.0 and is not deprecated --- docs/libcurl/symbols-in-versions | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index fc5834d52..e22b6251e 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -367,7 +367,7 @@ CURLOPT_IOCTLDATA 7.12.3 CURLOPT_IOCTLFUNCTION 7.12.3 CURLOPT_IPRESOLVE 7.10.8 CURLOPT_ISSUERCERT 7.19.0 -CURLOPT_KEYPASSWD - 7.17.0 +CURLOPT_KEYPASSWD 7.17.0 CURLOPT_KRB4LEVEL 7.3 7.17.0 CURLOPT_KRBLEVEL 7.17.0 CURLOPT_LOCALPORT 7.15.2 -- cgit v1.2.1 From 16c4314a21c5918ddb90e537217e0a2406f2f410 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 22 Dec 2010 14:44:10 +0100 Subject: CURLOPT_MAIL_FROM: document the bracket situation --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3d76b6616..a725b33cb 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1189,6 +1189,10 @@ option is set to zero. (added in 7.16.2) Pass a pointer to a zero terminated string as parameter. It will be used to specify the sender address in a mail when sending an SMTP mail with libcurl. +An originator email address in SMTP lingo is specified within angle brackets +(<>) which libcurl will not add for you before version 7.21.4. Failing to +provide such brackets may cause the server to reject your mail. + (Added in 7.20.0) .IP CURLOPT_MAIL_RCPT Pass a pointer to a linked list of recipients to pass to the server in your -- cgit v1.2.1 From cd045e24a08a5d5a0c936d4d9e27506b0f390da7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 30 Dec 2010 23:49:03 +0100 Subject: CURLINFO_FTP_ENTRY_PATH: sftp support --- docs/libcurl/curl_easy_getinfo.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 9f298ed71..2629755e8 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -206,6 +206,8 @@ Pass a pointer to a char pointer to receive a pointer to a string holding the path of the entry path. That is the initial path libcurl ended up in when logging on to the remote FTP server. This stores a NULL as pointer if something is wrong. (Added in 7.15.4) + +Also works for SFTP since 7.21.4 .IP CURLINFO_CERTINFO Pass a pointer to a 'struct curl_certinfo *' and you'll get it set to point to struct that holds a number of linked lists with info about the certificate -- cgit v1.2.1 From d8f6d1c3341cfc5a1263e1f3f339b64e10b75dc3 Mon Sep 17 00:00:00 2001 From: Kamil Dudka Date: Tue, 4 Jan 2011 13:52:54 +0100 Subject: nss: avoid CURLE_OUT_OF_MEMORY given a file name without any slash Bug: https://bugzilla.redhat.com/623663 --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a725b33cb..8c14c7dcc 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1811,8 +1811,9 @@ Pass a pointer to a zero terminated string as parameter. The string should be the file name of your certificate. The default format is "PEM" and can be changed with \fICURLOPT_SSLCERTTYPE\fP. -With NSS this is the nickname of the certificate you wish to authenticate -with. +With NSS this can also be the nickname of the certificate you wish to +authenticate with. If you want to use a file from the current directory, please +precede it with "./" prefix, in order to avoid confusion with a nickname. .IP CURLOPT_SSLCERTTYPE Pass a pointer to a zero terminated string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER". (Added -- cgit v1.2.1 From fc77790bcd451f32a0f60a5e4073b2be54fb40e9 Mon Sep 17 00:00:00 2001 From: Kamil Dudka Date: Tue, 18 Jan 2011 13:53:43 +0100 Subject: nss: fix a bug in handling of CURLOPT_CAPATH ... and update the curl.1 and curl_easy_setopt.3 man pages such that they do not suggest to use an OpenSSL utility if curl is not built against OpenSSL. Bug: https://bugzilla.redhat.com/669702 --- docs/libcurl/curl_easy_setopt.3 | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8c14c7dcc..bd342a125 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1924,13 +1924,15 @@ mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER\fP has to be set too for the check to fail). (Added in 7.19.0) .IP CURLOPT_CAPATH Pass a char * to a zero terminated string naming a directory holding multiple -CA certificates to verify the peer with. The certificate directory must be -prepared using the openssl c_rehash utility. This makes sense only when used -in combination with the \fICURLOPT_SSL_VERIFYPEER\fP option. If -\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_CAPATH\fP need not even -indicate an accessible path. The \fICURLOPT_CAPATH\fP function apparently -does not work in Windows due to some limitation in openssl. This option is -OpenSSL-specific and does nothing if libcurl is built to use GnuTLS. +CA certificates to verify the peer with. If libcurl is built against OpenSSL, +the certificate directory must be prepared using the openssl c_rehash utility. +This makes sense only when used in combination with the +\fICURLOPT_SSL_VERIFYPEER\fP option. If \fICURLOPT_SSL_VERIFYPEER\fP is zero, +\fICURLOPT_CAPATH\fP need not even indicate an accessible path. The +\fICURLOPT_CAPATH\fP function apparently does not work in Windows due to some +limitation in openssl. This option is OpenSSL-specific and does nothing if +libcurl is built to use GnuTLS. NSS-powered libcurl provides the option only +for backward compatibility. .IP CURLOPT_CRLFILE Pass a char * to a zero terminated string naming a file with the concatenation of CRL (in PEM format) to use in the certificate validation that occurs during -- cgit v1.2.1 From b35622f387e7c85d7eba7c8af1a9ee6dcbee5dc0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 19 Jan 2011 12:54:17 +0100 Subject: curl_easy_setopt.3: clarify VERIFYHOST/PEER Extended the descriptions somewhat and made the options get listed next to each other. --- docs/libcurl/curl_easy_setopt.3 | 41 ++++++++++++++++++++++------------------- 1 file changed, 22 insertions(+), 19 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index bd342a125..e6e412305 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1888,12 +1888,14 @@ CA certificates and you can specify alternate certificates with the When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification fails to prove that the certificate is authentic, the connection fails. When the -option is zero, the connection succeeds regardless. +option is zero, the peer certificate verification succeeds regardless. Authenticating the certificate is not by itself very useful. You typically want to ensure that the server, as authentically identified by its certificate, is the server you mean to be talking to. Use -\fICURLOPT_SSL_VERIFYHOST\fP to control that. +\fICURLOPT_SSL_VERIFYHOST\fP to control that. The check that the host name in +the certificate is valid for the host name you're connecting to is done +independently of the \fICURLOPT_SSL_VERIFYPEER\fP option. .IP CURLOPT_CAINFO Pass a char * to a zero terminated string naming a file holding one or more certificates to verify the peer with. This makes sense only when used in @@ -1951,20 +1953,6 @@ A specific error code (CURLE_SSL_CRL_BADFILE) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. A failure in certificate verification due to a revocation information 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 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) -.IP CURLOPT_RANDOM_FILE -Pass a char * to a zero terminated file name. The file will be used to read -from to seed the random engine for SSL. The more random the specified file is, -the more secure the SSL connection will become. -.IP CURLOPT_EGDSOCKET -Pass a char * to the zero terminated path name to the Entropy Gathering Daemon -socket. It will be used to seed the random engine for SSL. .IP CURLOPT_SSL_VERIFYHOST Pass a long as parameter. @@ -1988,10 +1976,25 @@ doesn't matter what name it says. (This is not ordinarily a useful setting). When the value is 0, the connection succeeds regardless of the names in the certificate. -The default, since 7.10, is 2. +The default value for this option is 2. -This option controls checking the server's claimed identity. The server could -be lying. To control lying, see \fICURLOPT_SSL_VERIFYPEER\fP. +This option controls checking the server's certificate's claimed identity. +The server could be lying. To control lying, see +\fICURLOPT_SSL_VERIFYPEER\fP. +.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 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) +.IP CURLOPT_RANDOM_FILE +Pass a char * to a zero terminated file name. The file will be used to read +from to seed the random engine for SSL. The more random the specified file is, +the more secure the SSL connection will become. +.IP CURLOPT_EGDSOCKET +Pass a char * to the zero terminated path name to the Entropy Gathering Daemon +socket. It will be used to seed the random engine for SSL. .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, -- cgit v1.2.1 From 4f13340ab8be7baa0fe6210bb3a19b8994875fd8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 19 Jan 2011 13:19:44 +0100 Subject: CURLOPT_SSL_VERIFYPEER: more clarifications The default value is 1. curl _uses_ a default CA bundle, it doesn't install one. Drop the references to 7.10 as that is now >8 years old! --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e6e412305..95772d2e3 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1872,19 +1872,19 @@ Force SSLv2 Force SSLv3 .RE .IP CURLOPT_SSL_VERIFYPEER -Pass a long as parameter. +Pass a long as parameter. By default, curl assumes a value of 1. This option determines whether curl verifies the authenticity of the peer's -certificate. A value of 1 means curl verifies; zero means it doesn't. The -default is nonzero, but before 7.10, it was zero. +certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't. When negotiating an SSL connection, the server sends a certificate indicating its identity. Curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority -(CA) certificates you supply. As of 7.10, curl installs a default bundle of -CA certificates and you can specify alternate certificates with the -\fICURLOPT_CAINFO\fP option or the \fICURLOPT_CAPATH\fP option. +(CA) certificates you supply. curl uses a default bundle of CA certificates +(the path for that is determined at build time) and you can specify alternate +certificates with the \fICURLOPT_CAINFO\fP option or the \fICURLOPT_CAPATH\fP +option. When \fICURLOPT_SSL_VERIFYPEER\fP is nonzero, and the verification fails to prove that the certificate is authentic, the connection fails. When the -- cgit v1.2.1 From c0a2ee65a4d266c5e223723b677c6a532dc7182b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 19 Jan 2011 22:45:02 +0100 Subject: symbols-in-versions: add the new TLSAUTH-SRP symbols --- docs/libcurl/symbols-in-versions | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index e22b6251e..bbd629d66 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -123,6 +123,7 @@ CURLE_TFTP_NOSUCHUSER 7.15.0 CURLE_TFTP_NOTFOUND 7.15.0 CURLE_TFTP_PERM 7.15.0 CURLE_TFTP_UNKNOWNID 7.15.0 +CURLE_TLSAUTH_FAILED 7.21.4 CURLE_TOO_MANY_REDIRECTS 7.5 CURLE_UNKNOWN_TELNET_OPTION 7.7 CURLE_UNSUPPORTED_PROTOCOL 7.1 @@ -484,6 +485,9 @@ CURLOPT_TIMECONDITION 7.1 CURLOPT_TIMEOUT 7.1 CURLOPT_TIMEOUT_MS 7.16.2 CURLOPT_TIMEVALUE 7.1 +CURLOPT_TLSAUTH_PASSWORD 7.21.4 +CURLOPT_TLSAUTH_TYPE 7.21.4 +CURLOPT_TLSAUTH_USERNAME 7.21.4 CURLOPT_TRANSFERTEXT 7.11.1 CURLOPT_UNRESTRICTED_AUTH 7.10.4 CURLOPT_UPLOAD 7.1 @@ -650,6 +654,8 @@ CURL_TIMECOND_IFMODSINCE 7.9.7 CURL_TIMECOND_IFUNMODSINCE 7.9.7 CURL_TIMECOND_LASTMOD 7.9.7 CURL_TIMECOND_NONE 7.9.7 +CURL_TLSAUTH_NONE 7.21.4 +CURL_TLSAUTH_SRP 7.21.4 CURL_VERSION_ASYNCHDNS 7.10.7 CURL_VERSION_CONV 7.15.4 CURL_VERSION_CURLDEBUG 7.19.6 @@ -664,4 +670,5 @@ CURL_VERSION_NTLM 7.10.6 CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 +CURL_VERSION_TLSAUTH_SRP 7.21.4 CURL_WRITEFUNC_PAUSE 7.18.0 -- cgit v1.2.1 From 3427bece89ee00fdf82519e584a971f97c9f2071 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 21 Jan 2011 14:27:10 -0800 Subject: Mention axTLS in some more documentation --- docs/libcurl/libcurl-tutorial.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 72f002963..1efd6fbb3 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -283,6 +283,10 @@ yassl Required actions unknown. +axTLS + + 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 not honored during the DNS lookup - which you can work around by building -- cgit v1.2.1 From b89122a2bf1663f16d0977977c83320470c6d438 Mon Sep 17 00:00:00 2001 From: Dave Reisner Date: Sat, 29 Jan 2011 22:41:07 -0500 Subject: file: add support for CURLOPT_TIMECONDITION --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 95772d2e3..8c772c6e5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1648,8 +1648,8 @@ given limit. This concerns both FTP and HTTP transfers. .IP CURLOPT_TIMECONDITION Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE\fP time value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP -or \fICURL_TIMECOND_IFUNMODSINCE\fP. This feature applies to HTTP, FTP, and -RTSP. +or \fICURL_TIMECOND_IFUNMODSINCE\fP. This feature applies to HTTP, FTP, RTSP, +and FILE. 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 not -- cgit v1.2.1 From ae7fe3b7f45564569324e07ffeb1be4eabfef713 Mon Sep 17 00:00:00 2001 From: Quinn Slack Date: Wed, 9 Feb 2011 23:33:06 +0100 Subject: TLS-SRP: new options documented --- docs/libcurl/curl_easy_setopt.3 | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 8c772c6e5..7f3e27dd1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -870,6 +870,29 @@ This is a meta symbol. Or this value together with a single specific auth value to force libcurl to probe for un-restricted auth and if not, only that single auth algorithm is acceptable. (Added in 7.21.3) .RE +.IP CURLOPT_TLSAUTH_TYPE +Pass a long as parameter, which is set to a bitmask, to tell libcurl which +authentication method(s) you want it to use for TLS authentication. +.RS +.IP CURLOPT_TLSAUTH_SRP +TLS-SRP authentication. Secure Remote Password authentication for TLS is +defined in RFC 5054 and provides mutual authentication if both sides have a +shared secret. To use TLS-SRP, you must also set the +\fICURLOPT_TLSAUTH_USERNAME\fP and \fICURLOPT_TLSAUTH_PASSWORD\fP options. + +You need to build libcurl with GnuTLS and with TLS-SRP support for this to +work. (Added in 7.21.4) +.RE +.IP CURLOPT_TLSAUTH_USERNAME +Pass a char * as parameter, which should point to the zero-terminated username +to use for the TLS authentication method specified with the +\fICURLOPT_TLSAUTH_TYPE\fP option. Requires that the +\fICURLOPT_TLS_PASSWORD\fP option also be set. (Added in 7.21.4) +.IP CURLOPT_TLSAUTH_PASSWORD +Pass a char * as parameter, which should point to the zero-terminated password +to use for the TLS authentication method specified with the +\fICURLOPT_TLSAUTH_TYPE\fP option. Requires that the +\fICURLOPT_TLS_USERNAME\fP option also be set. (Added in 7.21.4) .IP CURLOPT_PROXYAUTH 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 -- cgit v1.2.1 From 3cffcba3d0cf78a2aa17197059f810f5a7ce05a5 Mon Sep 17 00:00:00 2001 From: Quinn Slack Date: Wed, 9 Feb 2011 23:34:30 +0100 Subject: CURLE_TLSAUTH_FAILED: removed On second thought, I think CURLE_TLSAUTH_FAILED should be eliminated. It was only being raised when an internal error occurred while allocating or setting the GnuTLS SRP client credentials struct. For TLS authentication failures, the general CURLE_SSL_CONNECT_ERROR seems appropriate; its error string already includes "passwords" as a possible cause. Having a separate TLS auth error code might also cause people to think that a TLS auth failure means the wrong username or password was entered, when it could also be a sign of a man-in-the-middle attack. --- docs/libcurl/symbols-in-versions | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index bbd629d66..bacf5277e 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -123,7 +123,6 @@ CURLE_TFTP_NOSUCHUSER 7.15.0 CURLE_TFTP_NOTFOUND 7.15.0 CURLE_TFTP_PERM 7.15.0 CURLE_TFTP_UNKNOWNID 7.15.0 -CURLE_TLSAUTH_FAILED 7.21.4 CURLE_TOO_MANY_REDIRECTS 7.5 CURLE_UNKNOWN_TELNET_OPTION 7.7 CURLE_UNSUPPORTED_PROTOCOL 7.1 -- cgit v1.2.1 From 4c33b0a200ec8ce2a7446a361a389775c6a2a0a0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 17 Feb 2011 22:34:18 +0100 Subject: SOCKOPTFUNCTION: documented new return codes --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ docs/libcurl/symbols-in-versions | 3 +++ 2 files changed, 7 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7f3e27dd1..cb23c2396 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -271,6 +271,10 @@ discretion. Return 0 (zero) from the callback on success. Return 1 from the callback function to signal an unrecoverable error to the library and it will close the socket and return \fICURLE_COULDNT_CONNECT\fP. (Option added in 7.15.6.) + +Added in 7.21.5, the callback function may return +\fICURL_SOCKOPT_ALREADY_CONNECTED\fP, which tells libcurl that the socket is +in fact already connected and then libcurl will not attempt to connect it. .IP CURLOPT_SOCKOPTDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index bacf5277e..1a8b04334 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -671,3 +671,6 @@ CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 CURL_VERSION_TLSAUTH_SRP 7.21.4 CURL_WRITEFUNC_PAUSE 7.18.0 +CURL_SOCKOPT_OK 7.21.5 +CURL_SOCKOPT_ERROR 7.21.5 +CURL_SOCKOPT_ALREADY_CONNECTED 7.21.5 -- cgit v1.2.1 From d9805c5b2bf5e7cc9980306c5720f2d7f0402225 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 17 Feb 2011 23:22:11 +0100 Subject: symbols-in-versions: sorted I forgot to sort it when I added the CURL_SOCKOPT_* symbols --- docs/libcurl/symbols-in-versions | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 1a8b04334..704838fa5 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -645,6 +645,9 @@ CURL_SEEKFUNC_FAIL 7.19.5 CURL_SEEKFUNC_OK 7.19.5 CURL_SOCKET_BAD 7.14.0 CURL_SOCKET_TIMEOUT 7.14.0 +CURL_SOCKOPT_ALREADY_CONNECTED 7.21.5 +CURL_SOCKOPT_ERROR 7.21.5 +CURL_SOCKOPT_OK 7.21.5 CURL_SSLVERSION_DEFAULT 7.9.2 CURL_SSLVERSION_SSLv2 7.9.2 CURL_SSLVERSION_SSLv3 7.9.2 @@ -671,6 +674,3 @@ CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 CURL_VERSION_TLSAUTH_SRP 7.21.4 CURL_WRITEFUNC_PAUSE 7.18.0 -CURL_SOCKOPT_OK 7.21.5 -CURL_SOCKOPT_ERROR 7.21.5 -CURL_SOCKOPT_ALREADY_CONNECTED 7.21.5 -- cgit v1.2.1 From 073ce06379818c1bc7cf513ca0595efeee5c1c72 Mon Sep 17 00:00:00 2001 From: Julien Chaffraix Date: Sun, 20 Feb 2011 21:13:19 -0800 Subject: curl_easy_setopt.3: Removed wrong reference to CURLOPT_USERPASSWORD. CURLOPT_HTTPAUTH was mentioning CURLOPT_USERPASSWORD instead of CURLOPT_PASSWORD. Reported by: Mike Henshaw --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index cb23c2396..a94f40fcc 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -827,7 +827,7 @@ below. If more than one bit is set, libcurl will first query the site to see 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. +with the \fICURLOPT_USERNAME\fP and the \fICURLOPT_PASSWORD\fP options. (Added in 7.10.6) .RS .IP CURLAUTH_BASIC -- cgit v1.2.1 From 10cea49a467e4c0547ed2f827d7f86737892479c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 21 Feb 2011 13:51:26 +0100 Subject: CURLOPT_SSH_KEYFUNCTION: requires *SSH_KNOWNHOSTS Extend the docs to clarify that CURLOPT_SSH_KEYFUNCTION is only called if the known hosts option is also correctly set! --- docs/libcurl/curl_easy_setopt.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a94f40fcc..56a54a9db 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2088,7 +2088,10 @@ behavior on host and key (mis)matching. (Added in 7.19.6) .IP CURLOPT_SSH_KEYFUNCTION Pass a pointer to a curl_sshkeycallback function. It gets called when the known_host matching has been done, to allow the application to act and decide -for libcurl how to proceed. It gets passed the CURL handle, the key from the +for libcurl how to proceed. The callback will only be called if +\fICURLOPT_SSH_KNOWNHOSTS\fP is also set. + +The curl_sshkeycallback function gets passed the CURL handle, the key from the known_hosts file, the key from the remote site, info from libcurl on the matching status and a custom pointer (set with \fICURLOPT_SSH_KEYDATA\fP). It MUST return one of the following return codes to tell libcurl how to act: -- cgit v1.2.1 From 029136da6054a3b2d6cb36b3b4f2ed34f83e010a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 12 Mar 2011 00:14:32 +0100 Subject: source header: added to more files --- docs/libcurl/Makefile.am | 19 +++++++++++++++++++ docs/libcurl/curl_easy_duphandle.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_easy_init.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_easy_pause.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_easy_perform.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_easy_reset.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_easy_strerror.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_escape.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_formadd.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_formfree.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_formget.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_free.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_getdate.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_getenv.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_global_cleanup.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_global_init.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_global_init_mem.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_mprintf.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_add_handle.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_assign.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_cleanup.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_fdset.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_info_read.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_init.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_perform.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_remove_handle.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_setopt.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_socket.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_socket_action.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_multi_strerror.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_multi_timeout.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_share_cleanup.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_share_init.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_share_setopt.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_share_strerror.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_slist_append.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_slist_free_all.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_strequal.3 | 22 +++++++++++++++++++++- docs/libcurl/curl_unescape.3 | 24 +++++++++++++++++++++--- docs/libcurl/curl_version.3 | 24 +++++++++++++++++++++--- docs/libcurl/libcurl-easy.3 | 24 +++++++++++++++++++++--- docs/libcurl/libcurl-share.3 | 24 +++++++++++++++++++++--- docs/libcurl/libcurl.3 | 22 +++++++++++++++++++++- 43 files changed, 901 insertions(+), 82 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 3f949d66c..45c8fee97 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -1,5 +1,24 @@ +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| # +# Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. # +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### AUTOMAKE_OPTIONS = foreign no-dependencies diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3 index 3fae30e6a..e53ced48b 100644 --- a/docs/libcurl/curl_easy_duphandle.3 +++ b/docs/libcurl/curl_easy_duphandle.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_duphandle 3 "18 September 2001" "libcurl 7.9" "libcurl Manual" .SH NAME curl_easy_duphandle - Clone a libcurl session handle diff --git a/docs/libcurl/curl_easy_init.3 b/docs/libcurl/curl_easy_init.3 index 478db5c03..837ba32a5 100644 --- a/docs/libcurl/curl_easy_init.3 +++ b/docs/libcurl/curl_easy_init.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_init 3 "4 March 2002" "libcurl 7.8.1" "libcurl Manual" .SH NAME curl_easy_init - Start a libcurl easy session diff --git a/docs/libcurl/curl_easy_pause.3 b/docs/libcurl/curl_easy_pause.3 index 4d16ecffe..25d67bfbb 100644 --- a/docs/libcurl/curl_easy_pause.3 +++ b/docs/libcurl/curl_easy_pause.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_pause 3 "17 Dec 2007" "libcurl 7.18.0" "libcurl Manual" .SH NAME curl_easy_pause - pause and unpause a connection diff --git a/docs/libcurl/curl_easy_perform.3 b/docs/libcurl/curl_easy_perform.3 index 1ed006b0b..8f8517f22 100644 --- a/docs/libcurl/curl_easy_perform.3 +++ b/docs/libcurl/curl_easy_perform.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_perform 3 "5 Mar 2001" "libcurl 7.7" "libcurl Manual" .SH NAME curl_easy_perform - Perform a file transfer diff --git a/docs/libcurl/curl_easy_reset.3 b/docs/libcurl/curl_easy_reset.3 index 4652f7e60..592d3ed5c 100644 --- a/docs/libcurl/curl_easy_reset.3 +++ b/docs/libcurl/curl_easy_reset.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_reset 3 "31 July 2004" "libcurl 7.12.1" "libcurl Manual" .SH NAME curl_easy_reset - reset all options of a libcurl session handle diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 index 1afbd12bf..be95f0ddc 100644 --- a/docs/libcurl/curl_easy_strerror.3 +++ b/docs/libcurl/curl_easy_strerror.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_easy_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_easy_strerror - return string describing error code diff --git a/docs/libcurl/curl_escape.3 b/docs/libcurl/curl_escape.3 index 59906150e..75fd51f2d 100644 --- a/docs/libcurl/curl_escape.3 +++ b/docs/libcurl/curl_escape.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_escape 3 "6 March 2002" "libcurl 7.9" "libcurl Manual" .SH NAME curl_escape - URL encodes the given string diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 06757ed0a..bba0c083e 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 2fba295ab..7c825c980 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_formfree 3 "6 April 2001" "libcurl 7.7.1" "libcurl Manual" .SH NAME curl_formfree - free a previously build multipart/formdata HTTP POST chain diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index b0dd8fead..b214a50c2 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_formget 3 "20 June 2006" "libcurl 7.15.5" "libcurl Manual" .SH NAME curl_formget - serialize a previously built multipart/formdata HTTP POST chain diff --git a/docs/libcurl/curl_free.3 b/docs/libcurl/curl_free.3 index f8546935f..08ec9b6b3 100644 --- a/docs/libcurl/curl_free.3 +++ b/docs/libcurl/curl_free.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_free 3 "12 Aug 2003" "libcurl 7.10" "libcurl Manual" .SH NAME curl_free - reclaim memory that has been obtained through a libcurl call diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 73cd3ef1d..65eed9c57 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_getdate 3 "12 Aug 2005" "libcurl 7.0" "libcurl Manual" .SH NAME curl_getdate - Convert a date string to number of seconds since January 1, diff --git a/docs/libcurl/curl_getenv.3 b/docs/libcurl/curl_getenv.3 index 74132921a..33554476a 100644 --- a/docs/libcurl/curl_getenv.3 +++ b/docs/libcurl/curl_getenv.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_getenv 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_getenv - return value for environment name diff --git a/docs/libcurl/curl_global_cleanup.3 b/docs/libcurl/curl_global_cleanup.3 index 9ca11d6ff..83a54e467 100644 --- a/docs/libcurl/curl_global_cleanup.3 +++ b/docs/libcurl/curl_global_cleanup.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_global_cleanup 3 "17 Feb 2006" "libcurl 7.8" "libcurl Manual" .SH NAME curl_global_cleanup - global libcurl cleanup diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index e732911f8..5fff6c556 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_global_init 3 "11 May 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_global_init - Global libcurl initialisation diff --git a/docs/libcurl/curl_global_init_mem.3 b/docs/libcurl/curl_global_init_mem.3 index 57ae6aeea..d13a17c6e 100644 --- a/docs/libcurl/curl_global_init_mem.3 +++ b/docs/libcurl/curl_global_init_mem.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_global_init_mem 3 "10 May 2004" "libcurl 7.12.0" "libcurl Manual" .SH NAME curl_global_init_mem - Global libcurl initialisation with memory callbacks diff --git a/docs/libcurl/curl_mprintf.3 b/docs/libcurl/curl_mprintf.3 index ade7f65f5..cbf10e1ab 100644 --- a/docs/libcurl/curl_mprintf.3 +++ b/docs/libcurl/curl_mprintf.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_printf 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf diff --git a/docs/libcurl/curl_multi_add_handle.3 b/docs/libcurl/curl_multi_add_handle.3 index 85f199ed9..bae2c90fe 100644 --- a/docs/libcurl/curl_multi_add_handle.3 +++ b/docs/libcurl/curl_multi_add_handle.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_add_handle 3 "4 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_add_handle - add an easy handle to a multi session diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3 index 3e15d73e6..0b580fe27 100644 --- a/docs/libcurl/curl_multi_assign.3 +++ b/docs/libcurl/curl_multi_assign.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_assign 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_assign \- set data to association with an internal socket diff --git a/docs/libcurl/curl_multi_cleanup.3 b/docs/libcurl/curl_multi_cleanup.3 index d40173c99..e83c9f01b 100644 --- a/docs/libcurl/curl_multi_cleanup.3 +++ b/docs/libcurl/curl_multi_cleanup.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_cleanup 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_cleanup - close down a multi session diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index 79281056e..fadc53812 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_fdset 3 "2 Jan 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_fdset - extracts file descriptor information from a multi handle diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3 index 9ff08e707..875176486 100644 --- a/docs/libcurl/curl_multi_info_read.3 +++ b/docs/libcurl/curl_multi_info_read.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_info_read 3 "18 Dec 2004" "libcurl 7.10.3" "libcurl Manual" .SH NAME curl_multi_info_read - read multi stack informationals diff --git a/docs/libcurl/curl_multi_init.3 b/docs/libcurl/curl_multi_init.3 index 0ac298efd..ca9374e15 100644 --- a/docs/libcurl/curl_multi_init.3 +++ b/docs/libcurl/curl_multi_init.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_init 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_init - create a multi handle diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index ede23905f..96ebb34e3 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_perform 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_perform - reads/writes available data from each easy handle diff --git a/docs/libcurl/curl_multi_remove_handle.3 b/docs/libcurl/curl_multi_remove_handle.3 index efecb109e..ad6d2bac8 100644 --- a/docs/libcurl/curl_multi_remove_handle.3 +++ b/docs/libcurl/curl_multi_remove_handle.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_remove_handle 3 "6 March 2002" "libcurl 7.9.5" "libcurl Manual" .SH NAME curl_multi_remove_handle - remove an easy handle from a multi session diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index a1cbb70dc..baaaaeac0 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_setopt 3 "10 Oct 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_setopt \- set options for a curl multi handle diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index 18b571c1c..6b262f292 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_socket \- reads/writes available data diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index 94e6f10a5..f93e914da 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_socket_action 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_socket_action \- reads/writes available data given an action diff --git a/docs/libcurl/curl_multi_strerror.3 b/docs/libcurl/curl_multi_strerror.3 index 2d9801d6a..40d0974c5 100644 --- a/docs/libcurl/curl_multi_strerror.3 +++ b/docs/libcurl/curl_multi_strerror.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_multi_strerror - return string describing error code diff --git a/docs/libcurl/curl_multi_timeout.3 b/docs/libcurl/curl_multi_timeout.3 index 9e53d0b8a..5ad8008ea 100644 --- a/docs/libcurl/curl_multi_timeout.3 +++ b/docs/libcurl/curl_multi_timeout.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_multi_timeout 3 "2 Jan 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_timeout \- how long to wait for action before proceeding diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 index 222197cc8..3af1707bb 100644 --- a/docs/libcurl/curl_share_cleanup.3 +++ b/docs/libcurl/curl_share_cleanup.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_share_cleanup 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME curl_share_cleanup - Clean up a shared object diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index 871519cb9..ce00d958e 100644 --- a/docs/libcurl/curl_share_init.3 +++ b/docs/libcurl/curl_share_init.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_share_init 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME curl_share_init - Create a shared object diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index 351360da9..5fff33d25 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_share_setopt 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl Manual" .SH NAME curl_share_setopt - Set options for a shared object diff --git a/docs/libcurl/curl_share_strerror.3 b/docs/libcurl/curl_share_strerror.3 index 69087dbf2..f1bc39867 100644 --- a/docs/libcurl/curl_share_strerror.3 +++ b/docs/libcurl/curl_share_strerror.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_share_strerror 3 "26 Apr 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_share_strerror - return string describing error code diff --git a/docs/libcurl/curl_slist_append.3 b/docs/libcurl/curl_slist_append.3 index 5cca9b72e..529560e8a 100644 --- a/docs/libcurl/curl_slist_append.3 +++ b/docs/libcurl/curl_slist_append.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_slist_append 3 "19 Jun 2003" "libcurl 7.10.4" "libcurl Manual" .SH NAME curl_slist_append - add a string to an slist diff --git a/docs/libcurl/curl_slist_free_all.3 b/docs/libcurl/curl_slist_free_all.3 index ec1b3607b..fab3d6080 100644 --- a/docs/libcurl/curl_slist_free_all.3 +++ b/docs/libcurl/curl_slist_free_all.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_slist_free_all 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" .SH NAME curl_slist_free_all - free an entire curl_slist list diff --git a/docs/libcurl/curl_strequal.3 b/docs/libcurl/curl_strequal.3 index 8ab4234bc..ce575d7ac 100644 --- a/docs/libcurl/curl_strequal.3 +++ b/docs/libcurl/curl_strequal.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_strequal 3 "30 April 2004" "libcurl 7.12" "libcurl Manual" .SH NAME curl_strequal, curl_strnequal - case insensitive string comparisons diff --git a/docs/libcurl/curl_unescape.3 b/docs/libcurl/curl_unescape.3 index 9bb470f4e..2a24866d3 100644 --- a/docs/libcurl/curl_unescape.3 +++ b/docs/libcurl/curl_unescape.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_unescape 3 "22 March 2001" "libcurl 7.7" "libcurl Manual" .SH NAME curl_unescape - URL decodes the given string diff --git a/docs/libcurl/curl_version.3 b/docs/libcurl/curl_version.3 index 24793caeb..003329800 100644 --- a/docs/libcurl/curl_version.3 +++ b/docs/libcurl/curl_version.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_version 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" .SH NAME curl_version - returns the libcurl version string diff --git a/docs/libcurl/libcurl-easy.3 b/docs/libcurl/libcurl-easy.3 index 803e54244..698a4ce72 100644 --- a/docs/libcurl/libcurl-easy.3 +++ b/docs/libcurl/libcurl-easy.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH libcurl 3 "12 Aug 2003" "libcurl 7.10.7" "libcurl easy interface" .SH NAME libcurl-easy \- easy interface overview diff --git a/docs/libcurl/libcurl-share.3 b/docs/libcurl/libcurl-share.3 index 2e58c0ba6..fc624088e 100644 --- a/docs/libcurl/libcurl-share.3 +++ b/docs/libcurl/libcurl-share.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH libcurl-share 3 "8 Aug 2003" "libcurl 7.10.7" "libcurl share interface" .SH NAME libcurl-share \- how to use the share interface diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index c0b221fe7..d2dcd7838 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -1,4 +1,24 @@ -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH libcurl 3 "19 March 2002" "libcurl 7.9.6" "libcurl overview" .SH NAME libcurl \- client-side URL transfers -- cgit v1.2.1 From 806dbb022b8a595405a740131a30fa0cf4523645 Mon Sep 17 00:00:00 2001 From: Kamil Dudka Date: Tue, 15 Mar 2011 14:52:26 +0100 Subject: nss: do not ignore value of CURLOPT_SSL_VERIFYPEER When NSS-powered libcurl connected to a SSL server with CURLOPT_SSL_VERIFYPEER equal to zero, NSS remembered that the peer certificate was accepted by libcurl and did not ask the second time when connecting to the same server with CURLOPT_SSL_VERIFYPEER equal to one. This patch turns off the SSL session cache for the particular SSL socket if peer verification is disabled. In order to avoid any performance impact, the peer verification is completely skipped in that case, which makes it even faster than before. Bug: https://bugzilla.redhat.com/678580 --- docs/libcurl/curl_easy_setopt.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 56a54a9db..2dd536cf5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2007,7 +2007,10 @@ The default value for this option is 2. This option controls checking the server's certificate's claimed identity. The server could be lying. To control lying, see -\fICURLOPT_SSL_VERIFYPEER\fP. +\fICURLOPT_SSL_VERIFYPEER\fP. If libcurl is built against NSS and +\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_SSL_VERIFYHOST\fP +is ignored. + .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 -- cgit v1.2.1 From 42d95bcc44a1ec8b4066eb2d86948a198aa7e227 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 17 Mar 2011 13:42:36 +0100 Subject: symbols-in-versions: 2 corrections CURLE_CHUNK_FAILED and CURLE_FTP_BAD_FILE_LIST were introduced in 7.21.0, not 7.20.1 --- docs/libcurl/symbols-in-versions | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 704838fa5..3ae28d747 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -35,7 +35,7 @@ CURLE_BAD_CONTENT_ENCODING 7.10 CURLE_BAD_DOWNLOAD_RESUME 7.10 CURLE_BAD_FUNCTION_ARGUMENT 7.1 CURLE_BAD_PASSWORD_ENTERED - 7.17.0 -CURLE_CHUNK_FAILED 7.20.1 +CURLE_CHUNK_FAILED 7.21.0 CURLE_CONV_FAILED 7.15.4 CURLE_CONV_REQD 7.15.4 CURLE_COULDNT_CONNECT 7.1 @@ -47,7 +47,7 @@ CURLE_FILE_COULDNT_READ_FILE 7.1 CURLE_FTP_ACCESS_DENIED 7.1 CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 7.1 -CURLE_FTP_BAD_FILE_LIST 7.20.1 +CURLE_FTP_BAD_FILE_LIST 7.21.0 CURLE_FTP_CANT_GET_HOST 7.1 CURLE_FTP_CANT_RECONNECT 7.1 7.17.0 CURLE_FTP_COULDNT_GET_SIZE 7.1 7.17.0 -- cgit v1.2.1 From 929aeed38618fe96f6105b61c10feedc81257dbb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 17 Mar 2011 15:25:12 +0100 Subject: symbols-in-versions: remove duplicates --- docs/libcurl/symbols-in-versions | 10 ---------- 1 file changed, 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 3ae28d747..07979cd06 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -45,7 +45,6 @@ CURLE_FAILED_INIT 7.1 CURLE_FILESIZE_EXCEEDED 7.10.8 CURLE_FILE_COULDNT_READ_FILE 7.1 CURLE_FTP_ACCESS_DENIED 7.1 -CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 7.1 CURLE_FTP_BAD_FILE_LIST 7.21.0 CURLE_FTP_CANT_GET_HOST 7.1 @@ -167,11 +166,8 @@ CURLFORM_PTRCONTENTS 7.9.1 CURLFORM_PTRNAME 7.9.1 CURLFORM_STREAM 7.18.2 CURLFTPAUTH_DEFAULT 7.12.2 -CURLFTPAUTH_DEFAULT 7.12.2 -CURLFTPAUTH_SSL 7.12.2 CURLFTPAUTH_SSL 7.12.2 CURLFTPAUTH_TLS 7.12.2 -CURLFTPAUTH_TLS 7.12.2 CURLFTPMETHOD_DEFAULT 7.15.1 CURLFTPMETHOD_MULTICWD 7.15.1 CURLFTPMETHOD_NOCWD 7.15.1 @@ -221,7 +217,6 @@ CURLINFO_PRETRANSFER_TIME 7.4.1 CURLINFO_PRIMARY_IP 7.19.0 CURLINFO_PRIMARY_PORT 7.21.0 CURLINFO_PRIVATE 7.10.3 -CURLINFO_PRIVATE 7.10.3 CURLINFO_PROXYAUTH_AVAIL 7.10.8 CURLINFO_REDIRECT_COUNT 7.9.7 CURLINFO_REDIRECT_TIME 7.9.7 @@ -467,7 +462,6 @@ CURLOPT_SSLENGINE 7.9.3 CURLOPT_SSLENGINE_DEFAULT 7.9.3 CURLOPT_SSLKEY 7.9.3 CURLOPT_SSLKEYPASSWD 7.17.0 -CURLOPT_SSLKEYPASSWD 7.17.0 CURLOPT_SSLKEYTYPE 7.9.3 CURLOPT_SSLVERSION 7.1 CURLOPT_SSL_CIPHER_LIST 7.9 @@ -560,12 +554,8 @@ CURLSSH_AUTH_NONE 7.16.1 CURLSSH_AUTH_PASSWORD 7.16.1 CURLSSH_AUTH_PUBLICKEY 7.16.1 CURLUSESSL_ALL 7.17.0 -CURLUSESSL_ALL 7.17.0 -CURLUSESSL_CONTROL 7.17.0 CURLUSESSL_CONTROL 7.17.0 CURLUSESSL_NONE 7.17.0 -CURLUSESSL_NONE 7.17.0 -CURLUSESSL_TRY 7.17.0 CURLUSESSL_TRY 7.17.0 CURLVERSION_FIRST 7.10 CURLVERSION_FOURTH 7.16.1 -- cgit v1.2.1 From e765afccb6b0b22fcc653cbaa938521997a27ec7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 19 Mar 2011 15:34:46 +0100 Subject: symbols-in-versions: many corrections Scanned with a tool that checked for mistakes and this is the subsequent cleanup. --- docs/libcurl/symbols-in-versions | 126 +++++++++++++++++++++------------------ 1 file changed, 69 insertions(+), 57 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 07979cd06..546f26d0b 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -34,7 +34,7 @@ CURLE_BAD_CALLING_ORDER 7.1 7.17.0 CURLE_BAD_CONTENT_ENCODING 7.10 CURLE_BAD_DOWNLOAD_RESUME 7.10 CURLE_BAD_FUNCTION_ARGUMENT 7.1 -CURLE_BAD_PASSWORD_ENTERED - 7.17.0 +CURLE_BAD_PASSWORD_ENTERED 7.4.2 7.17.0 CURLE_CHUNK_FAILED 7.21.0 CURLE_CONV_FAILED 7.15.4 CURLE_CONV_REQD 7.15.4 @@ -60,7 +60,7 @@ CURLE_FTP_PARTIAL_FILE 7.1 7.1 CURLE_FTP_PORT_FAILED 7.1 CURLE_FTP_PRET_FAILED 7.20.0 CURLE_FTP_QUOTE_ERROR 7.1 7.17.0 -CURLE_FTP_SSL_FAILED - 7.17.0 +CURLE_FTP_SSL_FAILED 7.11.0 7.17.0 CURLE_FTP_USER_PASSWORD_INCORRECT 7.1 7.17.0 CURLE_FTP_WEIRD_227_FORMAT 7.1 CURLE_FTP_WEIRD_PASS_REPLY 7.1 @@ -71,7 +71,7 @@ CURLE_FTP_WRITE_ERROR 7.1 7.17.0 CURLE_FUNCTION_NOT_FOUND 7.1 CURLE_GOT_NOTHING 7.9.1 CURLE_HTTP_NOT_FOUND 7.1 -CURLE_HTTP_PORT_FAILED - 7.12.0 +CURLE_HTTP_PORT_FAILED 7.3 7.12.0 CURLE_HTTP_POST_ERROR 7.1 CURLE_HTTP_RANGE_ERROR 7.1 7.17.0 CURLE_HTTP_RETURNED_ERROR 7.10.3 @@ -83,7 +83,7 @@ CURLE_LIBRARY_NOT_FOUND 7.1 7.17.0 CURLE_LOGIN_DENIED 7.13.1 CURLE_MALFORMAT_USER 7.1 7.17.0 CURLE_OK 7.1 -CURLE_OPERATION_TIMEDOUT 7.17.0 +CURLE_OPERATION_TIMEDOUT 7.10.2 CURLE_OPERATION_TIMEOUTED 7.1 7.17.0 CURLE_OUT_OF_MEMORY 7.1 CURLE_PARTIAL_FILE 7.1 @@ -91,16 +91,16 @@ CURLE_PEER_FAILED_VERIFICATION 7.17.1 CURLE_QUOTE_ERROR 7.17.0 CURLE_RANGE_ERROR 7.17.0 CURLE_READ_ERROR 7.1 -CURLE_RECV_ERROR 7.13.0 +CURLE_RECV_ERROR 7.10 CURLE_REMOTE_ACCESS_DENIED 7.17.0 CURLE_REMOTE_DISK_FULL 7.17.0 CURLE_REMOTE_FILE_EXISTS 7.17.0 CURLE_REMOTE_FILE_NOT_FOUND 7.16.1 CURLE_RTSP_CSEQ_ERROR 7.20.0 CURLE_RTSP_SESSION_ERROR 7.20.0 -CURLE_SEND_ERROR 7.13.0 +CURLE_SEND_ERROR 7.10 CURLE_SEND_FAIL_REWIND 7.12.3 -CURLE_SHARE_IN_USE - 7.17.0 +CURLE_SHARE_IN_USE 7.9.6 7.17.0 CURLE_SSH 7.16.1 CURLE_SSL_CACERT 7.10 CURLE_SSL_CACERT_BADFILE 7.16.0 @@ -108,11 +108,11 @@ CURLE_SSL_CERTPROBLEM 7.10 CURLE_SSL_CIPHER 7.10 CURLE_SSL_CONNECT_ERROR 7.1 CURLE_SSL_CRL_BADFILE 7.19.0 -CURLE_SSL_ENGINE_INITFAILED 7.13.0 +CURLE_SSL_ENGINE_INITFAILED 7.12.3 CURLE_SSL_ENGINE_NOTFOUND 7.9.3 CURLE_SSL_ENGINE_SETFAILED 7.9.3 CURLE_SSL_ISSUER_ERROR 7.19.0 -CURLE_SSL_PEER_CERTIFICATE - 7.17.1 +CURLE_SSL_PEER_CERTIFICATE 7.8 7.17.1 CURLE_SSL_SHUTDOWN_FAILED 7.16.1 CURLE_TELNET_OPTION_SYNTAX 7.7 CURLE_TFTP_DISKFULL 7.15.0 7.17.0 @@ -148,33 +148,35 @@ CURLFINFOFLAG_KNOWN_SIZE 7.21.0 CURLFINFOFLAG_KNOWN_TIME 7.21.0 CURLFINFOFLAG_KNOWN_UID 7.21.0 CURLFORM_ARRAY 7.9.1 +CURLFORM_ARRAY_END 7.9.1 7.9.6 +CURLFORM_ARRAY_START 7.9.1 7.9.6 CURLFORM_BUFFER 7.9.8 CURLFORM_BUFFERLENGTH 7.9.8 CURLFORM_BUFFERPTR 7.9.8 CURLFORM_CONTENTHEADER 7.9.3 -CURLFORM_CONTENTSLENGTH 7.9.1 -CURLFORM_CONTENTTYPE 7.9.1 -CURLFORM_COPYCONTENTS 7.9.1 -CURLFORM_COPYNAME 7.9.1 -CURLFORM_END 7.9.1 -CURLFORM_FILE 7.9.1 +CURLFORM_CONTENTSLENGTH 7.9 +CURLFORM_CONTENTTYPE 7.9 +CURLFORM_COPYCONTENTS 7.9 +CURLFORM_COPYNAME 7.9 +CURLFORM_END 7.9 +CURLFORM_FILE 7.9 CURLFORM_FILECONTENT 7.9.1 CURLFORM_FILENAME 7.9.6 -CURLFORM_NAMELENGTH 7.9.1 -CURLFORM_NOTHING 7.9.1 -CURLFORM_PTRCONTENTS 7.9.1 -CURLFORM_PTRNAME 7.9.1 +CURLFORM_NAMELENGTH 7.9 +CURLFORM_NOTHING 7.9 +CURLFORM_PTRCONTENTS 7.9 +CURLFORM_PTRNAME 7.9 CURLFORM_STREAM 7.18.2 CURLFTPAUTH_DEFAULT 7.12.2 CURLFTPAUTH_SSL 7.12.2 CURLFTPAUTH_TLS 7.12.2 -CURLFTPMETHOD_DEFAULT 7.15.1 -CURLFTPMETHOD_MULTICWD 7.15.1 -CURLFTPMETHOD_NOCWD 7.15.1 -CURLFTPMETHOD_SINGLECWD 7.15.1 -CURLFTPSSL_ALL - 7.17.0 -CURLFTPSSL_CCC_ACTIVE 7.16.1 -CURLFTPSSL_CCC_NONE 7.16.1 +CURLFTPMETHOD_DEFAULT 7.15.3 +CURLFTPMETHOD_MULTICWD 7.15.3 +CURLFTPMETHOD_NOCWD 7.15.3 +CURLFTPMETHOD_SINGLECWD 7.15.3 +CURLFTPSSL_ALL 7.11.0 7.17.0 +CURLFTPSSL_CCC_ACTIVE 7.16.2 +CURLFTPSSL_CCC_NONE 7.16.2 CURLFTPSSL_CCC_PASSIVE 7.16.1 CURLFTPSSL_CONTROL 7.11.0 7.17.0 CURLFTPSSL_NONE 7.11.0 7.17.0 @@ -193,8 +195,8 @@ CURLINFO_COOKIELIST 7.14.1 CURLINFO_DATA_IN 7.9.6 CURLINFO_DATA_OUT 7.9.6 CURLINFO_DOUBLE 7.4.1 -CURLINFO_EFFECTIVE_URL 7.3 -CURLINFO_END 7.4.1 +CURLINFO_EFFECTIVE_URL 7.4 +CURLINFO_END 7.9.6 CURLINFO_FILETIME 7.5 CURLINFO_FTP_ENTRY_PATH 7.15.4 CURLINFO_HEADER_IN 7.9.6 @@ -279,7 +281,7 @@ CURLOPTTYPE_LONG 7.1 CURLOPTTYPE_OBJECTPOINT 7.1 CURLOPTTYPE_OFF_T 7.11.0 CURLOPT_ADDRESS_SCOPE 7.19.0 -CURLOPT_APPEND 7.16.4 +CURLOPT_APPEND 7.17.0 CURLOPT_AUTOREFERER 7.1 CURLOPT_BUFFERSIZE 7.10 CURLOPT_CAINFO 7.4.2 @@ -288,7 +290,7 @@ CURLOPT_CERTINFO 7.19.1 CURLOPT_CHUNK_BGN_FUNCTION 7.21.0 CURLOPT_CHUNK_DATA 7.21.0 CURLOPT_CHUNK_END_FUNCTION 7.21.0 -CURLOPT_CLOSEFUNCTION 7.7 7.11.1 7.15.4 +CURLOPT_CLOSEFUNCTION 7.7 7.11.1 7.15.5 CURLOPT_CLOSEPOLICY 7.7 7.16.1 CURLOPT_CONNECTTIMEOUT 7.7 CURLOPT_CONNECTTIMEOUT_MS 7.16.2 @@ -299,7 +301,7 @@ CURLOPT_CONV_TO_NETWORK_FUNCTION 7.15.4 CURLOPT_COOKIE 7.1 CURLOPT_COOKIEFILE 7.1 CURLOPT_COOKIEJAR 7.9 -CURLOPT_COOKIELIST 7.17.1 +CURLOPT_COOKIELIST 7.14.1 CURLOPT_COOKIESESSION 7.9.7 CURLOPT_COPYPOSTFIELDS 7.17.1 CURLOPT_CRLF 7.1 @@ -307,27 +309,26 @@ CURLOPT_CRLFILE 7.19.0 CURLOPT_CUSTOMREQUEST 7.1 CURLOPT_DEBUGDATA 7.9.6 CURLOPT_DEBUGFUNCTION 7.9.6 -CURLOPT_DIRLISTONLY 7.16.4 +CURLOPT_DIRLISTONLY 7.17.0 CURLOPT_DNS_CACHE_TIMEOUT 7.9.3 CURLOPT_DNS_USE_GLOBAL_CACHE 7.9.3 7.11.1 CURLOPT_EGDSOCKET 7.7 -CURLOPT_ENCODING 7.12.2 +CURLOPT_ENCODING 7.10 CURLOPT_ERRORBUFFER 7.1 CURLOPT_FAILONERROR 7.1 CURLOPT_FILE 7.1 7.9.7 CURLOPT_FILETIME 7.5 -CURLOPT_FLAGS 7.1 - 7.9.2 CURLOPT_FNMATCH_DATA 7.21.0 CURLOPT_FNMATCH_FUNCTION 7.21.0 CURLOPT_FOLLOWLOCATION 7.1 CURLOPT_FORBID_REUSE 7.7 CURLOPT_FRESH_CONNECT 7.7 CURLOPT_FTPAPPEND 7.1 7.16.4 -CURLOPT_FTPASCII 7.1 7.11.1 7.15.4 +CURLOPT_FTPASCII 7.1 7.11.1 7.15.5 CURLOPT_FTPLISTONLY 7.1 7.16.4 CURLOPT_FTPPORT 7.1 CURLOPT_FTPSSLAUTH 7.12.2 -CURLOPT_FTP_ACCOUNT 7.13.1 +CURLOPT_FTP_ACCOUNT 7.13.0 CURLOPT_FTP_ALTERNATIVE_TO_USER 7.15.5 CURLOPT_FTP_CREATE_MISSING_DIRS 7.10.7 CURLOPT_FTP_FILEMETHOD 7.15.1 @@ -347,7 +348,7 @@ CURLOPT_HTTPGET 7.8.1 CURLOPT_HTTPHEADER 7.1 CURLOPT_HTTPPOST 7.1 CURLOPT_HTTPPROXYTUNNEL 7.3 -CURLOPT_HTTPREQUEST 7.1 - 7.15.4 +CURLOPT_HTTPREQUEST 7.1 - 7.15.5 CURLOPT_HTTP_CONTENT_DECODING 7.16.2 CURLOPT_HTTP_TRANSFER_DECODING 7.16.2 CURLOPT_HTTP_VERSION 7.9.1 @@ -364,7 +365,7 @@ CURLOPT_IPRESOLVE 7.10.8 CURLOPT_ISSUERCERT 7.19.0 CURLOPT_KEYPASSWD 7.17.0 CURLOPT_KRB4LEVEL 7.3 7.17.0 -CURLOPT_KRBLEVEL 7.17.0 +CURLOPT_KRBLEVEL 7.16.4 CURLOPT_LOCALPORT 7.15.2 CURLOPT_LOCALPORTRANGE 7.15.2 CURLOPT_LOW_SPEED_LIMIT 7.1 @@ -377,7 +378,7 @@ CURLOPT_MAXFILESIZE_LARGE 7.11.0 CURLOPT_MAXREDIRS 7.5 CURLOPT_MAX_RECV_SPEED_LARGE 7.15.5 CURLOPT_MAX_SEND_SPEED_LARGE 7.15.5 -CURLOPT_MUTE 7.1 7.8 7.15.4 +CURLOPT_MUTE 7.1 7.8 7.15.5 CURLOPT_NETRC 7.1 CURLOPT_NETRC_FILE 7.11.0 CURLOPT_NEW_DIRECTORY_PERMS 7.16.4 @@ -386,12 +387,13 @@ CURLOPT_NOBODY 7.1 CURLOPT_NOPROGRESS 7.1 CURLOPT_NOPROXY 7.19.4 CURLOPT_NOSIGNAL 7.10 +CURLOPT_NOTHING 7.1.1 7.11.1 7.11.0 CURLOPT_OPENSOCKETDATA 7.17.1 CURLOPT_OPENSOCKETFUNCTION 7.17.1 -CURLOPT_PASSWDDATA 7.1 7.11.1 7.15.4 -CURLOPT_PASSWDFUNCTION 7.1 7.11.1 7.15.4 +CURLOPT_PASSWDDATA 7.4.2 7.11.1 7.15.5 +CURLOPT_PASSWDFUNCTION 7.4.2 7.11.1 7.15.5 CURLOPT_PASSWORD 7.19.1 -CURLOPT_PASV_POST 7.12.1 - 7.13.0 +CURLOPT_PASV_HOST 7.12.1 7.15.6 7.15.5 CURLOPT_PORT 7.1 CURLOPT_POST 7.1 CURLOPT_POST301 7.17.1 7.19.1 @@ -404,7 +406,6 @@ CURLOPT_PREQUOTE 7.9.5 CURLOPT_PRIVATE 7.10.3 CURLOPT_PROGRESSDATA 7.1 CURLOPT_PROGRESSFUNCTION 7.1 -CURLOPT_PROGRESSMODE 7.1 - 7.9.2 CURLOPT_PROTOCOLS 7.19.4 CURLOPT_PROXY 7.1 CURLOPT_PROXYAUTH 7.10.7 @@ -432,22 +433,22 @@ CURLOPT_RTSP_SERVER_CSEQ 7.20.0 CURLOPT_RTSP_SESSION_ID 7.20.0 CURLOPT_RTSP_STREAM_URI 7.20.0 CURLOPT_RTSP_TRANSPORT 7.20.0 -CURLOPT_SEEKDATA 7.18.1 -CURLOPT_SEEKFUNCTION 7.18.1 +CURLOPT_SEEKDATA 7.18.0 +CURLOPT_SEEKFUNCTION 7.18.0 CURLOPT_SERVER_RESPONSE_TIMEOUT 7.20.0 CURLOPT_SHARE 7.10 CURLOPT_SOCKOPTDATA 7.16.0 CURLOPT_SOCKOPTFUNCTION 7.16.0 CURLOPT_SOCKS5_GSSAPI_NEC 7.19.4 CURLOPT_SOCKS5_GSSAPI_SERVICE 7.19.4 -CURLOPT_SOURCE_HOST 7.12.1 - 7.13.0 -CURLOPT_SOURCE_PATH 7.12.1 - 7.13.0 -CURLOPT_SOURCE_PORT 7.12.1 - 7.13.0 -CURLOPT_SOURCE_POSTQUOTE 7.12.1 - 7.15.4 -CURLOPT_SOURCE_PREQUOTE 7.12.1 - 7.15.4 -CURLOPT_SOURCE_QUOTE 7.13.0 - 7.15.4 -CURLOPT_SOURCE_URL 7.13.0 - 7.15.4 -CURLOPT_SOURCE_USERPWD 7.12.1 - 7.15.4 +CURLOPT_SOURCE_HOST 7.12.1 - 7.15.5 +CURLOPT_SOURCE_PATH 7.12.1 - 7.15.5 +CURLOPT_SOURCE_PORT 7.12.1 - 7.15.5 +CURLOPT_SOURCE_POSTQUOTE 7.12.1 - 7.15.5 +CURLOPT_SOURCE_PREQUOTE 7.12.1 - 7.15.5 +CURLOPT_SOURCE_QUOTE 7.13.0 - 7.15.5 +CURLOPT_SOURCE_URL 7.13.0 - 7.15.5 +CURLOPT_SOURCE_USERPWD 7.12.1 - 7.15.5 CURLOPT_SSH_AUTH_TYPES 7.16.1 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 7.17.1 CURLOPT_SSH_KEYDATA 7.19.6 @@ -456,12 +457,12 @@ CURLOPT_SSH_KNOWNHOSTS 7.19.6 CURLOPT_SSH_PRIVATE_KEYFILE 7.16.1 CURLOPT_SSH_PUBLIC_KEYFILE 7.16.1 CURLOPT_SSLCERT 7.1 -CURLOPT_SSLCERTPASSWD 7.17.0 +CURLOPT_SSLCERTPASSWD 7.1.1 7.17.0 CURLOPT_SSLCERTTYPE 7.9.3 CURLOPT_SSLENGINE 7.9.3 CURLOPT_SSLENGINE_DEFAULT 7.9.3 CURLOPT_SSLKEY 7.9.3 -CURLOPT_SSLKEYPASSWD 7.17.0 +CURLOPT_SSLKEYPASSWD 7.9.3 7.17.0 CURLOPT_SSLKEYTYPE 7.9.3 CURLOPT_SSLVERSION 7.1 CURLOPT_SSL_CIPHER_LIST 7.9 @@ -481,7 +482,7 @@ CURLOPT_TIMEVALUE 7.1 CURLOPT_TLSAUTH_PASSWORD 7.21.4 CURLOPT_TLSAUTH_TYPE 7.21.4 CURLOPT_TLSAUTH_USERNAME 7.21.4 -CURLOPT_TRANSFERTEXT 7.11.1 +CURLOPT_TRANSFERTEXT 7.1.1 CURLOPT_UNRESTRICTED_AUTH 7.10.4 CURLOPT_UPLOAD 7.1 CURLOPT_URL 7.1 @@ -537,7 +538,7 @@ CURLPROXY_SOCKS5_HOSTNAME 7.18.0 CURLSHE_BAD_OPTION 7.10.3 CURLSHE_INVALID 7.10.3 CURLSHE_IN_USE 7.10.3 -CURLSHE_NOMEM 7.10.3 +CURLSHE_NOMEM 7.12.0 CURLSHE_OK 7.10.3 CURLSHOPT_LOCKFUNC 7.10.3 CURLSHOPT_NONE 7.10.3 @@ -570,6 +571,8 @@ CURL_CHUNK_END_FUNC_OK 7.21.0 CURL_CSELECT_ERR 7.16.3 CURL_CSELECT_IN 7.16.3 CURL_CSELECT_OUT 7.16.3 +CURL_EASY_NONE 7.14.0 - 7.15.4 +CURL_EASY_TIMEOUT 7.14.0 - 7.15.4 CURL_ERROR_SIZE 7.1 CURL_FNMATCHFUNC_FAIL 7.21.0 CURL_FNMATCHFUNC_MATCH 7.21.0 @@ -582,6 +585,7 @@ CURL_FORMADD_NULL 7.9.8 CURL_FORMADD_OK 7.9.8 CURL_FORMADD_OPTION_TWICE 7.9.8 CURL_FORMADD_UNKNOWN_OPTION 7.9.8 +CURL_FORMAT_OFF_T 7.11.1 CURL_GLOBAL_ALL 7.8 CURL_GLOBAL_DEFAULT 7.8 CURL_GLOBAL_NOTHING 7.8 @@ -593,6 +597,7 @@ CURL_HTTP_VERSION_NONE 7.9.1 CURL_IPRESOLVE_V4 7.10.8 CURL_IPRESOLVE_V6 7.10.8 CURL_IPRESOLVE_WHATEVER 7.10.8 +CURL_ISOCPP 7.10.2 CURL_LOCK_ACCESS_NONE 7.10.3 CURL_LOCK_ACCESS_SHARED 7.10.3 CURL_LOCK_ACCESS_SINGLE 7.10.3 @@ -602,6 +607,11 @@ CURL_LOCK_DATA_DNS 7.10.3 CURL_LOCK_DATA_NONE 7.10.3 CURL_LOCK_DATA_SHARE 7.10.4 CURL_LOCK_DATA_SSL_SESSION 7.10.3 +CURL_LOCK_TYPE_CONNECT 7.10 - 7.10.2 +CURL_LOCK_TYPE_COOKIE 7.10 - 7.10.2 +CURL_LOCK_TYPE_DNS 7.10 - 7.10.2 +CURL_LOCK_TYPE_NONE 7.10 - 7.10.2 +CURL_LOCK_TYPE_SSL_SESSION 7.10 - 7.10.2 CURL_MAX_HTTP_HEADER 7.19.7 CURL_MAX_WRITE_SIZE 7.9.7 CURL_NETRC_IGNORED 7.9.8 @@ -612,6 +622,8 @@ CURL_POLL_INOUT 7.14.0 CURL_POLL_NONE 7.14.0 CURL_POLL_OUT 7.14.0 CURL_POLL_REMOVE 7.14.0 +CURL_PROGRESS_BAR 7.1.1 - 7.4.1 +CURL_PROGRESS_STATS 7.1.1 - 7.4.1 CURL_READFUNC_ABORT 7.12.1 CURL_READFUNC_PAUSE 7.18.0 CURL_REDIR_GET_ALL 7.19.1 -- cgit v1.2.1 From a374d8f85d375b003dae21c76c6ebd0facf03428 Mon Sep 17 00:00:00 2001 From: Dave Reisner Date: Mon, 21 Mar 2011 13:18:57 -0400 Subject: libcurl.m4: Add missing quotes in AC_LINK_IFELSE This avoids warnings generated by autoconf 2.68. Signed-off-by: Dave Reisner --- docs/libcurl/libcurl.m4 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 952b79f4e..01a0575cc 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -146,7 +146,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], _libcurl_save_libs=$LIBS LIBS="$LIBCURL $LIBS" - AC_LINK_IFELSE(AC_LANG_PROGRAM([#include ],[ + AC_LINK_IFELSE([AC_LANG_PROGRAM([#include ],[ /* Try and use a few common options to force a failure if we are missing symbols or can't link. */ int x; @@ -157,7 +157,7 @@ x=CURLOPT_FILE; x=CURLOPT_ERRORBUFFER; x=CURLOPT_STDERR; x=CURLOPT_VERBOSE; -]),libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) +])],libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) CPPFLAGS=$_libcurl_save_cppflags LIBS=$_libcurl_save_libs -- cgit v1.2.1 From d02f444759eab5901a3d5439cf00657669b198c7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 24 Mar 2011 13:48:18 +0100 Subject: symbols-in-versions: make test 1119 happy --- docs/libcurl/symbols-in-versions | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 546f26d0b..fca917a97 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -148,8 +148,8 @@ CURLFINFOFLAG_KNOWN_SIZE 7.21.0 CURLFINFOFLAG_KNOWN_TIME 7.21.0 CURLFINFOFLAG_KNOWN_UID 7.21.0 CURLFORM_ARRAY 7.9.1 -CURLFORM_ARRAY_END 7.9.1 7.9.6 -CURLFORM_ARRAY_START 7.9.1 7.9.6 +CURLFORM_ARRAY_END 7.9.1 7.9.5 7.9.6 +CURLFORM_ARRAY_START 7.9.1 7.9.5 7.9.6 CURLFORM_BUFFER 7.9.8 CURLFORM_BUFFERLENGTH 7.9.8 CURLFORM_BUFFERPTR 7.9.8 @@ -585,7 +585,6 @@ CURL_FORMADD_NULL 7.9.8 CURL_FORMADD_OK 7.9.8 CURL_FORMADD_OPTION_TWICE 7.9.8 CURL_FORMADD_UNKNOWN_OPTION 7.9.8 -CURL_FORMAT_OFF_T 7.11.1 CURL_GLOBAL_ALL 7.8 CURL_GLOBAL_DEFAULT 7.8 CURL_GLOBAL_NOTHING 7.8 @@ -597,7 +596,6 @@ CURL_HTTP_VERSION_NONE 7.9.1 CURL_IPRESOLVE_V4 7.10.8 CURL_IPRESOLVE_V6 7.10.8 CURL_IPRESOLVE_WHATEVER 7.10.8 -CURL_ISOCPP 7.10.2 CURL_LOCK_ACCESS_NONE 7.10.3 CURL_LOCK_ACCESS_SHARED 7.10.3 CURL_LOCK_ACCESS_SINGLE 7.10.3 -- cgit v1.2.1 From 2531cd94a54292a12de0a6392788d310c1bd899a Mon Sep 17 00:00:00 2001 From: Peter Sylvester Date: Fri, 25 Mar 2011 23:09:28 +0100 Subject: TSL-SRP: enabled with OpenSSL If a new enough OpenSSL version is used, configure detects the TLS-SRP support and enables it. --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2dd536cf5..6166d5fd5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -884,8 +884,8 @@ defined in RFC 5054 and provides mutual authentication if both sides have a shared secret. To use TLS-SRP, you must also set the \fICURLOPT_TLSAUTH_USERNAME\fP and \fICURLOPT_TLSAUTH_PASSWORD\fP options. -You need to build libcurl with GnuTLS and with TLS-SRP support for this to -work. (Added in 7.21.4) +You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this +to work. (Added in 7.21.4) .RE .IP CURLOPT_TLSAUTH_USERNAME Pass a char * as parameter, which should point to the zero-terminated username -- cgit v1.2.1 From 2a0c7ea4cc94a01c9396a213b2d0ccce6c05b37f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 29 Mar 2011 11:19:49 +0200 Subject: curl_easy_setopt.3: mention TFTP read callback flaw The read callback must return the exact requested amount of data when it is used for doing TFTP uploads. This is due to how it deals with data internally. This could/should be fixed but for now we document the existing behavior. Reported by: Colin Blair Bug: http://curl.haxx.se/mail/lib-2011-03/0319.html --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6166d5fd5..16f4b5842 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -208,6 +208,10 @@ 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. +\fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data +that the callback wants, or it will be considered the final packet by the +server end and the transfer will end there. + If you set this callback pointer to NULL, or don't set it at all, the default internal read function will be used. It is doing an fread() on the FILE * userdata set with \fICURLOPT_READDATA\fP. -- cgit v1.2.1 From 01f05d0c758795e5bb02c6245fc73b8458eb397a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Apr 2011 15:14:02 +0200 Subject: return code cleanup: build, init and run-time errors Stop the abuse of CURLE_FAILED_INIT as return code for things not being init related by introducing two new return codes: CURLE_NOT_BUILT_IN and CURLE_UNKNOWN_OPTION CURLE_NOT_BUILT_IN replaces return code 4 that has been obsoleted for several years. It is used for returning error when something is attempted to be used but the feature/option was not enabled or explictitly disabled at build-time. Getting this error mostly means that libcurl needs to be rebuilt. CURLE_FAILED_INIT is now saved and used strictly for init failures. Getting this problem means something went seriously wrong, like a resource shortage or similar. CURLE_UNKNOWN_OPTION is the option formerly known as CURLE_UNKNOWN_TELNET_OPTION (and the old name is still present, separately defined to be removed in a very distant future). This error code is meant to be used to return when an option is given to libcurl that isn't known. This problem would mostly indicate a problem in the program that uses libcurl. --- docs/libcurl/libcurl-errors.3 | 18 +++++++++++++----- docs/libcurl/symbols-in-versions | 2 ++ 2 files changed, 15 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index c3c854e90..beabf98f0 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -44,9 +44,15 @@ can be a misspelled protocol string or just a protocol libcurl has no code for. .IP "CURLE_FAILED_INIT (2)" Very early initialization code failed. This is likely to be an internal error -or problem. +or problem, or a resource problem where something fundamental couldn't get +done at init time. .IP "CURLE_URL_MALFORMAT (3)" The URL was not properly formatted. +.IP "CURLE_NOT_BUILT_IN (4)" +A requested feature, protocol or option was not found built-in in this libcurl +due to a build-time decision. This means that a feature or option was not +enabled or explicitly disabled when libcurl was built and in order to get it +to function you have to get a rebuilt libcurl. .IP "CURLE_COULDNT_RESOLVE_PROXY (5)" Couldn't resolve proxy. The given proxy host could not be resolved. .IP "CURLE_COULDNT_RESOLVE_HOST (6)" @@ -145,9 +151,11 @@ CURLOPT_INTERFACE. .IP "CURLE_TOO_MANY_REDIRECTS (47)" Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS. -.IP "CURLE_UNKNOWN_TELNET_OPTION (48)" -An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to -the appropriate documentation. +.IP "CURLE_UNKNOWN_OPTION (48)" +An option passed to libcurl is not recognized/known. Refer to the appropriate +documentation. This is most likely a problem in the program that uses +libcurl. The error buffer might contain more specific information about which +exact option it concerns. .IP "CURLE_TELNET_OPTION_SYNTAX (49)" A telnet option string was Illegally formatted. .IP "CURLE_PEER_FAILED_VERIFICATION (51)" diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index fca917a97..aa86b913a 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -82,6 +82,7 @@ CURLE_LDAP_SEARCH_FAILED 7.1 CURLE_LIBRARY_NOT_FOUND 7.1 7.17.0 CURLE_LOGIN_DENIED 7.13.1 CURLE_MALFORMAT_USER 7.1 7.17.0 +CURLE_NOT_BUILT_IN 7.21.5 CURLE_OK 7.1 CURLE_OPERATION_TIMEDOUT 7.10.2 CURLE_OPERATION_TIMEOUTED 7.1 7.17.0 @@ -123,6 +124,7 @@ CURLE_TFTP_NOTFOUND 7.15.0 CURLE_TFTP_PERM 7.15.0 CURLE_TFTP_UNKNOWNID 7.15.0 CURLE_TOO_MANY_REDIRECTS 7.5 +CURLE_UNKNOWN_OPTION 7.21.5 CURLE_UNKNOWN_TELNET_OPTION 7.7 CURLE_UNSUPPORTED_PROTOCOL 7.1 CURLE_UPLOAD_FAILED 7.16.3 -- cgit v1.2.1 From 2064ea961282aa02867b80f505d00eef47203651 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 9 Apr 2011 20:04:22 +0200 Subject: curl_easy_setopt.3: CURLOPT_RESOLVE typo version Reported by: Hongli Lai --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 16f4b5842..9debc8895 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1835,7 +1835,7 @@ resolves, by including a string in the linked list that uses the format \&"-HOST:PORT". The host name must be prefixed with a dash, and the host name and port number must exactly match what was already added previously. -(Added in 7.12.3) +(Added in 7.21.3) .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be -- cgit v1.2.1 From 8e4fb01e64bee1893452f25873758cb856898d84 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Apr 2011 22:45:42 +0200 Subject: transfer-encoding: added new option and cmdline Added CURLOPT_TRANSFER_ENCODING as the option to set to request Transfer Encoding in HTTP requests (if built zlib enabled). I also renamed CURLOPT_ENCODING to CURLOPT_ACCEPT_ENCODING (while keeping the old name around) to reduce the confusion when we have to encoding options for HTTP. --tr-encoding is now the new command line option for curl to request this, and thus I updated the test cases accordingly. --- docs/libcurl/symbols-in-versions | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index aa86b913a..7c2c866be 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -282,6 +282,7 @@ CURLOPTTYPE_FUNCTIONPOINT 7.1 CURLOPTTYPE_LONG 7.1 CURLOPTTYPE_OBJECTPOINT 7.1 CURLOPTTYPE_OFF_T 7.11.0 +CURLOPT_ACCEPT_ENCODING 7.21.6 CURLOPT_ADDRESS_SCOPE 7.19.0 CURLOPT_APPEND 7.17.0 CURLOPT_AUTOREFERER 7.1 @@ -485,6 +486,7 @@ CURLOPT_TLSAUTH_PASSWORD 7.21.4 CURLOPT_TLSAUTH_TYPE 7.21.4 CURLOPT_TLSAUTH_USERNAME 7.21.4 CURLOPT_TRANSFERTEXT 7.1.1 +CURLOPT_TRANSFER_ENCODING 7.21.6 CURLOPT_UNRESTRICTED_AUTH 7.10.4 CURLOPT_UPLOAD 7.1 CURLOPT_URL 7.1 -- cgit v1.2.1 From 5aae3c13e2ce95c1e06e8512948f5caac118aa1c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 14 Apr 2011 22:59:34 +0200 Subject: transfer-encoding: document the options The new libcurl and command line options are now described. --- docs/libcurl/curl_easy_setopt.3 | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9debc8895..7cfe29b98 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -916,7 +916,7 @@ work. (Added in 7.10.7) Pass a parameter set to 1 to enable this. When enabled, libcurl will automatically set the Referer: field in requests where it follows a Location: redirect. -.IP CURLOPT_ENCODING +.IP CURLOPT_ACCEPT_ENCODING Sets the contents of the Accept-Encoding: header sent in an HTTP request, and enables decoding of a response when a Content-Encoding: header is received. Three encodings are supported: \fIidentity\fP, which does nothing, @@ -928,6 +928,21 @@ supported encodings is sent. This is a request, not an order; the server may or may not do it. This option must be set (to any non-NULL value) or else any unsolicited encoding done by the server is ignored. See the special file lib/README.encoding for details. + +(This option was called CURLOPT_ENCODING before 7.21.6) +.IP CURLOPT_TRANSFER_ENCODING +Adds a request for compressed Transfer Encoding in the outgoing HTTP +request. If the server supports this and so desires, it can respond with the +HTTP resonse sent using a compressed Transfer-Encoding that will be +automatically uncompressed by libcurl on receival. + +Transfer-Encoding differs slightly from the Content-Encoding you ask for with +\fBCURLOPT_ACCEPT_ENCODING\fP in that a Transfer-Encoding is strictly meant to +be for the transfer and thus MUST be decoded before the data arrives in the +client. Traditionally, Transfer-Encoding has been much less used and supported +by both HTTP clients and HTTP servers. + +(Added in 7.21.6) .IP CURLOPT_FOLLOWLOCATION A parameter set to 1 tells the library to follow any Location: header that the server sends as part of an HTTP header. -- cgit v1.2.1 From c6a0abdd975848dca03f93e7ff1dd4550bda7c0a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 20 Apr 2011 15:42:23 +0200 Subject: curl_easy_setopt.3: CURLOPT_PROXYTYPE clarification When set to a HTTP 1.0 proxy, that only affects the CONNECT request and not the regular HTTP request. --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7cfe29b98..347c49ad3 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -641,6 +641,11 @@ this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP (added in 7.19.4), \fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and \fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is default. (Added in 7.10) + +If you set \fBCURLOPT_PROXYTYPE\fP to \fICURLPROXY_HTTP_1_0\fP, it will only +affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version +used for "regular" HTTP requests is instead controled with +\fICURLOPT_HTTP_VERSION\fP. .IP CURLOPT_NOPROXY Pass a pointer to a zero terminated string. The should be a comma- separated list of hosts which do not use a proxy, if one is specified. The only -- cgit v1.2.1 From a490961b10c62bf1f0c251d5a507c2eab4c5db70 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 30 Apr 2011 18:49:35 +0200 Subject: curl_formfree.3: mention argument may be NULL As the code already checks for it we can just as well make it official! --- docs/libcurl/curl_formfree.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 7c825c980..9944666cc 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -31,6 +31,9 @@ curl_formfree - free a previously build multipart/formdata HTTP POST chain 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 \fIcurl_easy_perform(3)\fP has been called. + +\fBform\fP is the pointer as returned from a previous call to +\fIcurl_formadd(3)\fP and may be NULL. .SH RETURN VALUE None .SH "SEE ALSO" -- cgit v1.2.1 From 038a631274606e911e45681d88219908eb0749bf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 May 2011 11:14:30 +0200 Subject: url encode docs: mention '-', '.', '_' and '~' Clarify that the '-', '.', '_' or '~' letters are also not escaped since they shouldn't according to RFC3986 section 2.3. This is how this function has behaved since sep 2010, commit 5df13c31735fa0. --- docs/libcurl/curl_easy_escape.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_escape.3 b/docs/libcurl/curl_easy_escape.3 index 2c09875cb..3a98e6fe8 100644 --- a/docs/libcurl/curl_easy_escape.3 +++ b/docs/libcurl/curl_easy_escape.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -31,8 +31,8 @@ curl_easy_escape - URL encodes the given string .SH DESCRIPTION This function converts the given input string to an URL encoded string and returns that as a new allocated string. All input characters that are not a-z, -A-Z or 0-9 are converted to their "URL escaped" version (%NN where NN is a -two-digit hexadecimal number). +A-Z, 0-9, '-', '.', '_' or '~' are converted to their "URL escaped" version +(%NN where NN is a two-digit hexadecimal number). If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on the input \fBurl\fP to find out the size. -- cgit v1.2.1 From d4ebf3c6b0951dcec2157feb6e064ee636cd919b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 May 2011 22:15:14 +0200 Subject: docs: mention the protocol:// support in proxy strings --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 347c49ad3..4522181b1 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -632,6 +632,11 @@ use of a proxy, even if there is an environment variable set for it. Since 7.14.1, the proxy host string given in environment variables can be specified the exact same way as the proxy can be set with \fICURLOPT_PROXY\fP, include protocol prefix (http://) and embedded user + password. + +Since 7.21.7, the proxy string may be specified with a protocol:// prefix to +specify alternative proxy protocols. Use socks4://, socks4a:// or socks5:// to +request the specific SOCKS version to be used. No protocol specified, http:// +and all others will be treated as HTTP proxies. .IP CURLOPT_PROXYPORT Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. -- cgit v1.2.1 From 365db94e0a92cacfebd20aa660138ea5b67a02d3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 May 2011 23:31:38 +0200 Subject: curl_easy_setopt.3: clarify the SSH KEYFILE options usage The internal defaults are important info --- docs/libcurl/curl_easy_setopt.3 | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4522181b1..55b0db5ba 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2103,13 +2103,15 @@ libcurl will reject the connection to the host unless the md5sums match. This option is only for SCP and SFTP transfers. (Added in 7.17.1) .IP CURLOPT_SSH_PUBLIC_KEYFILE Pass a char * pointing to a file name for your public key. If not used, -libcurl defaults to using \fB~/.ssh/id_dsa.pub\fP. -(Added in 7.16.1) +libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment +variable is set, and just "id_dsa.pub" in the current directory if HOME is not +set. (Added in 7.16.1) .IP CURLOPT_SSH_PRIVATE_KEYFILE Pass a char * pointing to a file name for your private key. If not used, -libcurl defaults to using \fB~/.ssh/id_dsa\fP. If the file is -password-protected, set the password with \fICURLOPT_KEYPASSWD\fP. (Added in -7.16.1) +libcurl defaults to \fB$HOME/.ssh/id_dsa\fP if the HOME environment variable +is set, and just "id_dsa" in the current directory if HOME is not set. If the +file is password-protected, set the password with +\fICURLOPT_KEYPASSWD\fP. (Added in 7.16.1) .IP CURLOPT_SSH_KNOWNHOSTS Pass a pointer to a zero terminated string holding the file name of the known_host file to use. The known_hosts file should use the OpenSSH file -- cgit v1.2.1 From ade337d79e1920c7836ca34b62595fcd42bd85c0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 May 2011 22:47:56 +0200 Subject: curl_easy_getinfo.3: clarify some timing info --- docs/libcurl/curl_easy_getinfo.3 | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index 2629755e8..eb4e900dd 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -80,12 +80,13 @@ waits in line for the pipeline and more. (Added in 7.19.0) Pass a pointer to a double to receive the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular -protocol(s) involved. +protocol(s) involved. It does \fInot\fP involve the sending of the protocol- +specific request that triggers a transfer. .IP CURLINFO_STARTTRANSFER_TIME Pass a pointer to a double to receive the time, in seconds, it took from the -start until the first byte is just about to be transferred. This includes -CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate -the result. +start until the first byte is received by libcurl. This includes +CURLINFO_PRETRANSFER_TIME and also the time the server needs to calculate the +result. .IP CURLINFO_REDIRECT_TIME Pass a pointer to a double to receive the total time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer @@ -275,7 +276,7 @@ file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved. .IP STARTTRANSFER \fICURLINFO_STARTTRANSFER_TIME\fP. The time it took from the start until the -first byte is just about to be transferred. +first byte is received by libcurl. .IP TOTAL \fICURLINFO_TOTAL_TIME\fP. Total time of the previous request. .IP REDIRECT -- cgit v1.2.1 From 558f997e99c4c8e4f6ed888a85d748b33920cdf2 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 5 May 2011 11:47:55 +0200 Subject: socks proxy: allow socks5h:// prefix too Using 'socks5h' as proxy protocol will make it a CURLPROXY_SOCKS5_HOSTNAME proxy which is SOCKS5 and asking the proxy to resolve host names. I found no "standard" protocol name for this. --- docs/libcurl/curl_easy_setopt.3 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 55b0db5ba..2494ecc15 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -634,9 +634,11 @@ specified the exact same way as the proxy can be set with \fICURLOPT_PROXY\fP, include protocol prefix (http://) and embedded user + password. Since 7.21.7, the proxy string may be specified with a protocol:// prefix to -specify alternative proxy protocols. Use socks4://, socks4a:// or socks5:// to -request the specific SOCKS version to be used. No protocol specified, http:// -and all others will be treated as HTTP proxies. +specify alternative proxy protocols. Use socks4://, socks4a://, socks5:// or +socks5h:// (the last one to enable socks5 and asking the proxy to do the +resolving, also known as CURLPROXY_SOCKS5_HOSTNAME type) to request the +specific SOCKS version to be used. No protocol specified, http:// and all +others will be treated as HTTP proxies. .IP CURLOPT_PROXYPORT Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY\fP. -- cgit v1.2.1 From 6dfa16c3c47b0226b9835a7246bbc08d872e3eab Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 16 May 2011 23:53:38 +0200 Subject: symbols-in-versions: add CLOSESOCKET* --- docs/libcurl/symbols-in-versions | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 7c2c866be..9257fb16b 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -295,6 +295,8 @@ CURLOPT_CHUNK_DATA 7.21.0 CURLOPT_CHUNK_END_FUNCTION 7.21.0 CURLOPT_CLOSEFUNCTION 7.7 7.11.1 7.15.5 CURLOPT_CLOSEPOLICY 7.7 7.16.1 +CURLOPT_CLOSESOCKETDATA 7.21.7 +CURLOPT_CLOSESOCKETFUNCTION 7.21.7 CURLOPT_CONNECTTIMEOUT 7.7 CURLOPT_CONNECTTIMEOUT_MS 7.16.2 CURLOPT_CONNECT_ONLY 7.15.2 -- cgit v1.2.1 From 664ff3065031b21a4fa22b7629f54db860bbb3c7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 18 May 2011 22:30:10 +0200 Subject: curl_easy_setopt.3: document CLOSESOCKET* options --- docs/libcurl/curl_easy_setopt.3 | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2494ecc15..2ba37f353 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -307,6 +307,17 @@ address blacklisting. The default behavior is: Pass a pointer that will be untouched by libcurl and passed as the first argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP. (Option added in 7.17.1.) +.IP CURLOPT_CLOSESOCKETFUNCTION +Function pointer that should match the \fIcurl_closesocket_callback\fP +prototype found in \fI\fP. This function gets called by libcurl +instead of the \fIclose(2)\fP or \fIclosesocket(2)\fP call when sockets are +closed (not for any other file descriptors). This is pretty much the reverse +to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. \fIReturn 0 to signal success +and 1 if there was an error. (Option added in 7.21.7) +.IP CURLOPT_CLOSESOCKETDATA +Pass a pointer that will be untouched by libcurl and passed as the first +argument in the opensocket callback set with +\fICURLOPT_CLOSESOCKETFUNCTION\fP. (Option added in 7.21.7) .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of -- cgit v1.2.1 From e83816bfcf759adb4a7102ea3616fe2a3793cec6 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 18 May 2011 23:46:57 +0200 Subject: typo: close is in man page section 3 --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2ba37f353..0fa6999e0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -310,7 +310,7 @@ argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP. .IP CURLOPT_CLOSESOCKETFUNCTION Function pointer that should match the \fIcurl_closesocket_callback\fP prototype found in \fI\fP. This function gets called by libcurl -instead of the \fIclose(2)\fP or \fIclosesocket(2)\fP call when sockets are +instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when sockets are closed (not for any other file descriptors). This is pretty much the reverse to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. \fIReturn 0 to signal success and 1 if there was an error. (Option added in 7.21.7) -- cgit v1.2.1 From edf282c09681dfca6b6480a3e07a475918b32e23 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 May 2011 13:50:52 +0200 Subject: setopt.3: CURLOPT_WRITEFUNCTION had wrong function proto --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0fa6999e0..f7af816bb 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -145,7 +145,7 @@ Using the rules above, a file name pattern can be constructed: .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION Function pointer that should match the following prototype: \fBsize_t -function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP This +function( char *ptr, size_t size, size_t nmemb, void *userdata);\fP This function gets called by libcurl as soon as there is data received that needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP, it will not be zero terminated. Return the number -- cgit v1.2.1 From 340228cc8121270adbde1d49326327d48165e463 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 25 May 2011 13:51:57 +0200 Subject: setopt.3: remove leftover style change --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f7af816bb..06d071bf2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -312,8 +312,8 @@ Function pointer that should match the \fIcurl_closesocket_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when sockets are closed (not for any other file descriptors). This is pretty much the reverse -to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. \fIReturn 0 to signal success -and 1 if there was an error. (Option added in 7.21.7) +to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal success and +1 if there was an error. (Option added in 7.21.7) .IP CURLOPT_CLOSESOCKETDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the opensocket callback set with -- cgit v1.2.1 From f3d77f772dedce951fe56726f679de4c32e09299 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 27 May 2011 11:12:52 +0200 Subject: curl_easy_setopt.3: NOPROGRESS also affects the callback --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 06d071bf2..ba43a530a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -68,8 +68,9 @@ A parameter set to 1 tells the library to include the header in the body output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). .IP CURLOPT_NOPROGRESS -A parameter set to 1 tells the library to shut off the built-in progress meter -completely. +Pass a long. If set to 1, it tells the library to shut off the progress meter +completely. It will also present the \fICURLOPT_PROGRESSFUNCTION\fP from +getting called. Future versions of libcurl are likely to not have any built-in progress meter at all. -- cgit v1.2.1 From d6bb8dcc23b5e607e2f30c63d9cf13371219df54 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 1 Jun 2011 19:50:08 +0200 Subject: CURLOPT_WILDCARDMATCH: minor style edit Due to some flaw in roffit I removed some style changes to make the web page look better. --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index ba43a530a..7588df9aa 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -106,18 +106,18 @@ This feature is only supported by the FTP download for now. A brief introduction of its syntax follows: .RS -.IP "\fB*\fP - ASTERISK" +.IP "* - ASTERISK" \&ftp://example.com/some/path/\fB*.txt\fP (for all txt's from the root directory) .RE .RS -.IP "\fB?\fP - QUESTION MARK" +.IP "? - QUESTION MARK" Question mark matches any (exactly one) character. \&ftp://example.com/some/path/\fBphoto?.jpeg\fP .RE .RS -.IP "\fB[\fP - BRACKET EXPRESSION" +.IP "[ - BRACKET EXPRESSION" The left bracket opens a bracket expression. The question mark and asterisk have no special meaning in a bracket expression. Each bracket expression ends by the right bracket and matches exactly one character. Some examples follow: -- cgit v1.2.1 From d5cc77b7449316b6c8374968594f718df567ef7a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 10 Jun 2011 13:17:17 +0200 Subject: CURLOPT_WRITEHEADER: clarify the docs --- docs/libcurl/curl_easy_setopt.3 | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7588df9aa..c2804f385 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -343,10 +343,10 @@ Function pointer that should match the following prototype: \fIsize_t function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP. This function gets called by libcurl as soon as it has received header data. The header callback will be called once for each header and only complete header -lines are passed on to the callback. Parsing headers should be easy enough -using this. The size of the data pointed to by \fIptr\fP is \fIsize\fP -multiplied with \fInmemb\fP. Do not assume that the header line is zero -terminated! The pointer named \fIuserdata\fP is the one you set with the +lines are passed on to the callback. Parsing headers is very easy using +this. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied +with \fInmemb\fP. Do not assume that the header line is zero terminated! The +pointer named \fIuserdata\fP is the one you set with the \fICURLOPT_WRITEHEADER\fP option. The callback function must return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the @@ -365,19 +365,20 @@ negotiation. If you need to operate on only the headers from the final response, you will need to collect headers in the callback yourself and use HTTP status lines, for example, to delimit response boundaries. -Since 7.14.1: When a server sends a chunked encoded transfer, it may contain a -trailer. That trailer is identical to a HTTP header and if such a trailer is -received it is passed to the application using this callback as well. There -are several ways to detect it being a trailer and not an ordinary header: 1) -it comes after the response-body. 2) it comes after the final header line (CR -LF) 3) a Trailer: header among the response-headers mention what header to -expect in the trailer. +When a server sends a chunked encoded transfer, it may contain a trailer. That +trailer is identical to a HTTP header and if such a trailer is received it is +passed to the application using this callback as well. There are several ways +to detect it being a trailer and not an ordinary header: 1) it comes after the +response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: +header among the regular response-headers mention what header(s) to expect in +the trailer. .IP CURLOPT_WRITEHEADER (This option is also known as \fBCURLOPT_HEADERDATA\fP) Pass a pointer to be -used to write the header part of the received data to. If you don't use your -own callback to take care of the writing, this must be a valid FILE *. See -also the \fICURLOPT_HEADERFUNCTION\fP option above on how to set a custom -get-all-headers callback. +used to write the header part of the received data to. If you don't use +\fICURLOPT_WRITEFUNCTION\fP or \fICURLOPT_HEADERFUNCTION\fP to take care of +the writing, this must be a valid FILE * as the internal default will then be +a plain fwrite(). See also the \fICURLOPT_HEADERFUNCTION\fP option above on +how to set a custom get-all-headers callback. .IP CURLOPT_DEBUGFUNCTION Function pointer that should match the following prototype: \fIint curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP -- cgit v1.2.1 From 84e13f2e07121e09a1a4b607f0f887b20296ec5f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 13 Jun 2011 22:03:33 +0200 Subject: curl_formget.3: CURLFORM_STREAM has its drawbacks Due to a design flaw, the CURLFORM_STREAM option doesn't really work with curl_formget until after curl_easy_perform (or similar). --- docs/libcurl/curl_formget.3 | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formget.3 b/docs/libcurl/curl_formget.3 index b214a50c2..b52622136 100644 --- a/docs/libcurl/curl_formget.3 +++ b/docs/libcurl/curl_formget.3 @@ -23,24 +23,27 @@ .SH NAME curl_formget - serialize a previously built multipart/formdata HTTP POST chain .SH SYNOPSIS +.nf .B #include -.sp -.BI "void curl_formget(struct curl_httppost *" form, " void *" arg, -.BI " curl_formget_callback " append ");" -.ad + +void curl_formget(struct curl_httppost * form, void *userp, + curl_formget_callback append ); .SH DESCRIPTION curl_formget() is used to serialize data previously built/appended with -\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument which will be -passed to the curl_formget_callback function. +\fIcurl_formadd(3)\fP. Accepts a void pointer as second argument named +\fIuserp\fP which will be passed as the first argument to the +curl_formget_callback function. -.BI "typedef size_t (*curl_formget_callback)(void *" arg, " const char *" buf, +.BI "typedef size_t (*curl_formget_callback)(void *" userp, " const char *" buf, .BI " size_t " len ");" -.nf The curl_formget_callback will be executed for each part of the HTTP POST -chain. The void *arg pointer will be the one passed as second argument to -curl_formget(). The character buffer passed to it must not be freed. The +chain. The character buffer passed to the callback must not be freed. The callback should return the buffer length passed to it on success. + +If the \fBCURLFORM_STREAM\fP option is used in the formpost, it will prevent +\fIcurl_formget(3)\fP from working until you've performed the actual HTTP +request as only then will libcurl get the actual read callback to use! .SH RETURN VALUE 0 means everything was ok, non-zero means an error occurred .SH EXAMPLE @@ -52,6 +55,7 @@ callback should return the buffer length passed to it on success. (*(size_t *) arg) += len; return len; } + size_t print_httppost(struct curl_httppost *post) { size_t total_size = 0; -- cgit v1.2.1 From 8da5da9b6544337b8a675db092da201f279265d4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 23 Jun 2011 09:31:12 +0200 Subject: curl_formfree: clarify which pointer to free --- docs/libcurl/curl_formadd.3 | 17 +++++++++-------- docs/libcurl/curl_formfree.3 | 4 ++++ 2 files changed, 13 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index bba0c083e..ce4df1e4b 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -30,18 +30,19 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata -HTTP POST (sometimes referred to as RFC2388-style posts). Append one section at -a time until you've added all the sections you want included and then you pass -the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. -\fIlastitem\fP is set after each call and on repeated invokes it should be -left as set to allow repeated invokes to find the end of the list faster. +HTTP POST (sometimes referred to as RFC2388-style posts). Append one section +at a time until you've added all the sections you want included and then you +pass the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. +\fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated +invokes it should be left as set to allow repeated invokes to find the end of +the list faster. After the \fIlastitem\fP pointer follow the real arguments. -The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to +The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to NULL in the first call to this function. All list-data will be allocated by -the function itself. You must call \fIcurl_formfree(3)\fP after the form post -has been done to free the resources. +the function itself. You must call \fIcurl_formfree(3)\fP on the +\fIfirstitem\P after the form post has been done to free the resources. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. diff --git a/docs/libcurl/curl_formfree.3 b/docs/libcurl/curl_formfree.3 index 9944666cc..7438a1640 100644 --- a/docs/libcurl/curl_formfree.3 +++ b/docs/libcurl/curl_formfree.3 @@ -32,6 +32,10 @@ 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 \fIcurl_easy_perform(3)\fP has been called. +The pointer to free is the same pointer you passed to the +\fBCURLOPT_HTTPPOST\fP option, which is the \fIfirstitem\fP pointer from the +\fIcurl_formadd(3)\fP invoke(s). + \fBform\fP is the pointer as returned from a previous call to \fIcurl_formadd(3)\fP and may be NULL. .SH RETURN VALUE -- cgit v1.2.1 From 3e71ebe4eb262c09e871700707525ee16f33497e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 30 Jun 2011 09:57:23 +0200 Subject: docs: FTP quotes support '*' prefix to ignore errors By default libcurl stops processing quote commands on failures. --- docs/libcurl/curl_easy_setopt.3 | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index c2804f385..014269f4f 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1313,18 +1313,22 @@ Examples with specified ports: 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 -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 -to append strings (commands) to the list, and clear the entire list -afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation -again by setting a NULL to this option. -The set of valid FTP commands depends on the server (see RFC959 for a -list of mandatory commands). -The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, -rename, rm, rmdir, symlink (see +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 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 to append strings (commands) to the +list, and clear the entire list afterwards with +\fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL +to this option. When speaking to a FTP server, prefix the command with an +asterisk (*) to make libcurl continue even if the command fails as by default +libcurl will stop at first failure. + +The set of valid FTP commands depends on the server (see RFC959 for a list of +mandatory commands). + +The valid SFTP commands are: chgrp, chmod, chown, ln, mkdir, pwd, rename, rm, +rmdir, symlink (see .BR curl (1)) (SFTP support added in 7.16.3) .IP CURLOPT_POSTQUOTE -- cgit v1.2.1 From d95f45cd407b631f21de0800eec6ccdb452a048f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 19 Jul 2011 00:54:41 +0200 Subject: symbols-in-versions: add NTLM_SSO symbols --- docs/libcurl/symbols-in-versions | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 9257fb16b..a91f4fb00 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -20,6 +20,7 @@ CURLAUTH_DIGEST_IE 7.19.3 CURLAUTH_GSSNEGOTIATE 7.10.6 CURLAUTH_NONE 7.10.6 CURLAUTH_NTLM 7.10.6 +CURLAUTH_NTLM_SSO 7.21.8 CURLAUTH_ONLY 7.21.3 CURLCLOSEPOLICY_CALLBACK 7.7 CURLCLOSEPOLICY_LEAST_RECENTLY_USED 7.7 @@ -675,6 +676,7 @@ CURL_VERSION_KERBEROS4 7.10 CURL_VERSION_LARGEFILE 7.11.1 CURL_VERSION_LIBZ 7.10 CURL_VERSION_NTLM 7.10.6 +CURL_VERSION_NTLM_SSO 7.21.8 CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 -- cgit v1.2.1 From ebf42c4be76df40ec6d3bf32f229bbb274e2c32f Mon Sep 17 00:00:00 2001 From: Adam Tkac Date: Tue, 19 Jul 2011 19:10:43 +0200 Subject: Add new CURLOPT_GSSAPI_DELEGATION option. Curl_gss_init_sec_context got new parameter - SessionHandle. Signed-off-by: Adam Tkac --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 014269f4f..2cdfcf86b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2109,6 +2109,10 @@ of these, 'private' will be used. Set the string to NULL to disable kerberos support for FTP. (This option was known as CURLOPT_KRB4LEVEL up to 7.16.3) +.IP CURLOPT_GSSAPI_DELEGATION +Set the parameter to 1 to allow GSSAPI credential delegation. The delegation +is disabled by default since 7.21.7. +(Added in 7.21.8) .SH SSH OPTIONS .IP CURLOPT_SSH_AUTH_TYPES Pass a long set to a bitmask consisting of one or more of -- cgit v1.2.1 From a7864c41db6ac12a1b67f2646f837174f75a240b Mon Sep 17 00:00:00 2001 From: Kamil Dudka Date: Mon, 25 Jul 2011 11:49:26 +0200 Subject: curl_gssapi: refine the handling of CURLOPT_GSSAPI_DELEGATION Suggested by Richard Silverman. --- docs/libcurl/curl_easy_setopt.3 | 8 ++++++-- docs/libcurl/symbols-in-versions | 4 ++++ 2 files changed, 10 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2cdfcf86b..1e5f3b641 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2110,8 +2110,12 @@ support for FTP. (This option was known as CURLOPT_KRB4LEVEL up to 7.16.3) .IP CURLOPT_GSSAPI_DELEGATION -Set the parameter to 1 to allow GSSAPI credential delegation. The delegation -is disabled by default since 7.21.7. +Set the parameter to CURLGSSAPI_DELEGATION_FLAG to allow unconditional GSSAPI +credential delegation. The delegation is disabled by default since 7.21.7. +Set the parameter to CURLGSSAPI_DELEGATION_POLICY_FLAG to delegate only if +the OK-AS-DELEGATE flag is set in the service ticket in case this feature is +supported by the GSSAPI implementation and the definition of +GSS_C_DELEG_POLICY_FLAG was available at compile-time. (Added in 7.21.8) .SH SSH OPTIONS .IP CURLOPT_SSH_AUTH_TYPES diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index a91f4fb00..a1d92aa06 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -187,6 +187,9 @@ CURLFTPSSL_TRY 7.11.0 7.17.0 CURLFTP_CREATE_DIR 7.19.4 CURLFTP_CREATE_DIR_NONE 7.19.4 CURLFTP_CREATE_DIR_RETRY 7.19.4 +CURLGSSAPI_DELEGATION_FLAG 7.21.8 +CURLGSSAPI_DELEGATION_NONE 7.21.8 +CURLGSSAPI_DELEGATION_POLICY_FLAG 7.21.8 CURLINFO_APPCONNECT_TIME 7.19.0 CURLINFO_CERTINFO 7.19.1 CURLINFO_CONDITION_UNMET 7.19.4 @@ -345,6 +348,7 @@ CURLOPT_FTP_SSL_CCC 7.16.1 CURLOPT_FTP_USE_EPRT 7.10.5 CURLOPT_FTP_USE_EPSV 7.9.2 CURLOPT_FTP_USE_PRET 7.20.0 +CURLOPT_GSSAPI_DELEGATION 7.21.8 CURLOPT_HEADER 7.1 CURLOPT_HEADERDATA 7.10 CURLOPT_HEADERFUNCTION 7.7.2 -- cgit v1.2.1 From 73548e1d22e7ab0c39d7a98e42adbbe2f6221725 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Aug 2011 10:13:09 +0200 Subject: s/7.21.8/7.22.0 --- docs/libcurl/symbols-in-versions | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index a1d92aa06..dfc2efe31 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -20,7 +20,7 @@ CURLAUTH_DIGEST_IE 7.19.3 CURLAUTH_GSSNEGOTIATE 7.10.6 CURLAUTH_NONE 7.10.6 CURLAUTH_NTLM 7.10.6 -CURLAUTH_NTLM_SSO 7.21.8 +CURLAUTH_NTLM_SSO 7.22.0 CURLAUTH_ONLY 7.21.3 CURLCLOSEPOLICY_CALLBACK 7.7 CURLCLOSEPOLICY_LEAST_RECENTLY_USED 7.7 @@ -187,9 +187,9 @@ CURLFTPSSL_TRY 7.11.0 7.17.0 CURLFTP_CREATE_DIR 7.19.4 CURLFTP_CREATE_DIR_NONE 7.19.4 CURLFTP_CREATE_DIR_RETRY 7.19.4 -CURLGSSAPI_DELEGATION_FLAG 7.21.8 -CURLGSSAPI_DELEGATION_NONE 7.21.8 -CURLGSSAPI_DELEGATION_POLICY_FLAG 7.21.8 +CURLGSSAPI_DELEGATION_FLAG 7.22.0 +CURLGSSAPI_DELEGATION_NONE 7.22.0 +CURLGSSAPI_DELEGATION_POLICY_FLAG 7.22.0 CURLINFO_APPCONNECT_TIME 7.19.0 CURLINFO_CERTINFO 7.19.1 CURLINFO_CONDITION_UNMET 7.19.4 @@ -348,7 +348,7 @@ CURLOPT_FTP_SSL_CCC 7.16.1 CURLOPT_FTP_USE_EPRT 7.10.5 CURLOPT_FTP_USE_EPSV 7.9.2 CURLOPT_FTP_USE_PRET 7.20.0 -CURLOPT_GSSAPI_DELEGATION 7.21.8 +CURLOPT_GSSAPI_DELEGATION 7.22.0 CURLOPT_HEADER 7.1 CURLOPT_HEADERDATA 7.10 CURLOPT_HEADERFUNCTION 7.7.2 @@ -680,7 +680,7 @@ CURL_VERSION_KERBEROS4 7.10 CURL_VERSION_LARGEFILE 7.11.1 CURL_VERSION_LIBZ 7.10 CURL_VERSION_NTLM 7.10.6 -CURL_VERSION_NTLM_SSO 7.21.8 +CURL_VERSION_NTLM_SSO 7.22.0 CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 -- cgit v1.2.1 From 784971743dc57077c9b1b1af15d29273ca2e912c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 11 Aug 2011 14:54:44 +0200 Subject: curl_easy_cleanup: clarify the callback situation --- docs/libcurl/curl_easy_cleanup.3 | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3 index 75a370367..d8a3f9fcf 100644 --- a/docs/libcurl/curl_easy_cleanup.3 +++ b/docs/libcurl/curl_easy_cleanup.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2007, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -37,8 +37,15 @@ This will effectively close all connections this handle has used and possibly has kept open until now. Don't call this function if you intend to transfer more files. -Any uses of the \fBhandle\fP after this function has been called are -illegal. This kills the handle and all memory associated with it! +Occasionally you may get your progress callback or header callback called from +within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using +\fIcurl_easy_setopt(3)\fP). Like if libcurl decides to shut down the +connection and the protocol is of a kind that requires a command/response +sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP. + +Any uses of the \fBhandle\fP after this function has been called and have +returned, are illegal. This kills the handle and all memory associated with +it! With libcurl versions prior to 7.17.: when you've called this, you can safely remove all the strings you've previously told libcurl to use, as it won't use -- cgit v1.2.1 From f5ad192d2373b24ef600358adb78bf02beffe426 Mon Sep 17 00:00:00 2001 From: Kamil Dudka Date: Wed, 24 Aug 2011 23:50:59 +0200 Subject: docs: the next release is going to be 7.22.0 --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 1e5f3b641..77a24f4a2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2116,7 +2116,7 @@ Set the parameter to CURLGSSAPI_DELEGATION_POLICY_FLAG to delegate only if the OK-AS-DELEGATE flag is set in the service ticket in case this feature is supported by the GSSAPI implementation and the definition of GSS_C_DELEG_POLICY_FLAG was available at compile-time. -(Added in 7.21.8) +(Added in 7.22.0) .SH SSH OPTIONS .IP CURLOPT_SSH_AUTH_TYPES Pass a long set to a bitmask consisting of one or more of -- cgit v1.2.1 From 407e08baad45b060e3fa1387190a8b12aca9ab60 Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Fri, 26 Aug 2011 18:57:50 +0200 Subject: NTLM single-sign on adjustments (X) Functions renamed: Curl_output_ntlm_sso -> Curl_output_ntlm_wb sso_ntlm_close -> wb_ntlm_close sso_ntlm_response -> wb_ntlm_response sso_ntlm_initiate -> wb_ntlm_initiate Preprocessor symbols renamed: CURLAUTH_NTLM_SSO -> CURLAUTH_NTLM_WB CURL_VERSION_NTLM_SSO -> CURL_VERSION_NTLM_WB --- docs/libcurl/symbols-in-versions | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index dfc2efe31..028bb1a57 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -20,7 +20,7 @@ CURLAUTH_DIGEST_IE 7.19.3 CURLAUTH_GSSNEGOTIATE 7.10.6 CURLAUTH_NONE 7.10.6 CURLAUTH_NTLM 7.10.6 -CURLAUTH_NTLM_SSO 7.22.0 +CURLAUTH_NTLM_WB 7.22.0 CURLAUTH_ONLY 7.21.3 CURLCLOSEPOLICY_CALLBACK 7.7 CURLCLOSEPOLICY_LEAST_RECENTLY_USED 7.7 @@ -680,7 +680,7 @@ CURL_VERSION_KERBEROS4 7.10 CURL_VERSION_LARGEFILE 7.11.1 CURL_VERSION_LIBZ 7.10 CURL_VERSION_NTLM 7.10.6 -CURL_VERSION_NTLM_SSO 7.22.0 +CURL_VERSION_NTLM_WB 7.22.0 CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 -- cgit v1.2.1 From 9dfd7a3d132e554c90b45d14d5cef0c96dfad7a0 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Mon, 12 Sep 2011 14:45:22 -0700 Subject: Document NTLM winbind options (and caveats) --- docs/libcurl/curl_easy_setopt.3 | 18 +++++++++++++++++- docs/libcurl/curl_version_info.3 | 5 +++++ 2 files changed, 22 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 77a24f4a2..90ebd8fd2 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -91,7 +91,9 @@ SIGPIPE signals, which otherwise are sent by the system when trying to send data to a socket which is closed in the other end. libcurl makes an effort to never cause such SIGPIPEs to trigger, but some operating systems have no way to avoid them and even on those that have there are some corner cases when -they may still happen, contrary to our desire. +they may still happen, contrary to our desire. In addition, using +\fICURLAUTH_NTLM_WB\fP authentication could cause a SIGCHLD signal to be +raised. .IP CURLOPT_WILDCARDMATCH Set this option to 1 if you want to transfer multiple files according to a file name pattern. The pattern can be specified as part of the @@ -890,6 +892,20 @@ prevent the password from being eavesdropped. You need to build libcurl with OpenSSL support for this option to work, or build libcurl on Windows. +.IP CURLAUTH_NTLM_WB +NTLM delegating to winbind helper. Authentication is performed by a separate +binary application that is executed when needed. The name of the application +is specified at compile time but is typically /usr/bin/ntlm_auth +(Added in 7.22.0) + +Note that libcurl will fork when necessary to run the winbind application and +kill it when complete, calling waitpid() to await its exit when done. On POSIX +operating systems, killing the process will cause a SIGCHLD signal to be +raised (regardless of whether \fICURLOPT_NOSIGNAL\fP is set), which must be +handled intelligently by the application. In particular, the application must +not unconditionally call wait() in its SIGCHLD signal handler to avoid being +subject to a race condition. This behavior is subject to change in future +versions of libcurl. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl will automatically select the one it finds most diff --git a/docs/libcurl/curl_version_info.3 b/docs/libcurl/curl_version_info.3 index 4481830a3..ccb202834 100644 --- a/docs/libcurl/curl_version_info.3 +++ b/docs/libcurl/curl_version_info.3 @@ -128,6 +128,11 @@ 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 CURLOPT_CONV_* callbacks. (Added in 7.15.4) +.IP CURL_VERSION_TLSAUTH_SRP +libcurl was built with support for TLS-SRP. (Added in 7.21.4) +.IP CURL_VERSION_NTLM_WB +libcurl was built with support for NTLM delegation to a winbind helper. +(Added in 7.22.0) .RE \fIssl_version\fP is an ASCII string for the OpenSSL version used. If libcurl has no SSL support, this is NULL. -- cgit v1.2.1 From dae0b7d1aaccbc9ed91fdc228ddc3cbeb0a7f5f5 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sun, 18 Sep 2011 14:16:13 +0100 Subject: CURLOPT_URL: Expanded URL description Expanded the section about CURLOPT_URL to include the format of the URL and detailed information and examples relating to specific protocols. --- docs/libcurl/curl_easy_setopt.3 | 117 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 107 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 90ebd8fd2..bdc0e9707 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -584,20 +584,117 @@ POST/PUT and a 401 or 407 is received immediately afterwards. .SH NETWORK OPTIONS .IP CURLOPT_URL The actual URL to deal with. The parameter should be a char * to a zero -terminated string. +terminated string which must be URL-encoded in the following format: -If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will -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 are supported. +scheme://host:port/path -The string given to CURLOPT_URL must be url-encoded and follow RFC 2396 +For a greater explaination of the format please see RFC 2396 (http://curl.haxx.se/rfc/rfc2396.txt). -Starting with version 7.20.0, the fragment part of the URI will not be send as -part of the path, which was the case previously. +If the given URL lacks the scheme, or protocol, part ("http://" or "ftp://" +etc), libcurl will attempt to resolve which protocol to use based on the +given host mame. If the protocol is not supported, libcurl will return +(\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 +information on which protocols are supported. + +The host part of the URL contains the address of the server that you want to +connect to. This can be the fully qualified domain name of the server, the +local network name of the machine on your network or the IP address of the +server or machine represented by either an IPv4 or IPv6 address. For example: + +http://www.domain.com/ + +http://hostname/ + +http://192.168.0.1/ + +http://[2001:1890:1112:1::20]/ + +It is also possible to specify the user name and password as part of the +host, for some protocols, when connecting to servers that require +authentication. + +HTTP and FTP support this type of authentication as follows: + +http://name:password@www.domain.com +ftp://name:password@ftp.domain.com + +The port is optional and when not specified libcurl will use the default port +based on the determined or specified protocol: 80 for http, 21 for ftp and 25 +for smtp, etc. The following examples show how to specify the port: + +http://www.weirdserver.com:8080/ - This will connect to a web server using +port 8080. + +smtp://mail.domain.com:587/ - This will connect to a smtp server on the +alternative mail port. + +The path part of the URL is protocol specific and whilst some examples are +given below this list is not conclusive: + +.B HTTP + +The path part of a HTTP request specifies the file to retrieve and from what +directory. If the directory is not specified then the web server's root +directory is used. If the file is omitted then the default document will be +retrieved for either the directory specified or the root directory. + +http://www.netscape.com - This gets the main page (index.html in this +example) from Netscape's web server. + +http://www.netscape.com/index.html - This returns the main page from Netscape +by specifing the page to get. + +http://www.netscape.com/contactus/ - This returns the default document from +the contact us directory. + +.B FTP + +The path part of a FTP request specifies the file to retrieve and from what +directory. If the file part is omitted then libcurl downloads the directory +listing for the directory specified. If the directory is omitted then +the directory listing for the root / home directory will be returned. + +ftp://cool.haxx.se - This retrieves the directory listing for our FTP server. + +ftp://cool.haxx.se/readme.txt - This downloads the file readme.txt from the +root directory. + +ftp://cool.haxx.se/libcurl/readme.txt - This downloads readme.txt from the +libcurl directory. + +ftp://user:password@my.site.com/readme.txt - This retrieves the readme.txt +file from the user's home directory. When a username and password is +specified, everything that is specified in the path part is relative to the +user's home directory. To retrieve files from the root directory or a +directory underneath the root directory then the absolute path must be +specified by using an additional forward slash to the beginning of the path. + +ftp://user:password@my.site.com//readme.txt - This retrieves the readme.txt +from the root directory when logging in as a specified user. + +.B SMTP + +The path part of a SMTP request specifies the host name to present during +communication with the mail server. If the path is omitted then libcurl will +perform a call to \fCurl_gethostname\fP to resolve the local computer's +host name. However, \fCurl_gethostname\fP does not return the fully qualified +domain name that is required by some mail servers and specifing this path +allows you to specify an alternative nane such as your machine's fully +qualified domain name which you might have obtained from an external function +such as gethostname or getaddrinfo. + +smtp://mail.domain.com - This connects to the mail server at domain.com and +sends your local computer's host name in the HELO / EHLO command. + +smtp://mail.domain.com/client.domain.com - This will send client.domain.com +in the HELO / EHLO command to the mail server at domain.com. + +.B NOTES + +Starting with version 7.20.0, the fragment part of the URI will not be sent as +part of the path, which was previously the case. \fICURLOPT_URL\fP is the only option that \fBmust\fP be set before \fIcurl_easy_perform(3)\fP is called. -- cgit v1.2.1 From 00532341b568653e78bc676feedf225fe7c2948f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 18 Sep 2011 23:42:29 +0200 Subject: CURLOPT_URL docs: no need to mention function names --- docs/libcurl/curl_easy_setopt.3 | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index bdc0e9707..9f6f11d89 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -672,24 +672,23 @@ directory underneath the root directory then the absolute path must be specified by using an additional forward slash to the beginning of the path. ftp://user:password@my.site.com//readme.txt - This retrieves the readme.txt -from the root directory when logging in as a specified user. +from the root directory when logging in as a specified user. .B SMTP The path part of a SMTP request specifies the host name to present during communication with the mail server. If the path is omitted then libcurl will -perform a call to \fCurl_gethostname\fP to resolve the local computer's -host name. However, \fCurl_gethostname\fP does not return the fully qualified -domain name that is required by some mail servers and specifing this path -allows you to specify an alternative nane such as your machine's fully -qualified domain name which you might have obtained from an external function -such as gethostname or getaddrinfo. +attempt to to resolve the local computer's host name. However, that will not +return the fully qualified domain name that is required by some mail servers +and specifing this path allows you to specify an alternative name such as your +machine's fully qualified domain name which you might have obtained from an +external function such as gethostname or getaddrinfo. smtp://mail.domain.com - This connects to the mail server at domain.com and sends your local computer's host name in the HELO / EHLO command. -smtp://mail.domain.com/client.domain.com - This will send client.domain.com -in the HELO / EHLO command to the mail server at domain.com. +smtp://mail.domain.com/client.domain.com - This will send client.domain.com in +the HELO / EHLO command to the mail server at domain.com. .B NOTES -- cgit v1.2.1 From 2d6796aac51d8a5963f552b8fa23a2396a987913 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 25 Sep 2011 17:34:12 +0200 Subject: curl_multi_fdset: avoid FD_SET out of bounds If a socket is larger than FD_SETSIZE, avoid using FD_SET() on the platforms where this is possible. Bug: http://curl.haxx.se/bug/view.cgi?id=3413274 Reported by: Tim Starling --- docs/libcurl/curl_multi_fdset.3 | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index fadc53812..bdb389f26 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -53,6 +53,14 @@ When doing select(), you should use \fBcurl_multi_timeout\fP to figure out how long to wait for action. Call \fIcurl_multi_perform\fP even if no activity has been seen on the fd_sets after the timeout expires as otherwise internal retries and timeouts may not work as you'd think and want. + +If one of the sockets used by libcurl happens to be larger than what can be +set in an fd_set, which on POSIX systems means that the file descriptor is +larger than FD_SETSIZE, then libcurl will try to not set it. Setting a too +large file descriptor in an fd_set implies an out of bounds write which can +cause crashes, or worse. The effect of NOT storing it will possibly save you +from the crash, but will make your program NOT wait for sockets it should wait +for... .SH RETURN VALUE CURLMcode type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP -- cgit v1.2.1 From 119f43360b60c903982104944145d9cd8b7ec054 Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Sun, 25 Sep 2011 18:53:29 +0200 Subject: allow write callbacks to indicate OOM to libcurl Allow (*curl_write_callback) write callbacks to return CURL_WRITEFUNC_OUT_OF_MEMORY to properly indicate libcurl of OOM conditions inside the callback itself. --- docs/libcurl/curl_easy_setopt.3 | 5 +++++ docs/libcurl/symbols-in-versions | 1 + 2 files changed, 6 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9f6f11d89..b9d42b54e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -160,6 +160,11 @@ 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. +From 7.22.1, the function can return CURL_WRITEFUNC_OUT_OF_MEMORY to indicate +libcurl that an attempt to dynamically allocate memory from within the write +callback itself has failed. This will abort the transfer and make libcurl +return CURLE_OUT_OF_MEMORY. + This function may be called with zero bytes data if the transferred file is empty. diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 028bb1a57..5c985bde7 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -685,4 +685,5 @@ CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 CURL_VERSION_TLSAUTH_SRP 7.21.4 +CURL_WRITEFUNC_OUT_OF_MEMORY 7.22.1 CURL_WRITEFUNC_PAUSE 7.18.0 -- cgit v1.2.1 From d9f686db88cc6ed01af8f7d690a9e44b7dcfb6ee Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Mon, 26 Sep 2011 03:18:51 +0200 Subject: remove short-lived CURL_WRITEFUNC_OUT_OF_MEMORY --- docs/libcurl/curl_easy_setopt.3 | 5 ----- docs/libcurl/symbols-in-versions | 1 - 2 files changed, 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b9d42b54e..9f6f11d89 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -160,11 +160,6 @@ 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. -From 7.22.1, the function can return CURL_WRITEFUNC_OUT_OF_MEMORY to indicate -libcurl that an attempt to dynamically allocate memory from within the write -callback itself has failed. This will abort the transfer and make libcurl -return CURLE_OUT_OF_MEMORY. - This function may be called with zero bytes data if the transferred file is empty. diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 5c985bde7..028bb1a57 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -685,5 +685,4 @@ CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 CURL_VERSION_TLSAUTH_SRP 7.21.4 -CURL_WRITEFUNC_OUT_OF_MEMORY 7.22.1 CURL_WRITEFUNC_PAUSE 7.18.0 -- cgit v1.2.1 From 9f2f8d5122e1a88835bca132dab0d03fdec0da48 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 28 Sep 2011 13:53:59 +0200 Subject: multi docs: extended the multi_socket API description --- docs/libcurl/libcurl-multi.3 | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index d84bafcad..6cad56756 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -118,13 +118,32 @@ If you want to re-use an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re-add it again (possibly after having altered some options at your own choice). .SH "MULTI_SOCKET" -Since 7.16.0, the \fIcurl_multi_socket_action(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-performance API that will make a significant -difference for applications using large numbers of simultaneous connections. - -\fIcurl_multi_socket_action(3)\fP is then used -instead of \fIcurl_multi_perform(3)\fP. +\fIcurl_multi_socket_action(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-performance API that will make a significant difference for applications +using large numbers of simultaneous connections. + +\fIcurl_multi_socket_action(3)\fP is then used instead of +\fIcurl_multi_perform(3)\fP. + +When using this API, you add easy handles to the multi handle just as with the +normal multi interface. Then you also set two callbacks with the +CURLMOPT_SOCKETFUNCTION and CURLMOPT_TIMERFUNCTION options to +\fIcurl_multi_setopt(3)\fP. + +The API is then designed to inform your application about which sockets +libcurl is currently using and for what activities (read and/or write) on +those sockets your application is expected to wait for. + +Your application must then make sure to receive all sockets informed about in +the CURLMOPT_SOCKETFUNCTION callback and make sure it reacts on the given +activity on them. When a socket has the given activity, you call +\fIcurl_multi_socket_action(3)\fP specifying which socket and action there +are. + +The CURLMOPT_TIMERFUNCTION callback is called to set a timeout. When that +timeout expires, your application should call the +\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout. .SH "BLOCKING" A few areas in the code are still using blocking code, even when used from the multi interface. While we certainly want and intend for these to get fixed in -- cgit v1.2.1 From 5793bc370c794a10e6ed014cb535a47672842ae6 Mon Sep 17 00:00:00 2001 From: Alejandro Alvarez Date: Tue, 20 Sep 2011 17:43:54 +0200 Subject: SSL session sharing support added With locking, plus test, plus documentation --- docs/libcurl/curl_share_setopt.3 | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index 5fff33d25..295423ae3 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -64,6 +64,11 @@ Cached DNS hosts will be shared across the easy handles using this shared object. Note that when you use the multi interface, all easy handles added to the same multi handle will share DNS cache by default without this having to be used! +.IP CURL_LOCK_DATA_SSL_SESSION +SSL session IDs will be shared accross the easy handles using this shared +object. This will reduce the time spent in the SSL handshake when reconnecting +to the same server. Note SSL session IDs are reused within the same easy handle +by default. .RE .IP CURLSHOPT_UNSHARE This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that -- cgit v1.2.1 From 57fffa728b4f34fbf2e2b431ba788287239248f4 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Thu, 22 Sep 2011 19:47:45 +0100 Subject: curl_easy_setopt: A brief tidy up Slight rewording of the CURLOPT_URL SMTP sub-section. Corrected the incorrect use of hyphens on the three uses of "zero-terminated" with "zero terminated" to match the rest of the document. Corrected the use of an out of place hyphen in CURLOPT_NOPROXY section. --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9f6f11d89..7ef0d8790 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -678,11 +678,11 @@ from the root directory when logging in as a specified user. The path part of a SMTP request specifies the host name to present during communication with the mail server. If the path is omitted then libcurl will -attempt to to resolve the local computer's host name. However, that will not +attempt to to resolve the local computer's host name. However, this will not return the fully qualified domain name that is required by some mail servers -and specifing this path allows you to specify an alternative name such as your -machine's fully qualified domain name which you might have obtained from an -external function such as gethostname or getaddrinfo. +and specifing this path allows you to specify an alternative name, such as +your machine's fully qualified domain name, which you might have obtained +from an external function such as gethostname or getaddrinfo. smtp://mail.domain.com - This connects to the mail server at domain.com and sends your local computer's host name in the HELO / EHLO command. @@ -765,7 +765,7 @@ affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version used for "regular" HTTP requests is instead controled with \fICURLOPT_HTTP_VERSION\fP. .IP CURLOPT_NOPROXY -Pass a pointer to a zero terminated string. The should be a comma- separated +Pass a pointer to a zero terminated string. The should be a comma separated list of hosts which do not use a proxy, if one is specified. The only wildcard is a single * character, which matches all hosts, and effectively disables the proxy. Each name in this list is matched as either a domain which @@ -1029,12 +1029,12 @@ You need to build libcurl with GnuTLS or OpenSSL with TLS-SRP support for this to work. (Added in 7.21.4) .RE .IP CURLOPT_TLSAUTH_USERNAME -Pass a char * as parameter, which should point to the zero-terminated username +Pass a char * as parameter, which should point to the zero terminated username to use for the TLS authentication method specified with the \fICURLOPT_TLSAUTH_TYPE\fP option. Requires that the \fICURLOPT_TLS_PASSWORD\fP option also be set. (Added in 7.21.4) .IP CURLOPT_TLSAUTH_PASSWORD -Pass a char * as parameter, which should point to the zero-terminated password +Pass a char * as parameter, which should point to the zero terminated password to use for the TLS authentication method specified with the \fICURLOPT_TLSAUTH_TYPE\fP option. Requires that the \fICURLOPT_TLS_USERNAME\fP option also be set. (Added in 7.21.4) @@ -1567,7 +1567,7 @@ a reply. Initiate the shutdown and wait for a reply. .RE .IP CURLOPT_FTP_ACCOUNT -Pass a pointer to a zero-terminated string (or NULL to disable). When an FTP +Pass a pointer to a zero terminated string (or NULL to disable). When an FTP server asks for "account data" after user name and password has been provided, this data is sent off using the ACCT command. (Added in 7.13.0) .IP CURLOPT_FTP_FILEMETHOD -- cgit v1.2.1 From 5898a6a09b211fc7e22a3e2c721d9a08293f864e Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Wed, 28 Sep 2011 21:33:42 -0700 Subject: curl_easy_setopt: Added scp and sftp to the URL section --- docs/libcurl/curl_easy_setopt.3 | 59 ++++++++++++++++++++++++++++++++--------- 1 file changed, 47 insertions(+), 12 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7ef0d8790..b888e4027 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -588,7 +588,7 @@ terminated string which must be URL-encoded in the following format: scheme://host:port/path -For a greater explaination of the format please see RFC 2396 +For a greater explanation of the format please see RFC 2396 (http://curl.haxx.se/rfc/rfc2396.txt). If the given URL lacks the scheme, or protocol, part ("http://" or "ftp://" @@ -603,7 +603,7 @@ connect to. This can be the fully qualified domain name of the server, the local network name of the machine on your network or the IP address of the server or machine represented by either an IPv4 or IPv6 address. For example: -http://www.domain.com/ +http://www.example.com/ http://hostname/ @@ -638,20 +638,22 @@ given below this list is not conclusive: The path part of a HTTP request specifies the file to retrieve and from what directory. If the directory is not specified then the web server's root directory is used. If the file is omitted then the default document will be -retrieved for either the directory specified or the root directory. +retrieved for either the directory specified or the root directory. The +exact resource returned for each URL is entirely dependent on the server's +configuration. http://www.netscape.com - This gets the main page (index.html in this example) from Netscape's web server. http://www.netscape.com/index.html - This returns the main page from Netscape -by specifing the page to get. +by specifying the page to get. http://www.netscape.com/contactus/ - This returns the default document from -the contact us directory. +the contactus directory. .B FTP -The path part of a FTP request specifies the file to retrieve and from what +The path part of an FTP request specifies the file to retrieve and from what directory. If the file part is omitted then libcurl downloads the directory listing for the directory specified. If the directory is omitted then the directory listing for the root / home directory will be returned. @@ -664,23 +666,24 @@ root directory. ftp://cool.haxx.se/libcurl/readme.txt - This downloads readme.txt from the libcurl directory. -ftp://user:password@my.site.com/readme.txt - This retrieves the readme.txt +ftp://user:password@my.example.com/readme.txt - This retrieves the readme.txt file from the user's home directory. When a username and password is specified, everything that is specified in the path part is relative to the user's home directory. To retrieve files from the root directory or a directory underneath the root directory then the absolute path must be -specified by using an additional forward slash to the beginning of the path. +specified by prepending an additional forward slash to the beginning of the +path. -ftp://user:password@my.site.com//readme.txt - This retrieves the readme.txt +ftp://user:password@my.example.com//readme.txt - This retrieves the readme.txt from the root directory when logging in as a specified user. .B SMTP The path part of a SMTP request specifies the host name to present during communication with the mail server. If the path is omitted then libcurl will -attempt to to resolve the local computer's host name. However, this will not +attempt to resolve the local computer's host name. However, this may not return the fully qualified domain name that is required by some mail servers -and specifing this path allows you to specify an alternative name, such as +and specifying this path allows you to set an alternative name, such as your machine's fully qualified domain name, which you might have obtained from an external function such as gethostname or getaddrinfo. @@ -690,6 +693,38 @@ sends your local computer's host name in the HELO / EHLO command. smtp://mail.domain.com/client.domain.com - This will send client.domain.com in the HELO / EHLO command to the mail server at domain.com. +.B SCP + +The path part of an SCP request specifies the file to retrieve and from what +directory. The file part may not be omitted. The file is taken as an absolute +path from the root directory on the server. To specify a path relative to +the user's home directory on the server, prepend ~/ to the path portion. +If the user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD\fP or \fBCURLOPT_USERNAME\fP option. + +scp://user@example.com/etc/issue - This specifies the file /etc/issue + +scp://example.com/~/my-file - This specifies the file my-file in the +user's home directory on the server + +.B SFTP + +The path part of an SFTP request specifies the file to retrieve and from what +directory. If the file part is omitted then libcurl downloads the directory +listing for the directory specified. If the path ends in a / then a directory +listing is returned instead of a file. If the path is omitted entirely then +the directory listing for the root / home directory will be returned. +If the user name is not embedded in the URL, it can be set with the +\fICURLOPT_USERPWD\fP or \fBCURLOPT_USERNAME\fP option. + +sftp://user:pass@example.com/etc/issue - This specifies the file /etc/issue + +sftp://user@example.com/~/my-file - This specifies the file my-file in the +user's home directory + +sftp://ssh.example.com/~/Documents/ - This requests a directory listing +of the Documents directory under the user's home directory + .B NOTES Starting with version 7.20.0, the fragment part of the URI will not be sent as @@ -762,7 +797,7 @@ this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP (added in 7.19.4), If you set \fBCURLOPT_PROXYTYPE\fP to \fICURLPROXY_HTTP_1_0\fP, it will only affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version -used for "regular" HTTP requests is instead controled with +used for "regular" HTTP requests is instead controlled with \fICURLOPT_HTTP_VERSION\fP. .IP CURLOPT_NOPROXY Pass a pointer to a zero terminated string. The should be a comma separated -- cgit v1.2.1 From 5d45285cf39c27135542edcbbadc71c1bd3d90ab Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 30 Sep 2011 23:42:47 +0200 Subject: tutorial: clarify the handle sharing when treaded Previously there was wording that made people uncertain of the exact rules. Feedback by: Julien Royer and Georg Lippitsch URL: http://curl.haxx.se/mail/lib-2011-09/0357.html --- docs/libcurl/libcurl-tutorial.3 | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 1efd6fbb3..ff1a06be2 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -249,9 +249,11 @@ complication for you. Given simply the URL to a file, libcurl will take care of all the details needed to get the file moved from one machine to another. .SH "Multi-threading Issues" -The first basic rule is that you must \fBnever\fP share a libcurl handle (be -it easy or multi or whatever) between multiple threads. Only use one handle in -one thread at a time. +The first basic rule is that you must \fBnever\fP simultaneously share a +libcurl handle (be it easy or multi or whatever) between multiple +threads. Only use one handle in one thread at any time. You can pass the +handles around among threads, but you must never use a single handle from more +than one thread at any given 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) - -- cgit v1.2.1 From 15e3e451702396e870c00d186ff7710792a1f28e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 3 Oct 2011 22:32:36 +0200 Subject: share: don't use SSL unless enabled Don't even declare the struct members for disabled features Introducing the CURLSHE_NOT_BUILT_IN return code for the share interface when trying to set a sharing option that has been disabled (or not enabled) in the library. --- docs/libcurl/libcurl-errors.3 | 3 +++ docs/libcurl/symbols-in-versions | 1 + 2 files changed, 4 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index beabf98f0..7954a83db 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -277,3 +277,6 @@ An invalid share object was passed to the function. .IP "CURLSHE_NOMEM (4)" Not enough memory was available. (Added in 7.12.0) +.IP "CURLSHE_NOT_BUILT_IN (5)" +The requsted sharing could not be done because the library you use don't have +that particular feature enabled. (Added in 7.23.0) diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 028bb1a57..8c1792c88 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -550,6 +550,7 @@ CURLSHE_BAD_OPTION 7.10.3 CURLSHE_INVALID 7.10.3 CURLSHE_IN_USE 7.10.3 CURLSHE_NOMEM 7.12.0 +CURLSHE_NOT_BUILT_IN 7.23.0 CURLSHE_OK 7.10.3 CURLSHOPT_LOCKFUNC 7.10.3 CURLSHOPT_NONE 7.10.3 -- cgit v1.2.1 From 381459fa65a37943417462b32cb312ea9b3c7a62 Mon Sep 17 00:00:00 2001 From: Dominique Leuenberger Date: Mon, 3 Oct 2011 17:53:43 +0200 Subject: m4: Use x in order to avoid variable 'x' set but not used [-Werror=unused-but-set-variable] This error could be caused by configure scripts being run with -Werror -Wall, which would lead to libcurl being detected as unusable. --- docs/libcurl/libcurl.m4 | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 01a0575cc..8cada0523 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -157,6 +157,7 @@ x=CURLOPT_FILE; x=CURLOPT_ERRORBUFFER; x=CURLOPT_STDERR; x=CURLOPT_VERBOSE; +if (x) ; ])],libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) CPPFLAGS=$_libcurl_save_cppflags -- cgit v1.2.1 From 337252bdd421ce8262da183a577a7f8b44641385 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 16 Oct 2011 23:38:48 +0200 Subject: curl_multi_fdset: clarify the max_fd == -1 case Elaborate what max_fd == -1 means Remove the reference to CURLM_CALL_MULTI_PERFORM as modern libcurl versions don't ever return that. --- docs/libcurl/curl_multi_fdset.3 | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_fdset.3 b/docs/libcurl/curl_multi_fdset.3 index bdb389f26..3dbdc4504 100644 --- a/docs/libcurl/curl_multi_fdset.3 +++ b/docs/libcurl/curl_multi_fdset.3 @@ -40,14 +40,15 @@ but be sure to FD_ZERO them before calling this function as 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. -To be sure to have up-to-date results, you should call -\fIcurl_multi_perform\fP until it does not return CURLM_CALL_MULTI_PERFORM -prior to calling \fIcurl_multi_fdset\fP. This will make sure that libcurl has -updated the handles' socket states. - 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 -libcurl set. +libcurl set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl +currently does something that isn't possible for your application to monitor +with a socket and unfortunately you can then not know exactly when the current +action is completed using select(). When max_fd returns with -1, you need to +wait a while and then proceed and call \fIcurl_multi_perform\fP anyway. How +long to wait? I would suggest 100 milliseconds at least, but you may want to +test it out in your own particular conditions to find a suitable value. When doing select(), you should use \fBcurl_multi_timeout\fP to figure out how long to wait for action. Call \fIcurl_multi_perform\fP even if no activity has -- cgit v1.2.1 From adaa3f6e141ae4e721fb2d426a9b7a181ffb4fb8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 20 Oct 2011 08:48:15 +0200 Subject: CURLM_CALL_MULTI_PERFORM: remove mention This return code has not been used since 7.20.0 so we can stop mentioning it for current libcurl. --- docs/libcurl/libcurl-multi.3 | 8 -------- 1 file changed, 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 6cad56756..21cf8218b 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -82,14 +82,6 @@ might need attention. This also makes it very easy for your program to wait for input on your own private file descriptors at the same time or perhaps timeout every now and then, should you want that. -A little note here about the return codes from the multi functions, and -especially the \fIcurl_multi_perform(3)\fP: if you receive -\fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you should call -\fIcurl_multi_perform(3)\fP again, before you select() on more 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". - \fIcurl_multi_perform(3)\fP stores the number of still running transfers in one of its input arguments, and by reading that you can figure out when all the transfers in the multi handles are done. 'done' does not mean -- cgit v1.2.1 From a4471045bba8fc83a64221edc9a126796cb2c820 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Fri, 21 Oct 2011 22:59:50 +0100 Subject: curl_easy_setopt: Added pop3 to CURLOPT_URL. Added pop3 username and password example as well as an explanation of how path part of the URL is used under pop3. Additionally have corrected a couple of typos. --- docs/libcurl/curl_easy_setopt.3 | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index b888e4027..f4f0c80e3 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -615,10 +615,11 @@ It is also possible to specify the user name and password as part of the host, for some protocols, when connecting to servers that require authentication. -HTTP and FTP support this type of authentication as follows: +For exammple the following types of authentication support this: -http://name:password@www.domain.com -ftp://name:password@ftp.domain.com +http://user:password@www.domain.com +ftp://user:password@ftp.domain.com +pop3://user:password@mail.domain.com The port is optional and when not specified libcurl will use the default port based on the determined or specified protocol: 80 for http, 21 for ftp and 25 @@ -693,6 +694,15 @@ sends your local computer's host name in the HELO / EHLO command. smtp://mail.domain.com/client.domain.com - This will send client.domain.com in the HELO / EHLO command to the mail server at domain.com. +.B POP3 + +The path part of a POP3 request specifies the mailbox (message) to retrieve. +If the mailbox is not specified then a list of waiting messages is returned +instead. + +pop3://user:password@mail.domain.com - This lists the available messages +pop3://user:password@mail.domain.com/1 - This retrieves the first message + .B SCP The path part of an SCP request specifies the file to retrieve and from what @@ -717,7 +727,8 @@ the directory listing for the root / home directory will be returned. If the user name is not embedded in the URL, it can be set with the \fICURLOPT_USERPWD\fP or \fBCURLOPT_USERNAME\fP option. -sftp://user:pass@example.com/etc/issue - This specifies the file /etc/issue +sftp://user:password@example.com/etc/issue - This specifies the file +/etc/issue sftp://user@example.com/~/my-file - This specifies the file my-file in the user's home directory -- cgit v1.2.1 From e771344611e7405b73eff7744ca315a15c9ec50a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 24 Oct 2011 00:13:47 +0200 Subject: curl_easy_setopt.3: fix typo shoot, Dan Fandrich already had this pointed out... --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index f4f0c80e3..394bd7798 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -615,7 +615,7 @@ It is also possible to specify the user name and password as part of the host, for some protocols, when connecting to servers that require authentication. -For exammple the following types of authentication support this: +For example the following types of authentication support this: http://user:password@www.domain.com ftp://user:password@ftp.domain.com -- cgit v1.2.1 From 5850cc4808ab3669e7a973bd492a630f51804df3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 24 Oct 2011 16:43:53 +0200 Subject: curl_easy_setopt.3: headers can be CURL_MAX_HTTP_HEADER bytes Mention this maximum header size for the header callback cases --- docs/libcurl/curl_easy_setopt.3 | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 394bd7798..31464bf2a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -171,8 +171,12 @@ Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA\fP option. The callback function will be passed as much data as possible in all invokes, but you cannot possibly make any assumptions. It may be one byte, it may be -thousands. The maximum amount of data that can be passed to the write callback -is defined in the curl.h header file: CURL_MAX_WRITE_SIZE. +thousands. The maximum amount of body data that can be passed to the write +callback is defined in the curl.h header file: CURL_MAX_WRITE_SIZE (the usual +default is 16K). If you however have \fICURLOPT_HEADER\fP set, which sends +header data to the write callback, you can get up to +\fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually +means 100K. .IP CURLOPT_WRITEDATA Data pointer to pass to the file write function. If you use the \fICURLOPT_WRITEFUNCTION\fP option, this is the pointer you'll get as @@ -354,6 +358,9 @@ of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return \fICURL_WRITE_ERROR\fP. +A complete header that is passed to this function can be up to +\fICURL_MAX_HTTP_HEADER\fP (100K) bytes. + If this option is not set, or if it is set to NULL, but \fICURLOPT_HEADERDATA\fP (\fICURLOPT_WRITEHEADER\fP) is set to anything but NULL, the function used to accept response data will be used instead. That is, -- cgit v1.2.1 From 120025b7f853562af685e6385794c518eccc28c4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 27 Oct 2011 09:22:15 +0200 Subject: libcurl-multi.3: update the list of areas still blocking --- docs/libcurl/libcurl-multi.3 | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 21cf8218b..44cf54313 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -142,8 +142,7 @@ multi interface. While we certainly want and intend for these to get fixed in the future, you should be aware of the following current restrictions: .nf - - Name resolves on non-windows unless c-ares is used - - GnuTLS SSL connections + - Name resolves unless the c-ares or threaded-resolver backends are used - NSS SSL connections - Active FTP connections - HTTP proxy CONNECT operations -- cgit v1.2.1 From 8d0a504f0d34c2471393ef23fb2345c73c5d4746 Mon Sep 17 00:00:00 2001 From: Jason Glasgow Date: Tue, 12 Apr 2011 11:34:28 -0400 Subject: CURLOPT_DNS_SERVERS: set name servers if possible --- docs/libcurl/curl_easy_setopt.3 | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 31464bf2a..3b86476ea 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2045,6 +2045,20 @@ resolves, by including a string in the linked list that uses the format and port number must exactly match what was already added previously. (Added in 7.21.3) +.IP CURLOPT_DNS_SERVERS +Set the list of DNS servers to be used instead of the system default. +The format of the dns servers option is: + +host[:port][,host[:port]]... + +For example: + +192.168.1.100,192.168.1.101,3.4.5.6 + +This option requires that libcurl was built with a resolver backend that +supports this operation. The c-ares backend is the only such one. + +(Added in 7.24.0) .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be -- cgit v1.2.1 From f64812ca63d5dbcd8b255cc1102fcc321997eceb Mon Sep 17 00:00:00 2001 From: Jonas Schnelli Date: Fri, 18 Nov 2011 15:55:09 +0100 Subject: SFTP: support '*' prefix for quote operations prefixing a command with '*' means it is allowed to fail without aborting the chain actions --- docs/libcurl/symbols-in-versions | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 8c1792c88..ec902fd4e 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -320,6 +320,7 @@ CURLOPT_DEBUGDATA 7.9.6 CURLOPT_DEBUGFUNCTION 7.9.6 CURLOPT_DIRLISTONLY 7.17.0 CURLOPT_DNS_CACHE_TIMEOUT 7.9.3 +CURLOPT_DNS_SERVERS 7.24.0 CURLOPT_DNS_USE_GLOBAL_CACHE 7.9.3 7.11.1 CURLOPT_EGDSOCKET 7.7 CURLOPT_ENCODING 7.10 -- cgit v1.2.1 From 66617b79d7fb8310f55ce4008bbd169157ac376e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 18 Nov 2011 20:27:07 +0100 Subject: CURLOPT_QUOTE: SFTP supports the '*'-prefix now --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3b86476ea..29151802f 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1485,9 +1485,9 @@ fully valid list of 'struct curl_slist' structs properly filled in with text strings. Use \fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Disable this operation again by setting a NULL -to this option. When speaking to a FTP server, prefix the command with an -asterisk (*) to make libcurl continue even if the command fails as by default -libcurl will stop at first failure. +to this option. When speaking to a FTP (or SFTP since 7.24.0) server, prefix +the command with an asterisk (*) to make libcurl continue even if the command +fails as by default libcurl will stop at first failure. The set of valid FTP commands depends on the server (see RFC959 for a list of mandatory commands). -- cgit v1.2.1 From 4403e82f32de9b339cdacea6989e4a827a7b3a02 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 24 Nov 2011 22:55:09 +0100 Subject: symbols.pl: provide LIBCURL_HAS macro for apps Experience has shown that the symbols-in-versions file is very useful to applications that want to build with a wide range of libcurl versions. It is however easy to get it wrong and the source gets a bit messy with all the fixed numerical comparisions. The point of this script is to provide an easy-to-use macro for libcurl- using applications to do preprocessor checks for specific libcurl defines, and yet make the code clearly show what the macro is used for. --- docs/libcurl/Makefile.am | 2 +- docs/libcurl/symbols.pl | 100 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 1 deletion(-) create mode 100755 docs/libcurl/symbols.pl (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 45c8fee97..50f1a3b23 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -82,7 +82,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ CLEANFILES = $(HTMLPAGES) $(PDFPAGES) EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI \ - symbols-in-versions + symbols-in-versions symbols.pl MAN2HTML= roffit --mandir=. < $< >$@ SUFFIXES = .3 .html diff --git a/docs/libcurl/symbols.pl b/docs/libcurl/symbols.pl new file mode 100755 index 000000000..d1ff7a656 --- /dev/null +++ b/docs/libcurl/symbols.pl @@ -0,0 +1,100 @@ +#!/usr/bin/perl +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| +# +# Copyright (C) 2011, Daniel Stenberg, , et al. +# +# This software is licensed as described in the file COPYING, which +# you should have received as part of this distribution. The terms +# are also available at http://curl.haxx.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +########################################################################### +# +# Experience has shown that the symbols-in-versions file is very useful to +# applications that want to build with a wide range of libcurl versions. +# It is however easy to get it wrong and the source gets a bit messy with all +# the fixed numerical comparisions. +# +# The point of this script is to provide an easy-to-use macro for libcurl- +# using applications to do preprocessor checks for specific libcurl defines, +# and yet make the code clearly show what the macro is used for. +# +# Run this script and generate libcurl-symbols.h and then use that header in +# a fashion similar to: +# +# #include "libcurl-symbols.h" +# +# #if LIBCURL_HAS(CURLOPT_MUTE) +# has mute +# #else +# no mute +# #endif +# +# +open F, " + +#define LIBCURL_HAS(x) \\ + (defined(x ## _FIRST) && (x ## _FIRST <= LIBCURL_VERSION_NUM) && \\ + (!defined(x ## _LAST) || ( x ## _LAST >= LIBCURL_VERSION_NUM))) + +EOS + ; + +while() { + if(/^(CURL[^ ]*)[ \t]*(.*)/) { + my ($sym, $vers)=($1, $2); + + my $intr; + my $rm; + my $dep; + + # is there removed info? + if($vers =~ /([\d.]+)[ \t-]+([\d.]+)[ \t]+([\d.]+)/) { + ($intr, $dep, $rm)=($1, $2, $3); + } + # is it a dep-only line? + elsif($vers =~ /([\d.]+)[ \t-]+([\d.]+)/) { + ($intr, $dep)=($1, $2); + } + else { + $intr = $vers; + } + + my $inum = str2num($intr); + + print < Date: Mon, 5 Dec 2011 11:42:10 +0100 Subject: FTP: call opensocket callback properly When the new socket is created for an active connection, it is now done using the open socket callback. Test case 596 was modified to run fine, although it hides the fact that the close callback is still called too many times, as it also gets called for closing sockets that were created with accept(). --- docs/libcurl/curl_easy_setopt.3 | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 29151802f..2f7e40e26 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -294,10 +294,9 @@ argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. Function pointer that should match the \fIcurl_opensocket_callback\fP prototype found in \fI\fP. This function gets called by libcurl instead of the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument -identifies the exact purpose for this particular socket, and currently only -one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the primary connection -(meaning the control connection in the FTP case). Future versions of libcurl -may support more purposes. It passes the resolved peer address as a +identifies the exact purpose for this particular socket: +\fICURLSOCKTYPE_IPCXN\fP is for IP based connections. Future versions of +libcurl may support more purposes. It passes the resolved peer address as a \fIaddress\fP argument so the callback can modify the address or refuse to connect at all. The callback function should return the socket or \fICURL_SOCKET_BAD\fP in case no connection should be established or any error -- cgit v1.2.1 From 361cd03d5861d3639bfcc6b5001f113a05a195cc Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 5 Dec 2011 23:19:50 +0100 Subject: CURLOPT_CONNECTTIMEOUT: default is 300 seconds If the option is set to 0, the default timeout will be used - which in modern libcurl versions equals 300 seconds (== 5 minutes). Bug: http://curl.haxx.se/mail/lib-2011-12/0051.html Reported by: Vladimir Grishchenko --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 2f7e40e26..7cf9a0408 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1970,9 +1970,9 @@ re-use (default behavior). .IP CURLOPT_CONNECTTIMEOUT Pass a long. It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once -it has connected, this option is of no more use. Set to zero to disable -connection timeout (it will then only timeout on the system's internal -timeouts). See also the \fICURLOPT_TIMEOUT\fP option. +it has connected, this option is of no more use. Set to zero to switch to the +default built-in connection timeout - 300 seconds. See also the +\fICURLOPT_TIMEOUT\fP option. In unix-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL\fP is set. -- cgit v1.2.1 From 6e4835c795996ee92ac1aa78733f23a089f310a5 Mon Sep 17 00:00:00 2001 From: Jason Glasgow Date: Fri, 4 Nov 2011 16:48:05 -0400 Subject: CURLOPT_INTERFACE: avoid resolving interfaces names Do not try to resolve interfaces names via DNS by recognizing interface names in a few ways. If the interface option argument has a prefix of "if!" then treat the argument as only an interface. Similarly, if the interface argument is the name of an interface (even if it does not have an IP address assigned), treat it as an interface name. Finally, if the interface argument is prefixed by "host!" treat it as a hostname that must be resolved by /etc/hosts or DNS. These changes allow a client using the multi interfaces to avoid blocking on name resolution if the interface loses its IP address or disappears. --- docs/libcurl/curl_easy_setopt.3 | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7cf9a0408..5f1629d4a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -843,6 +843,15 @@ negotiation. (Added in 7.19.4). 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. + +Starting with 7.24.0: If the parameter starts with "if!" then it is treated as +only as interface name and no attempt will ever be named to do treat it as an +IP address or to do name resolution on it. If the parameter starts with +\&"host!" it is treated as either an IP address or a hostname. Hostnames are +resolved synchronously. Using the if! format is highly recommended when using +the multi interfaces to avoid allowing the code to block. If "if!" is +specified but the parameter does not match an existing interface, +CURLE_INTERFACE_FAILED is returned. .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 -- cgit v1.2.1 From cd4cd668396d501c91800bb8b0cb4577afa3e512 Mon Sep 17 00:00:00 2001 From: Alessandro Ghedini Date: Wed, 14 Dec 2011 22:00:56 +0100 Subject: docs: fix typo in curl_easy_setopt manpage --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5f1629d4a..4d2a22e0b 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1345,7 +1345,7 @@ option and thus you need to concatenate them all in one single string. Set multiple cookies in one string like this: "name1=content1; name2=content2;" etc. -This option sets the cookie header explictly in the outgoing request(s). If +This option sets the cookie header explicitly in the outgoing request(s). If multiple requests are done due to authentication, followed redirections or similar, they will all get this cookie passed on. -- cgit v1.2.1 From ee3d3adc6fe1559a5edaa6f7f743b51a19e3f63d Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Thu, 15 Dec 2011 22:24:25 +0000 Subject: DOCS: Added SMTP information to CURLOPT_INFILESIZE --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 4d2a22e0b..58564a6f0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1850,6 +1850,9 @@ as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP. For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE\fP is mandatory. +When sending emails using SMTP, this command can be used to specify the +optional SIZE parameter for the MAIL FROM command. (Added in 7.23.0) + This option does not limit how much data libcurl will actually send, as that is controlled entirely by what the read callback returns. .IP CURLOPT_INFILESIZE_LARGE -- cgit v1.2.1 From 7799ac434e2ef14040ba01c34085998e34baf41a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 20 Dec 2011 09:48:32 +0100 Subject: tutorial: remove CURLM_CALL_MULTI_PERFORM add sharing The CURLM_CALL_MULTI_PERFORM reference is an old leftover I had to remove. I also added some blurb to the previously blank "sharing" section. --- docs/libcurl/libcurl-tutorial.3 | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index ff1a06be2..64e144089 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -1303,9 +1303,7 @@ ones at any time), you start the transfers by calling \fIcurl_multi_perform(3)\fP is asynchronous. It will only execute as little as possible and then return back control to your program. It is designed to never -block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again soon, -as that is a signal that it still has local data to send or remote data to -receive. +block. The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also @@ -1341,9 +1339,21 @@ to figure out success on each individual transfer. [ seeding, passwords, keys, certificates, ENGINE, ca certs ] .SH "Sharing Data Between Easy Handles" +You can share some data between easy handles when the easy interface is used, +and some data is share automatically when you use the multi interface. - [ fill in ] +When you add easy handles to a multi handle, these easy handles will +automatically share a lot of the data that otherwise would be kept on a +per-easy handle basis when the easy interface is used. +The DNS cache is shared between handles within a multi handle, making +subsequent name resolvings faster and the connection pool that is kept to +better allow persistent connections and connection re-use is shared. If you're +using the easy interface, you can still share these between specific easy +handles by using the share interface, see \fIlibcurl-share(3)\fP. + +Some things are never shared automatically, not within multi handles, like for +example cookies so the only way to share that is with the share interface. .SH "Footnotes" .IP "[1]" -- cgit v1.2.1 From eb6e9593c4153ca122c2eba32fde1c2319a14db7 Mon Sep 17 00:00:00 2001 From: Bernhard Reutner-Fischer Date: Tue, 20 Dec 2011 13:31:08 +0100 Subject: libcurl.m4: Fix quoting arguments of AC_LANG_PROGRAM Parameters were underquoted, resulting in warning: AC_LANG_CONFTEST: no AC_LANG_SOURCE call detected in body Signed-off-by: Bernhard Reutner-Fischer --- docs/libcurl/libcurl.m4 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl.m4 b/docs/libcurl/libcurl.m4 index 8cada0523..d7d5a5259 100644 --- a/docs/libcurl/libcurl.m4 +++ b/docs/libcurl/libcurl.m4 @@ -146,7 +146,7 @@ AC_DEFUN([LIBCURL_CHECK_CONFIG], _libcurl_save_libs=$LIBS LIBS="$LIBCURL $LIBS" - AC_LINK_IFELSE([AC_LANG_PROGRAM([#include ],[ + AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include ]],[[ /* Try and use a few common options to force a failure if we are missing symbols or can't link. */ int x; @@ -158,7 +158,7 @@ x=CURLOPT_ERRORBUFFER; x=CURLOPT_STDERR; x=CURLOPT_VERBOSE; if (x) ; -])],libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) +]])],libcurl_cv_lib_curl_usable=yes,libcurl_cv_lib_curl_usable=no) CPPFLAGS=$_libcurl_save_cppflags LIBS=$_libcurl_save_libs -- cgit v1.2.1 From c834213ad52c52431e9ca597862dc81839cabe84 Mon Sep 17 00:00:00 2001 From: Gokhan Sengun Date: Mon, 19 Dec 2011 14:35:20 +0100 Subject: FTP: perform active connections non-blocking 1- Two new error codes are introduced. CURLE_FTP_ACCEPT_FAILED to be set whenever ACCEPTing fails because of FTP server connected. CURLE_FTP_ACCEPT_TIMEOUT to be set whenever ACCEPTing timeouts. Neither of these errors are considered fatal and control connection remains OK because it could just be a firewall blocking server to connect to the client. 2- One new setopt option was introduced. CURLOPT_ACCEPTTIMEOUT_MS It sets the maximum amount of time FTP client is going to wait for a server to connect. Internal default accept timeout is 60 seconds. --- docs/libcurl/symbols-in-versions | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index ec902fd4e..73d50a2b2 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -45,6 +45,8 @@ CURLE_COULDNT_RESOLVE_PROXY 7.1 CURLE_FAILED_INIT 7.1 CURLE_FILESIZE_EXCEEDED 7.10.8 CURLE_FILE_COULDNT_READ_FILE 7.1 +CURLE_FTP_ACCEPT_FAILED 7.24.0 +CURLE_FTP_ACCEPT_TIMEOUT 7.24.0 CURLE_FTP_ACCESS_DENIED 7.1 CURLE_FTP_BAD_DOWNLOAD_RESUME 7.1 7.1 CURLE_FTP_BAD_FILE_LIST 7.21.0 @@ -286,6 +288,7 @@ CURLOPTTYPE_FUNCTIONPOINT 7.1 CURLOPTTYPE_LONG 7.1 CURLOPTTYPE_OBJECTPOINT 7.1 CURLOPTTYPE_OFF_T 7.11.0 +CURLOPT_ACCEPTTIMEOUT_MS 7.24.0 CURLOPT_ACCEPT_ENCODING 7.21.6 CURLOPT_ADDRESS_SCOPE 7.19.0 CURLOPT_APPEND 7.17.0 -- cgit v1.2.1 From b06ed249d23a8d9bc5fe8a98e04a61f581443c0d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 20 Dec 2011 20:32:31 +0100 Subject: libcurl-multi.3: active FTP is no longer blocking! --- docs/libcurl/libcurl-multi.3 | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index 44cf54313..2af029961 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/docs/libcurl/libcurl-multi.3 @@ -144,7 +144,6 @@ the future, you should be aware of the following current restrictions: .nf - Name resolves unless the c-ares or threaded-resolver backends are used - NSS SSL connections - - Active FTP connections - HTTP proxy CONNECT operations - SOCKS proxy handshakes - file:// transfers -- cgit v1.2.1 From 6222ef8052fdc369977620d38d323f2f90a77011 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 20 Dec 2011 20:32:47 +0100 Subject: libcurl-tutorial.3: curl doesn't sent pragma no-cache It did a long time ago --- docs/libcurl/libcurl-tutorial.3 | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-tutorial.3 b/docs/libcurl/libcurl-tutorial.3 index 64e144089..1cca23f33 100644 --- a/docs/libcurl/libcurl-tutorial.3 +++ b/docs/libcurl/libcurl-tutorial.3 @@ -817,10 +817,6 @@ This header is required by HTTP 1.1 and even many 1.0 servers and should be the name of the server we want to talk to. This includes the port number if anything but default. -.IP "Pragma" -\&"no-cache". Tells a possible proxy to not grab a copy from the cache but to -fetch a fresh one. - .IP "Accept" \&"*/*". -- cgit v1.2.1 From 26ce3ac328c90da7a60fdb2028625ac1e51517aa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 20 Dec 2011 23:14:18 +0100 Subject: libcurl docs: add the new FTP accept option + errors --- docs/libcurl/curl_easy_setopt.3 | 4 ++++ docs/libcurl/libcurl-errors.3 | 6 ++++++ 2 files changed, 10 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 58564a6f0..cce2e09b6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2070,6 +2070,10 @@ This option requires that libcurl was built with a resolver backend that supports this operation. The c-ares backend is the only such one. (Added in 7.24.0) +.IP CURLOPT_ACCEPTTIMOUT_MS +Pass a long telling libcurl the maximum number of milliseconds to wait for a +server to connect back to libcurl when an active FTP connection is used. If no +timeout is set, the internal default of 60000 will be used. (Added in 7.24.0) .SH SSL and SECURITY OPTIONS .IP CURLOPT_SSLCERT Pass a pointer to a zero terminated string as parameter. The string should be diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 7954a83db..20359cf2e 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -66,9 +66,15 @@ remote server is probably not an OK FTP server. .IP "CURLE_REMOTE_ACCESS_DENIED (9)" We were denied access to the resource given in the URL. For FTP, this occurs while trying to change to the remote directory. +.IP "CURLE_FTP_ACCEPT_FAILED (10)" +While waiting for the server to connect back when an active FTP session is +used, an error code was sent over the control connection or similar. .IP "CURLE_FTP_WEIRD_PASS_REPLY (11)" After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. +.IP "CURLE_FTP_ACCEPT_TIMEOUT (12)" +During an active FTP session while waiting for the server to connect, the +\fICURLOPT_ACCEPTTIMOUT_MS\fP (or the internal default) timeout expired. .IP "CURLE_FTP_WEIRD_PASV_REPLY (13)" libcurl failed to get a sensible result back from the server as a response to either a PASV or a EPSV command. The server is flawed. -- cgit v1.2.1 From 585b89a6c3640af5a1ca963eeafc7d0d82408f00 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 Jan 2012 15:59:59 +0100 Subject: curl_easy_strerror.3: minor synopsis edit of the look --- docs/libcurl/curl_easy_strerror.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_strerror.3 b/docs/libcurl/curl_easy_strerror.3 index be95f0ddc..a26c9c5db 100644 --- a/docs/libcurl/curl_easy_strerror.3 +++ b/docs/libcurl/curl_easy_strerror.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -23,9 +23,9 @@ .SH NAME curl_easy_strerror - return string describing error code .SH SYNOPSIS -.nf -.B #include -.BI "const char *curl_easy_strerror(CURLcode " errornum ");" +#include + +const char *curl_easy_strerror(CURLcode errornum); .SH DESCRIPTION The curl_easy_strerror() function returns a string describing the CURLcode error code passed in the argument \fIerrornum\fP. -- cgit v1.2.1 From 0f8239d5b44b9dc027070385e5ebf7ac1f5d5560 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Jan 2012 23:39:22 +0100 Subject: curl_easy_setopt: refer to the most recent URI RFC --- docs/libcurl/curl_easy_setopt.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index cce2e09b6..9dcce8770 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -594,8 +594,8 @@ terminated string which must be URL-encoded in the following format: scheme://host:port/path -For a greater explanation of the format please see RFC 2396 -(http://curl.haxx.se/rfc/rfc2396.txt). +For a greater explanation of the format please see RFC 3986 +(http://curl.haxx.se/rfc/rfc3986.txt). If the given URL lacks the scheme, or protocol, part ("http://" or "ftp://" etc), libcurl will attempt to resolve which protocol to use based on the -- cgit v1.2.1 From 6e2fd2c9eac2d55fbe2119c377d608dc698c5c85 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 22 Jan 2012 00:00:55 +0100 Subject: CURLOPT_ACCEPTTIMEOUT_MS: spellfix --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 9dcce8770..1a20cb9d6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2070,7 +2070,7 @@ This option requires that libcurl was built with a resolver backend that supports this operation. The c-ares backend is the only such one. (Added in 7.24.0) -.IP CURLOPT_ACCEPTTIMOUT_MS +.IP CURLOPT_ACCEPTTIMEOUT_MS Pass a long telling libcurl the maximum number of milliseconds to wait for a server to connect back to libcurl when an active FTP connection is used. If no timeout is set, the internal default of 60000 will be used. (Added in 7.24.0) -- cgit v1.2.1 From 75b6f7d9efae9f952f32e73625c1b6fab963f7ad Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Tue, 24 Jan 2012 21:31:57 -0800 Subject: curl_easy_setopt.3: Fixed SEEKDATA & CLOSESOCKETDATA descriptions --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 1a20cb9d6..d94a84b78 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -266,7 +266,7 @@ If you forward the input arguments directly to "fseek" or "lseek", note that the data type for \fIoffset\fP is not the same as defined for curl_off_t on many systems! (Option added in 7.18.0) .IP CURLOPT_SEEKDATA -Data pointer to pass to the file read function. If you use the +Data pointer to pass to the file seek function. If you use the \fICURLOPT_SEEKFUNCTION\fP option, this is the pointer you'll get as input. If you don't specify a seek callback, NULL is passed. (Option added in 7.18.0) .IP CURLOPT_SOCKOPTFUNCTION @@ -322,7 +322,7 @@ to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal success and 1 if there was an error. (Option added in 7.21.7) .IP CURLOPT_CLOSESOCKETDATA Pass a pointer that will be untouched by libcurl and passed as the first -argument in the opensocket callback set with +argument in the closesocket callback set with \fICURLOPT_CLOSESOCKETFUNCTION\fP. (Option added in 7.21.7) .IP CURLOPT_PROGRESSFUNCTION Function pointer that should match the \fIcurl_progress_callback\fP prototype -- cgit v1.2.1 From 705f0f7a5b6120bb783d139c9266b285a4c8acd8 Mon Sep 17 00:00:00 2001 From: Dave Reisner Date: Tue, 24 Jan 2012 01:28:06 +0000 Subject: add library support for tuning TCP_KEEPALIVE This adds three new options to control the behavior of TCP keepalives: - CURLOPT_TCP_KEEPALIVE: enable/disable probes - CURLOPT_TCP_KEEPIDLE: idle time before sending first probe - CURLOPT_TCP_KEEPINTVL: delay between successive probes While not all operating systems support the TCP_KEEPIDLE and TCP_KEEPINTVL knobs, the library will still allow these options to be set by clients, silently ignoring the values. --- docs/libcurl/curl_easy_setopt.3 | 18 ++++++++++++++++++ docs/libcurl/symbols-in-versions | 3 +++ 2 files changed, 21 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d94a84b78..a7688a7d0 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -915,6 +915,24 @@ overdone. .IP CURLOPT_ADDRESS_SCOPE Pass a long specifying the scope_id value to use when connecting to IPv6 link-local or site-local addresses. (Added in 7.19.0) + +.IP CURLOPT_TCP_KEEPALIVE +Pass a long. If set to 1, TCP keepalive probes will be sent. The delay and +frequency of these probes can be controlled by the \fICURLOPT_TCP_KEEPIDLE\fP +and \fICURLOPT_TCP_KEEPINTVL\fP options, provided the operating system supports +them. Set to 0 (default behavior) to disable keepalive probes (Added in +7.24.1). + +.IP CURLOPT_TCP_KEEPIDLE +Pass a long. Sets the delay, in seconds, that the operating system will wait +while the connection is idle before sending keepalive probes. Not all operating +systems support this option. (Added in 7.24.1) + +.IP CURLOPT_TCP_KEEPINTVL +Pass a long. Sets the interval, in seconds, that the operating system will wait +between sending keepalive probes. Not all operating systems support this +option. (Added in 7.24.1) + .SH NAMES and PASSWORDS OPTIONS (Authentication) .IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 73d50a2b2..a9f8a9d6e 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -486,6 +486,9 @@ CURLOPT_SSL_SESSIONID_CACHE 7.16.0 CURLOPT_SSL_VERIFYHOST 7.8.1 CURLOPT_SSL_VERIFYPEER 7.4.2 CURLOPT_STDERR 7.1 +CURLOPT_TCP_KEEPALIVE 7.24.1 +CURLOPT_TCP_KEEPIDLE 7.24.1 +CURLOPT_TCP_KEEPINTVL 7.24.1 CURLOPT_TCP_NODELAY 7.11.2 CURLOPT_TELNETOPTIONS 7.7 CURLOPT_TFTP_BLKSIZE 7.19.4 -- cgit v1.2.1 From 2a699bc6e94b8223d900e8880ad628aebf17ab6d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 6 Feb 2012 22:12:06 +0100 Subject: CURLOPT_SSL_OPTIONS: added Allow an appliction to set libcurl specific SSL options. The first and only options supported right now is CURLSSLOPT_ALLOW_BEAST. It will make libcurl to disable any work-arounds the underlying SSL library may have to address a known security flaw in the SSL3 and TLS1.0 protocol versions. This is a reaction to us unconditionally removing that behavior after this security advisory: http://curl.haxx.se/docs/adv_20120124B.html ... it did however cause a lot of programs to fail because of old servers not liking this work-around. Now programs can opt to decrease the security in order to interoperate with old servers better. --- docs/libcurl/curl_easy_setopt.3 | 10 ++++++++++ docs/libcurl/symbols-in-versions | 2 ++ 2 files changed, 12 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a7688a7d0..571fe742a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2313,6 +2313,16 @@ this to 1 to enable it. By default all transfers are done using the cache. While nothing ever should get hurt by attempting to reuse SSL session-IDs, there seem to be broken SSL implementations in the wild that may require you to disable this in order for you to succeed. (Added in 7.16.0) +.IP CURLOPT_SSL_OPTIONS +Pass a long with a bitmask to tell libcurl about specific SSL behaviors. + +CURLSSLOPT_ALLOW_BEAST is the only supported bit and by setting this the user +will tell libcurl to not attempt to use any work-arounds for a security flaw +in the SSL3 and TLS1.0 protocols. If this option isn't used or this bit is +set to 0, the SSL layer libcurl uses may use a work-around for this flaw +although it might cause interoperability problems with some (older) SSL +implementations. WARNING: avoiding this work-around loosens the security, and +by setting this option to 1 you ask for exactly that. (Added in 7.25.0) .IP CURLOPT_KRBLEVEL Pass a char * as parameter. Set the kerberos security level for FTP; this also enables kerberos awareness. This is a string, \&'clear', \&'safe', diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index a9f8a9d6e..010ebc6fe 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -482,6 +482,7 @@ CURLOPT_SSLVERSION 7.1 CURLOPT_SSL_CIPHER_LIST 7.9 CURLOPT_SSL_CTX_DATA 7.10.6 CURLOPT_SSL_CTX_FUNCTION 7.10.6 +CURLOPT_SSL_OPTIONS 7.25.0 CURLOPT_SSL_SESSIONID_CACHE 7.16.0 CURLOPT_SSL_VERIFYHOST 7.8.1 CURLOPT_SSL_VERIFYPEER 7.4.2 @@ -573,6 +574,7 @@ CURLSSH_AUTH_KEYBOARD 7.16.1 CURLSSH_AUTH_NONE 7.16.1 CURLSSH_AUTH_PASSWORD 7.16.1 CURLSSH_AUTH_PUBLICKEY 7.16.1 +CURLSSLOPT_ALLOW_BEAST 7.25.0 CURLUSESSL_ALL 7.17.0 CURLUSESSL_CONTROL 7.17.0 CURLUSESSL_NONE 7.17.0 -- cgit v1.2.1 From ea4ceca2222aa5c49198d42678437a4f5ded6f3f Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 13 Feb 2012 23:57:18 +0100 Subject: s/7.24.1/7.25.0 We will go straight to 7.25.0 due to the new additions --- docs/libcurl/curl_easy_setopt.3 | 10 +++------- docs/libcurl/symbols-in-versions | 6 +++--- 2 files changed, 6 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 571fe742a..a68b65855 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -915,24 +915,20 @@ overdone. .IP CURLOPT_ADDRESS_SCOPE Pass a long specifying the scope_id value to use when connecting to IPv6 link-local or site-local addresses. (Added in 7.19.0) - .IP CURLOPT_TCP_KEEPALIVE Pass a long. If set to 1, TCP keepalive probes will be sent. The delay and frequency of these probes can be controlled by the \fICURLOPT_TCP_KEEPIDLE\fP and \fICURLOPT_TCP_KEEPINTVL\fP options, provided the operating system supports them. Set to 0 (default behavior) to disable keepalive probes (Added in -7.24.1). - +7.25.0). .IP CURLOPT_TCP_KEEPIDLE Pass a long. Sets the delay, in seconds, that the operating system will wait while the connection is idle before sending keepalive probes. Not all operating -systems support this option. (Added in 7.24.1) - +systems support this option. (Added in 7.25.0) .IP CURLOPT_TCP_KEEPINTVL Pass a long. Sets the interval, in seconds, that the operating system will wait between sending keepalive probes. Not all operating systems support this -option. (Added in 7.24.1) - +option. (Added in 7.25.0) .SH NAMES and PASSWORDS OPTIONS (Authentication) .IP CURLOPT_NETRC This parameter controls the preference of libcurl between using user names and diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 010ebc6fe..b71ad5998 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -487,9 +487,9 @@ CURLOPT_SSL_SESSIONID_CACHE 7.16.0 CURLOPT_SSL_VERIFYHOST 7.8.1 CURLOPT_SSL_VERIFYPEER 7.4.2 CURLOPT_STDERR 7.1 -CURLOPT_TCP_KEEPALIVE 7.24.1 -CURLOPT_TCP_KEEPIDLE 7.24.1 -CURLOPT_TCP_KEEPINTVL 7.24.1 +CURLOPT_TCP_KEEPALIVE 7.25.0 +CURLOPT_TCP_KEEPIDLE 7.25.0 +CURLOPT_TCP_KEEPINTVL 7.25.0 CURLOPT_TCP_NODELAY 7.11.2 CURLOPT_TELNETOPTIONS 7.7 CURLOPT_TFTP_BLKSIZE 7.19.4 -- cgit v1.2.1 From 154c0d4b9344a53852e0706031be6b4751123f54 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sat, 7 Jan 2012 14:10:40 +0000 Subject: DOCS: Added information for CURLOPT_MAIL_AUTH. Added information relating to the new CURLOPT_MAIL_AUTH parameter and reworked CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT to be a clearer. Fixed inconsistencies of "vocalisation of the abbreviation" versus "vocalisation of the first word" for all abbreviations. Corrected a typo in CURLOPT_NOPROXY. --- docs/libcurl/curl_easy_setopt.3 | 77 ++++++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 27 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a68b65855..895d85bcd 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -419,7 +419,7 @@ built against another SSL library, this functionality is absent. Function pointer that should match the following prototype: \fBCURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called -by libcurl just before the initialization of an SSL connection after having +by libcurl just before the initialization of a SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behaviour of openssl's ssl initialization. The \fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If @@ -434,7 +434,7 @@ the SSL negotiation. The SSL_CTX pointer will be a new one every time. To use this properly, a non-trivial amount of knowledge of the openssl libraries is necessary. For example, using this function allows you to use openssl callbacks to add additional validation code for certificates, and even -to change the actual URI of an HTTPS request (example used in the lib509 test +to change the actual URI of a HTTPS request (example used in the lib509 test case). See also the example section for a replacement of the key, certificate and trust file settings. .IP CURLOPT_SSL_CTX_DATA @@ -711,7 +711,7 @@ pop3://user:password@mail.domain.com/1 - This retrieves the first message .B SCP -The path part of an SCP request specifies the file to retrieve and from what +The path part of a SCP request specifies the file to retrieve and from what directory. The file part may not be omitted. The file is taken as an absolute path from the root directory on the server. To specify a path relative to the user's home directory on the server, prepend ~/ to the path portion. @@ -725,7 +725,7 @@ user's home directory on the server .B SFTP -The path part of an SFTP request specifies the file to retrieve and from what +The path part of a SFTP request specifies the file to retrieve and from what directory. If the file part is omitted then libcurl downloads the directory listing for the directory specified. If the path ends in a / then a directory listing is returned instead of a file. If the path is omitted entirely then @@ -778,7 +778,7 @@ proxy's port number may optionally be specified with the separate option. If not specified, libcurl will default to using port 1080 for proxies. \fICURLOPT_PROXYPORT\fP. -When you tell the library to use an HTTP proxy, libcurl will transparently +When you tell the library to use a HTTP proxy, libcurl will transparently convert operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as \fICURLOPT_QUOTE\fP and similar FTP specifics that don't work unless you @@ -817,7 +817,7 @@ affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version used for "regular" HTTP requests is instead controlled with \fICURLOPT_HTTP_VERSION\fP. .IP CURLOPT_NOPROXY -Pass a pointer to a zero terminated string. The should be a comma separated +Pass a pointer to a zero terminated string. This should be a comma separated list of hosts which do not use a proxy, if one is specified. The only wildcard is a single * character, which matches all hosts, and effectively disables the proxy. Each name in this list is matched as either a domain which @@ -1129,7 +1129,7 @@ Pass a parameter set to 1 to enable this. When enabled, libcurl will automatically set the Referer: field in requests where it follows a Location: redirect. .IP CURLOPT_ACCEPT_ENCODING -Sets the contents of the Accept-Encoding: header sent in an HTTP request, and +Sets the contents of the Accept-Encoding: header sent in a HTTP request, and enables decoding of a response when a Content-Encoding: header is received. Three encodings are supported: \fIidentity\fP, which does nothing, \fIdeflate\fP which requests the server to compress its response using the @@ -1157,7 +1157,7 @@ by both HTTP clients and HTTP servers. (Added in 7.21.6) .IP CURLOPT_FOLLOWLOCATION A parameter set to 1 tells the library to follow any Location: header that the -server sends as part of an HTTP header. +server sends as part of a HTTP header. This means that the library will re-send the same request on the new location and follow new Location: headers all the way until no more such headers are @@ -1237,7 +1237,7 @@ If you issue a POST request and then want to make a HEAD or GET using the same re-used handle, you must explicitly set the new request type using \fICURLOPT_NOBODY\fP or \fICURLOPT_HTTPGET\fP or similar. .IP CURLOPT_POSTFIELDS -Pass a void * as parameter, which should be the full data to post in an HTTP +Pass a void * as parameter, which should be the full data to post in a HTTP POST operation. You must make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded. @@ -1272,7 +1272,7 @@ Pass a curl_off_t as parameter. Use this to set the size of the data to figure out the size. This is the large file version of the \fICURLOPT_POSTFIELDSIZE\fP option. (Added in 7.11.1) .IP CURLOPT_COPYPOSTFIELDS -Pass a char * as parameter, which should be the full data to post in an HTTP +Pass a char * as parameter, which should be the full data to post in a HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS\fP option, but the original data are copied by the library, allowing the application to overwrite the original data after setting this option. @@ -1444,25 +1444,48 @@ transfer decoding will be disabled, if set to 1 it is enabled option is set to zero. (added in 7.16.2) .SH SMTP OPTIONS .IP CURLOPT_MAIL_FROM -Pass a pointer to a zero terminated string as parameter. It will be used to -specify the sender address in a mail when sending an SMTP mail with libcurl. +Pass a pointer to a zero terminated string as parameter. This should be used +to specify the sender's email address when sending SMTP mail with libcurl. + +An originator email address should be specified with angled brackets (<>) +around it, which if not specified, will be added by libcurl from version +7.21.4 onwards. Failing to provide such brackets may cause the server to +reject the email. -An originator email address in SMTP lingo is specified within angle brackets -(<>) which libcurl will not add for you before version 7.21.4. Failing to -provide such brackets may cause the server to reject your mail. +If this parameter is not specified then an empty address will be sent to the +mail server which may or may not cause the email to be rejected. (Added in 7.20.0) .IP CURLOPT_MAIL_RCPT Pass a pointer to a linked list of recipients to pass to the server in your -SMTP mail request. The linked list should be a fully valid list of \fBstruct +SMTP mail request. The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. -Each recipient in SMTP lingo is specified with angle brackets (<>), but should -you not use an angle bracket as first letter libcurl will assume you provide a -single email address only and enclose that with angle brackets for you. +Each recipient should be specified within a pair of angled brackets (<>), +however, should you not use an angled bracket as the first character libcurl +will assume you provided a single email address and enclose that address +within brackets for you. (Added in 7.20.0) +.IP CURLOPT_MAIL_AUTH +Pass a pointer to a zero terminated string as parameter. This will be used +to specify the authentication address (identity) of a submitted message that +is being relayed to another server. + +This optional parameter allows co-operating agents in a trusted environment to +communicate the authentication of individual messages and should only be used +by the application program, using libcurl, if the application is itself a +mail server acting in such an environment. If the application is operating as +such and the AUTH address is not known or is invalid, then an empty string +should be used for this parameter. + +Unlike CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT, the address should not be +specified within a pair of angled brackets (<>). However, if an empty string +is used then a pair of brackets will be sent by libcurl as required by +RFC-2554. + +(Added in 7.24.0) .SH TFTP OPTIONS .IP CURLOPT_TFTP_BLKSIZE Specify block size to use for TFTP data transmission. Valid range as per RFC @@ -1684,7 +1707,7 @@ needed for this method)\fP (Added in 7.20.0) When sent by a client, this method changes the description of the session. For example, if a client is using the server to record a meeting, the client can use Announce to inform the server of all the meta-information about the -session. ANNOUNCE acts like an HTTP PUT or POST just like +session. ANNOUNCE acts like a HTTP PUT or POST just like \fICURL_RTSPREQ_SET_PARAMETER\fP (Added in 7.20.0) .IP CURL_RTSPREQ_SETUP Setup is used to initialize the transport layer for the session. The @@ -1707,7 +1730,7 @@ different connections. (Added in 7.20.0) .IP CURL_RTSPREQ_GET_PARAMETER Retrieve a parameter from the server. By default, libcurl will automatically include a \fIContent-Type: text/parameters\fP header on all non-empty requests -unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST +unless a custom one is set. GET_PARAMETER acts just like a HTTP PUT or POST (see \fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat message (e.g. in the presence of a server-specified timeout) should send use an empty GET_PARAMETER request. @@ -1715,9 +1738,9 @@ server-specified timeout) should send use an empty GET_PARAMETER request. .IP CURL_RTSPREQ_SET_PARAMETER Set a parameter on the server. By default, libcurl will automatically include a \fIContent-Type: text/parameters\fP header unless a custom one is set. The -interaction with SET_PARAMTER is much like an HTTP PUT or POST. An application -may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like an HTTP -PUT, or it may use \fICURLOPT_POSTFIELDS\fP like an HTTP POST. No chunked +interaction with SET_PARAMTER is much like a HTTP PUT or POST. An application +may either use \fICURLOPT_UPLOAD\fP with \fICURLOPT_READDATA\fP like a HTTP +PUT, or it may use \fICURLOPT_POSTFIELDS\fP like a HTTP POST. No chunked transfers are allowed, so the application must set the \fICURLOPT_INFILESIZE\fP in the former and \fICURLOPT_POSTFIELDSIZE\fP in the latter. Also, there is no use of multi-part POSTs within RTSP. (Added in @@ -1779,7 +1802,7 @@ over FTP. This is a known limitation/flaw that nobody has rectified. libcurl simply sets the mode to ASCII and performs a standard transfer. .IP CURLOPT_PROXY_TRANSFER_MODE Pass a long. If the value is set to 1 (one), it tells libcurl to set the -transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by +transfer mode (binary or ASCII) for FTP transfers done via a HTTP proxy, by appending ;type=a or ;type=i to the URL. Without this setting, or it being set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT\fP has no effect when doing FTP via a proxy. Beware that not all proxies support this feature. (Added in @@ -1817,7 +1840,7 @@ Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST Pass a pointer to a zero terminated string as parameter. It will be used -instead of GET or HEAD when doing an HTTP request, or instead of LIST or NLST +instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST when doing a FTP directory listing. This is useful for doing DELETE or other more or less obscure HTTP requests. Don't do this at will, make sure your server supports the command first. @@ -2160,7 +2183,7 @@ Pass a long as parameter. By default, curl assumes a value of 1. This option determines whether curl verifies the authenticity of the peer's certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't. -When negotiating an SSL connection, the server sends a certificate indicating +When negotiating a SSL connection, the server sends a certificate indicating its identity. Curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority -- cgit v1.2.1 From 674699b2126ce3a07bbb0a6f1488b934f7f1e5c6 Mon Sep 17 00:00:00 2001 From: Kamil Dudka Date: Thu, 16 Feb 2012 12:20:57 +0100 Subject: docs: mention that NTLM works with NSS, too --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 895d85bcd..7068c5c42 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1061,8 +1061,8 @@ HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being eavesdropped. -You need to build libcurl with OpenSSL support for this option to work, or -build libcurl on Windows. +You need to build libcurl with either OpenSSL or NSS support for this option +to work, or build libcurl on Windows. .IP CURLAUTH_NTLM_WB NTLM delegating to winbind helper. Authentication is performed by a separate binary application that is executed when needed. The name of the application -- cgit v1.2.1 From 4cf742f34f77e4cc3b5418371357bb38a1e03cce Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 17 Feb 2012 14:40:07 +0100 Subject: CURLE_FTP_PRET_FAILED: listed twice Make sure it is mentioned once and with the correct description --- docs/libcurl/libcurl-errors.3 | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 20359cf2e..8ad1facc6 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -81,11 +81,6 @@ either a PASV or a EPSV command. The server is flawed. .IP "CURLE_FTP_WEIRD_227_FORMAT (14)" FTP servers return a 227-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back. -.IP "CURLE_FTP_PRET_FAILED (84)" -The FTP server does not understand the PRET command at all or does not support -the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST\fP, a -custom LIST command will be sent with PRET CMD before PASV as well. (Added in -7.20.0) .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)" @@ -233,7 +228,10 @@ 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_FTP_PRET_FAILED (84)" -PRET command failed +The FTP server does not understand the PRET command at all or does not support +the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST\fP, a +custom LIST command will be sent with PRET CMD before PASV as well. (Added in +7.20.0) .IP "CURLE_RTSP_CSEQ_ERROR (85)" Mismatch of RTSP CSeq numbers. .IP "CURLE_RTSP_SESSION_ERROR (86)" -- cgit v1.2.1 From 30c44edad3bb31341aa2992948e377848125f8b1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 21 Feb 2012 22:29:31 +0100 Subject: CURLOPT_MAIL_AUTH: added in 7.25.0 Brought in commit 0cf0ab6f300 --- docs/libcurl/symbols-in-versions | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index b71ad5998..03060ae5b 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -384,6 +384,7 @@ CURLOPT_LOCALPORT 7.15.2 CURLOPT_LOCALPORTRANGE 7.15.2 CURLOPT_LOW_SPEED_LIMIT 7.1 CURLOPT_LOW_SPEED_TIME 7.1 +CURLOPT_MAIL_AUTH 7.25.0 CURLOPT_MAIL_FROM 7.20.0 CURLOPT_MAIL_RCPT 7.20.0 CURLOPT_MAXCONNECTS 7.7 -- cgit v1.2.1 From 5430007222e0325a1c5e0359ecde43886cef61af Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Wed, 22 Feb 2012 10:44:34 +0000 Subject: SMTP: Added support for returning SMTP response codes Set the conn->data->info.httpcode variable in smtp_statemach_act() to allow Curl_getinfo() to return the SMTP response code via the CURLINFO_RESPONSE_CODE action. --- docs/libcurl/curl_easy_getinfo.3 | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index eb4e900dd..096813609 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -44,11 +44,13 @@ The following information can be extracted: .IP CURLINFO_EFFECTIVE_URL Pass a pointer to a char pointer to receive the last used effective URL. .IP CURLINFO_RESPONSE_CODE -Pass a pointer to a long to receive the last received HTTP or FTP code. This -option was known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. This -will be zero if no server response code has been received. Note that a proxy's -CONNECT response should be read with \fICURLINFO_HTTP_CONNECTCODE\fP and not -this. +Pass a pointer to a long to receive the last received HTTP, FTP or SMTP +response code. This option was previously known as CURLINFO_HTTP_CODE in +libcurl 7.10.7 and earlier. The value will be zero if no server response code +has been received. Note that a proxy's CONNECT response should be read with +\fICURLINFO_HTTP_CONNECTCODE\fP and not this. + +Support for SMTP responses added in 7.25.0. .IP CURLINFO_HTTP_CONNECTCODE Pass a pointer to a long to receive the last received proxy response code to a CONNECT request. -- cgit v1.2.1 From d185960a6d56a5298ba9a7ca97683d256f92317c Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 25 Feb 2012 19:34:08 +0100 Subject: libcurl docs: version corrections Correct some inconsistencies in which version some things were added. Bug: http://curl.haxx.se/bug/view.cgi?id=3494091 Reported by: "curlybugs" --- docs/libcurl/curl_easy_setopt.3 | 8 ++++---- docs/libcurl/symbols-in-versions | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7068c5c42..af5470c1c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -281,7 +281,7 @@ socket descriptor so additional setsockopt() calls can be done at the user's discretion. Return 0 (zero) from the callback on success. Return 1 from the callback function to signal an unrecoverable error to the library and it will close the socket and return \fICURLE_COULDNT_CONNECT\fP. (Option added in -7.15.6.) +7.16.0) Added in 7.21.5, the callback function may return \fICURL_SOCKOPT_ALREADY_CONNECTED\fP, which tells libcurl that the socket is @@ -289,7 +289,7 @@ in fact already connected and then libcurl will not attempt to connect it. .IP CURLOPT_SOCKOPTDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. -(Option added in 7.15.6.) +(Option added in 7.16.0) .IP CURLOPT_OPENSOCKETFUNCTION Function pointer that should match the \fIcurl_opensocket_callback\fP prototype found in \fI\fP. This function gets called by libcurl @@ -808,7 +808,7 @@ specified in the proxy string \fICURLOPT_PROXY\fP. .IP CURLOPT_PROXYTYPE Pass a long with this option to set type of the proxy. Available options for this are \fICURLPROXY_HTTP\fP, \fICURLPROXY_HTTP_1_0\fP (added in 7.19.4), -\fICURLPROXY_SOCKS4\fP (added in 7.15.2), \fICURLPROXY_SOCKS5\fP, +\fICURLPROXY_SOCKS4\fP (added in 7.10), \fICURLPROXY_SOCKS5\fP, \fICURLPROXY_SOCKS4A\fP (added in 7.18.0) and \fICURLPROXY_SOCKS5_HOSTNAME\fP (added in 7.18.0). The HTTP type is default. (Added in 7.10) @@ -1552,7 +1552,7 @@ Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. 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. Before version 7.15.6, if you also set \fICURLOPT_NOBODY\fP to 1, this +option. Before version 7.16.0, if you also set \fICURLOPT_NOBODY\fP to 1, this option didn't work. .IP CURLOPT_DIRLISTONLY A parameter set to 1 tells the library to just list the names of files in a diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 03060ae5b..62d8a242b 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -408,7 +408,7 @@ CURLOPT_OPENSOCKETFUNCTION 7.17.1 CURLOPT_PASSWDDATA 7.4.2 7.11.1 7.15.5 CURLOPT_PASSWDFUNCTION 7.4.2 7.11.1 7.15.5 CURLOPT_PASSWORD 7.19.1 -CURLOPT_PASV_HOST 7.12.1 7.15.6 7.15.5 +CURLOPT_PASV_HOST 7.12.1 7.16.0 7.15.5 CURLOPT_PORT 7.1 CURLOPT_POST 7.1 CURLOPT_POST301 7.17.1 7.19.1 @@ -567,7 +567,7 @@ CURLSHOPT_SHARE 7.10.3 CURLSHOPT_UNLOCKFUNC 7.10.3 CURLSHOPT_UNSHARE 7.10.3 CURLSHOPT_USERDATA 7.10.3 -CURLSOCKTYPE_IPCXN 7.15.6 +CURLSOCKTYPE_IPCXN 7.16.0 CURLSSH_AUTH_ANY 7.16.1 CURLSSH_AUTH_DEFAULT 7.16.1 CURLSSH_AUTH_HOST 7.16.1 -- cgit v1.2.1 From b50e9e9e9e39538b53cf56829f872f3034fc8060 Mon Sep 17 00:00:00 2001 From: Armel Asselin Date: Sat, 10 Mar 2012 16:15:23 +0100 Subject: CURLSSH_OPT_AUTH: documented it has no effect --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index af5470c1c..6514068a4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2362,8 +2362,8 @@ GSS_C_DELEG_POLICY_FLAG was available at compile-time. .IP CURLOPT_SSH_AUTH_TYPES Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, -CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. -(Added in 7.16.1) +CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. Currently +CURLSSH_AUTH_HOST has no effect. (Added in 7.16.1) .IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 Pass a char * pointing to a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host's public key, and -- cgit v1.2.1 From a9086e8a4b07f467ca12434fbe5f1e7e4348ba9a Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sat, 31 Mar 2012 18:47:58 +0100 Subject: DOCS: Added information regarding POP3 commands to CURLOPT_CUSTOMREQUEST --- docs/libcurl/curl_easy_setopt.3 | 38 ++++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 16 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 6514068a4..76b4281ca 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1839,16 +1839,20 @@ source file to the remote target file. Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. (Added in 7.11.0) .IP CURLOPT_CUSTOMREQUEST -Pass a pointer to a zero terminated string as parameter. It will be used -instead of GET or HEAD when doing a HTTP request, or instead of LIST or NLST -when doing a FTP directory listing. This is useful for doing DELETE or other -more or less obscure HTTP requests. Don't do this at will, make sure your -server supports the command first. - +Pass a pointer to a zero terminated string as parameter. It can be used to +specify the request instead of GET or HEAD when performing HTTP based +requests, instead of LIST and NLST when performing FTP directory listings and +instead of LIST and RETR when issuing POP3 based commands. This is +particularly useful, for example, for performing a HTTP DELETE request or a +POP3 DELE command. + +Please don't perform this at will, on HTTP based requests, by making sure +your server supports the command you are sending first. + When you change the request method by setting \fBCURLOPT_CUSTOMREQUEST\fP to -something, you don't actually change how libcurl behaves or acts in regards to -the particular request method, it will only change the actual string sent in -the request. +something, you don't actually change how libcurl behaves or acts in regards +to the particular request method, it will only change the actual string sent +in the request. For example: if you tell libcurl to do a HEAD request, but then change the request to a "GET" with \fBCURLOPT_CUSTOMREQUEST\fP you'll still see libcurl @@ -1860,12 +1864,14 @@ POST, use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and so on. Restore to the internal default by setting this to NULL. Many people have wrongly used this option to replace the entire request with -their own, including multiple headers and POST contents. While that might work -in many cases, it will cause libcurl to send invalid requests and it could -possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and +their own, including multiple headers and POST contents. While that might +work in many cases, it will cause libcurl to send invalid requests and it +could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and \fICURLOPT_POSTFIELDS\fP to set POST data. Use \fICURLOPT_HTTPHEADER\fP to replace or extend the set of headers sent by libcurl. Use \fICURLOPT_HTTP_VERSION\fP to change HTTP version. + +(Support for POP3 added in 7.25.1) .IP CURLOPT_FILETIME Pass a long. If it is 1, libcurl will attempt to get the modification date of the remote document in this operation. This requires that the remote server @@ -1874,11 +1880,11 @@ sends the time or replies to a time querying command. The can be used after a transfer to extract the received time (if any). .IP CURLOPT_NOBODY A parameter set to 1 tells the library to not include the body-part in the -output. This is only relevant for protocols that have separate header and body -parts. On HTTP(S) servers, this will make libcurl do a HEAD request. +output. This is only relevant for protocols that have separate header and +body parts. On HTTP(S) servers, this will make libcurl do a HEAD request. -To change request to GET, you should use \fICURLOPT_HTTPGET\fP. Change request -to POST with \fICURLOPT_POST\fP etc. +To change request to GET, you should use \fICURLOPT_HTTPGET\fP. Change +request to POST with \fICURLOPT_POST\fP etc. .IP CURLOPT_INFILESIZE When uploading a file to a remote site, this option should be used to tell libcurl what the expected size of the infile is. This value should be passed -- cgit v1.2.1 From 05a443adf2d607a53a943d6f1df33cd765061c4e Mon Sep 17 00:00:00 2001 From: Armel Asselin Date: Sun, 1 Apr 2012 20:22:37 +0200 Subject: SSH: public key can now be an empty string If an empty string is passed to CURLOPT_SSH_PUBLIC_KEYFILE, libcurl will pass no public key to libssh2 which then tries to compute it from the private key. This is known to work when libssh2 1.4.0+ is linked against OpenSSL. --- docs/libcurl/curl_easy_setopt.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 76b4281ca..d0e054b62 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2380,6 +2380,9 @@ Pass a char * pointing to a file name for your public key. If not used, libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment variable is set, and just "id_dsa.pub" in the current directory if HOME is not set. (Added in 7.16.1) +If an empty string is passed, libcurl will pass no public key to libssh2 +which then tries to compute it from the private key, this is known to work +when libssh2 1.4.0+ is linked against OpenSSL. (Added in 7.25.1) .IP CURLOPT_SSH_PRIVATE_KEYFILE Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to \fB$HOME/.ssh/id_dsa\fP if the HOME environment variable -- cgit v1.2.1 From 0b516b7162dc387ed80b0f24476b950ab2e18cb7 Mon Sep 17 00:00:00 2001 From: Andrei Cipu Date: Fri, 30 Mar 2012 10:40:04 +0300 Subject: CURLOPT_POSTREDIR: also allow 303 to do POST on the redirected URL As it turns out, some people do want that after all. --- docs/libcurl/curl_easy_setopt.3 | 7 ++++--- docs/libcurl/symbols-in-versions | 1 + 2 files changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index d0e054b62..a90ee65e6 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1180,12 +1180,13 @@ Setting the limit to 0 will make libcurl refuse any redirect. Set it to -1 for an infinite number of redirects (which is the default) .IP CURLOPT_POSTREDIR Pass a bitmask to control how libcurl acts on redirects after POSTs that get a -301 or 302 response back. A parameter with bit 0 set (value +301, 302 or 303 response back. A parameter with bit 0 set (value \fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 2616/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain -the request method after a 302 redirect. CURL_REDIR_POST_ALL is a convenience -define that sets both bits. +the request method after a 302 redirect. Setting bit 2 (value +\fBCURL_REDIR_POST_303) makes libcurl maintain the request method after a 302 +redirect. CURL_REDIR_POST_ALL is a convenience define that sets both bits. The non-RFC behaviour is ubiquitous in web browsers, so the library does the conversion by default to maintain consistency. However, a server may require a diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 62d8a242b..41705fd29 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -649,6 +649,7 @@ CURL_READFUNC_PAUSE 7.18.0 CURL_REDIR_GET_ALL 7.19.1 CURL_REDIR_POST_301 7.19.1 CURL_REDIR_POST_302 7.19.1 +CURL_REDIR_POST_303 7.25.1 CURL_REDIR_POST_ALL 7.19.1 CURL_RTSPREQ_ANNOUNCE 7.20.0 CURL_RTSPREQ_DESCRIBE 7.20.0 -- cgit v1.2.1 From 77bac2658736d1c323c38986c7741bc8ae68ca5b Mon Sep 17 00:00:00 2001 From: Claes Jakobsson Date: Thu, 3 May 2012 13:49:55 +0200 Subject: Add note about default timeout in CURLOPT_TIMEOUT --- docs/libcurl/curl_easy_setopt.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a90ee65e6..7d422e82a 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1965,6 +1965,8 @@ SIGALRM to enable time-outing system calls. In unix-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL\fP is set. + +Default timeout is 0 (zero) which means it never times out. .IP CURLOPT_TIMEOUT_MS Like \fICURLOPT_TIMEOUT\fP but takes number of milliseconds instead. If libcurl is built to use the standard system name resolver, that portion -- cgit v1.2.1 From 3ebcfdda36afeec0119c7f4f3fd8a37c5f9b37eb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 7 May 2012 00:13:46 +0200 Subject: CURLOPT_HEADERFUNCTION: works for non-HTTP protocols too --- docs/libcurl/curl_easy_setopt.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7d422e82a..830c1dd09 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -357,7 +357,7 @@ of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the transfer and return \fICURL_WRITE_ERROR\fP. -A complete header that is passed to this function can be up to +A complete HTTP header that is passed to this function can be up to \fICURL_MAX_HTTP_HEADER\fP (100K) bytes. If this option is not set, or if it is set to NULL, but @@ -380,6 +380,9 @@ to detect it being a trailer and not an ordinary header: 1) it comes after the response-body. 2) it comes after the final header line (CR LF) 3) a Trailer: header among the regular response-headers mention what header(s) to expect in the trailer. + +For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get +called with the server responses to the commands that libcurl sends. .IP CURLOPT_WRITEHEADER (This option is also known as \fBCURLOPT_HEADERDATA\fP) Pass a pointer to be used to write the header part of the received data to. If you don't use -- cgit v1.2.1 From 92f841aef772d90b96cfc804636ee0ab1eb039f8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 12 May 2012 23:15:51 +0200 Subject: NTLM: is supported in GnuTLS builds too ... since commit 9a4c887c4a7 introduced in libcurl 7.19.4 --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 830c1dd09..3edee8614 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1064,8 +1064,8 @@ HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge-response and hash concept similar to Digest, to prevent the password from being eavesdropped. -You need to build libcurl with either OpenSSL or NSS support for this option -to work, or build libcurl on Windows. +You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this +option to work, or build libcurl on Windows. .IP CURLAUTH_NTLM_WB NTLM delegating to winbind helper. Authentication is performed by a separate binary application that is executed when needed. The name of the application -- cgit v1.2.1 From b1f081f6e65576a9f824182ca47873a75e1f9e0d Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Tue, 22 May 2012 20:20:59 +0100 Subject: DOCS: Updated version number for features added in the pending release --- docs/libcurl/curl_easy_setopt.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3edee8614..bfe583472 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1875,7 +1875,7 @@ could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and replace or extend the set of headers sent by libcurl. Use \fICURLOPT_HTTP_VERSION\fP to change HTTP version. -(Support for POP3 added in 7.25.1) +(Support for POP3 added in 7.26.0) .IP CURLOPT_FILETIME Pass a long. If it is 1, libcurl will attempt to get the modification date of the remote document in this operation. This requires that the remote server @@ -2388,7 +2388,7 @@ variable is set, and just "id_dsa.pub" in the current directory if HOME is not set. (Added in 7.16.1) If an empty string is passed, libcurl will pass no public key to libssh2 which then tries to compute it from the private key, this is known to work -when libssh2 1.4.0+ is linked against OpenSSL. (Added in 7.25.1) +when libssh2 1.4.0+ is linked against OpenSSL. (Added in 7.26.0) .IP CURLOPT_SSH_PRIVATE_KEYFILE Pass a char * pointing to a file name for your private key. If not used, libcurl defaults to \fB$HOME/.ssh/id_dsa\fP if the HOME environment variable -- cgit v1.2.1 From 4f3ec68dc77ffbdaef0283f12243c6ebf7127264 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Thu, 24 May 2012 21:17:00 +0100 Subject: DOCS: Added LDAP to the CURLOPT_URL section --- docs/libcurl/curl_easy_setopt.3 | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index bfe583472..5aa0f5687 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -745,6 +745,26 @@ user's home directory sftp://ssh.example.com/~/Documents/ - This requests a directory listing of the Documents directory under the user's home directory +.B LDAP + +The path part of a LDAP request can be used to specify the: Distinguished +Name, Attributes, Scope, Filter and Extension for an LDAP search. Each field +is separated by a question mark and when that field is not required an empty +string with the question mark separator should be included. + +ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search +with the DN as My Organisation. + +ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform +the same search but will only return postalAddress attributes. + +ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN +and requests information about the rootDomainNamingContext attribute for an +Active Directory server. + +For more information about the individual components of an LDAP URL please +see RFC-4516. + .B NOTES Starting with version 7.20.0, the fragment part of the URI will not be sent as -- cgit v1.2.1 From cb9e2e8466534f35ed8188e43b978c74ee3df76c Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sat, 26 May 2012 12:26:35 +0100 Subject: DOCS: Standardised how RFCs are referenced. Standardised how RFCs are referenced so that the website may autolink to the correct documentation on ietf.org. Additionally removed the one link to RFC3986 on curl.haxx.se. --- docs/libcurl/curl_easy_setopt.3 | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5aa0f5687..70d7cd5b4 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -498,7 +498,7 @@ exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the interleaved header as well as the included data for each call. The first byte is always an ASCII dollar sign. The dollar sign is followed by a one byte channel identifier and then a 2 byte integer length in network byte order. See -\fIRFC 2326 Section 10.12\fP for more information on how RTP interleaving +\fIRFC2326 Section 10.12\fP for more information on how RTP interleaving behaves. If unset or set to NULL, curl will use the default write function. Interleaved RTP poses some challeneges for the client application. Since the @@ -597,8 +597,7 @@ terminated string which must be URL-encoded in the following format: scheme://host:port/path -For a greater explanation of the format please see RFC 3986 -(http://curl.haxx.se/rfc/rfc3986.txt). +For a greater explanation of the format please see RFC3986. If the given URL lacks the scheme, or protocol, part ("http://" or "ftp://" etc), libcurl will attempt to resolve which protocol to use based on the @@ -748,7 +747,7 @@ of the Documents directory under the user's home directory .B LDAP The path part of a LDAP request can be used to specify the: Distinguished -Name, Attributes, Scope, Filter and Extension for an LDAP search. Each field +Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field is separated by a question mark and when that field is not required an empty string with the question mark separator should be included. @@ -762,8 +761,8 @@ ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN and requests information about the rootDomainNamingContext attribute for an Active Directory server. -For more information about the individual components of an LDAP URL please -see RFC-4516. +For more information about the individual components of a LDAP URL please +see RFC4516. .B NOTES @@ -858,7 +857,7 @@ default service name for a SOCKS5 server is rcmd/server-fqdn. This option allows you to change it. (Added in 7.19.4) .IP CURLOPT_SOCKS5_GSSAPI_NEC Pass a long set to 1 to enable or 0 to disable. As part of the gssapi -negotiation a protection mode is negotiated. The rfc1961 says in section +negotiation a protection mode is negotiated. The RFC1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. If enabled, this option allows the unprotected exchange of the protection mode negotiation. (Added in 7.19.4). @@ -1119,7 +1118,7 @@ authentication method(s) you want it to use for TLS authentication. .RS .IP CURLOPT_TLSAUTH_SRP TLS-SRP authentication. Secure Remote Password authentication for TLS is -defined in RFC 5054 and provides mutual authentication if both sides have a +defined in RFC5054 and provides mutual authentication if both sides have a shared secret. To use TLS-SRP, you must also set the \fICURLOPT_TLSAUTH_USERNAME\fP and \fICURLOPT_TLSAUTH_PASSWORD\fP options. @@ -1204,12 +1203,12 @@ an infinite number of redirects (which is the default) .IP CURLOPT_POSTREDIR Pass a bitmask to control how libcurl acts on redirects after POSTs that get a 301, 302 or 303 response back. A parameter with bit 0 set (value -\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 2616/10.3.2 and -not convert POST requests into GET requests when following a 301 -redirection. Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain -the request method after a 302 redirect. Setting bit 2 (value -\fBCURL_REDIR_POST_303) makes libcurl maintain the request method after a 302 -redirect. CURL_REDIR_POST_ALL is a convenience define that sets both bits. +\fBCURL_REDIR_POST_301\fP) tells the library to respect RFC2616/10.3.2 and not +convert POST requests into GET requests when following a 301 redirection. +Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain the request +method after a 302 redirect. Setting bit 2 (value \fBCURL_REDIR_POST_303) +makes libcurl maintain the request method after a 302 redirect. +CURL_REDIR_POST_ALL is a convenience define that sets both bits. The non-RFC behaviour is ubiquitous in web browsers, so the library does the conversion by default to maintain consistency. However, a server may require a @@ -1507,7 +1506,7 @@ should be used for this parameter. Unlike CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT, the address should not be specified within a pair of angled brackets (<>). However, if an empty string is used then a pair of brackets will be sent by libcurl as required by -RFC-2554. +RFC2554. (Added in 7.24.0) .SH TFTP OPTIONS @@ -1841,7 +1840,7 @@ want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in \fI"X-Y,N-M"\fP. Using this kind of multiple intervals will cause the HTTP server to send the response document in pieces (using standard MIME separation -techniques). For RTSP, the formatting of a range should follow RFC 2326 +techniques). For RTSP, the formatting of a range should follow RFC2326 Section 12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in npt, utc, or smpte formats. -- cgit v1.2.1 From 2839c059b1c4c319385a10ba2c4f7979fab813ea Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sat, 26 May 2012 13:08:37 +0100 Subject: DOCS: Fixed meaning of bit 2 in CURLOPT_POSTREDIR Setting bit 2 for this value was documented as having a constant value defined as CURL_REDIR_POST_303 yet referenced a 302 request. Additionally corrected the meaning of CURL_REDIR_POST_ALL for all three bits and fixed problems with the bolding of keywords in this section. --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 70d7cd5b4..0b7dc8386 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1205,17 +1205,17 @@ Pass a bitmask to control how libcurl acts on redirects after POSTs that get a 301, 302 or 303 response back. A parameter with bit 0 set (value \fBCURL_REDIR_POST_301\fP) tells the library to respect RFC2616/10.3.2 and not convert POST requests into GET requests when following a 301 redirection. -Setting bit 1 (value CURL_REDIR_POST_302) makes libcurl maintain the request -method after a 302 redirect. Setting bit 2 (value \fBCURL_REDIR_POST_303) -makes libcurl maintain the request method after a 302 redirect. -CURL_REDIR_POST_ALL is a convenience define that sets both bits. +Setting bit 1 (value \fBCURL_REDIR_POST_302\fP) makes libcurl maintain the +request method after a 302 redirect whilst setting bit 2 (value +\fBCURL_REDIR_POST_303\fP) makes libcurl maintain the request method after a +303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience define that +sets all three bits. The non-RFC behaviour is ubiquitous in web browsers, so the library does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION\fP. (Added in 7.17.1) (This option was -known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 way before -then) +known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 then) .IP CURLOPT_PUT A parameter set to 1 tells the library to use HTTP PUT to transfer data. The data should be set with \fICURLOPT_READDATA\fP and \fICURLOPT_INFILESIZE\fP. -- cgit v1.2.1 From 25c1b29226444f88a138557833e8542a68427cdf Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sat, 26 May 2012 14:05:45 +0100 Subject: DOCS: Changed domain names in various examples to example.com Updated various references of real domain names to example.com as per RFC-2606. --- docs/libcurl/curl_easy_setopt.3 | 51 +++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 25 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0b7dc8386..0c88fead8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -625,18 +625,18 @@ authentication. For example the following types of authentication support this: -http://user:password@www.domain.com -ftp://user:password@ftp.domain.com -pop3://user:password@mail.domain.com +http://user:password@www.example.com +ftp://user:password@ftp.example.com +pop3://user:password@mail.example.com The port is optional and when not specified libcurl will use the default port -based on the determined or specified protocol: 80 for http, 21 for ftp and 25 -for smtp, etc. The following examples show how to specify the port: +based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25 +for SMTP, etc. The following examples show how to specify the port: -http://www.weirdserver.com:8080/ - This will connect to a web server using -port 8080. +http://www.example.com:8080/ - This will connect to a web server using port +8080 rather than 80. -smtp://mail.domain.com:587/ - This will connect to a smtp server on the +smtp://mail.example.com:587/ - This will connect to a SMTP server on the alternative mail port. The path part of the URL is protocol specific and whilst some examples are @@ -651,13 +651,12 @@ retrieved for either the directory specified or the root directory. The exact resource returned for each URL is entirely dependent on the server's configuration. -http://www.netscape.com - This gets the main page (index.html in this -example) from Netscape's web server. +http://www.example.com - This gets the main page from the web server. -http://www.netscape.com/index.html - This returns the main page from Netscape -by specifying the page to get. +http://www.example.com/index.html - This returns the main page by explicitly +requesting it. -http://www.netscape.com/contactus/ - This returns the default document from +http://www.example.com/contactus/ - This returns the default document from the contactus directory. .B FTP @@ -667,15 +666,16 @@ directory. If the file part is omitted then libcurl downloads the directory listing for the directory specified. If the directory is omitted then the directory listing for the root / home directory will be returned. -ftp://cool.haxx.se - This retrieves the directory listing for our FTP server. +ftp://ftp.example.com - This retrieves the directory listing for the root +directory. -ftp://cool.haxx.se/readme.txt - This downloads the file readme.txt from the +ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the root directory. -ftp://cool.haxx.se/libcurl/readme.txt - This downloads readme.txt from the +ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the libcurl directory. -ftp://user:password@my.example.com/readme.txt - This retrieves the readme.txt +ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt file from the user's home directory. When a username and password is specified, everything that is specified in the path part is relative to the user's home directory. To retrieve files from the root directory or a @@ -683,7 +683,7 @@ directory underneath the root directory then the absolute path must be specified by prepending an additional forward slash to the beginning of the path. -ftp://user:password@my.example.com//readme.txt - This retrieves the readme.txt +ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt from the root directory when logging in as a specified user. .B SMTP @@ -696,11 +696,11 @@ and specifying this path allows you to set an alternative name, such as your machine's fully qualified domain name, which you might have obtained from an external function such as gethostname or getaddrinfo. -smtp://mail.domain.com - This connects to the mail server at domain.com and +smtp://mail.example.com - This connects to the mail server at example.com and sends your local computer's host name in the HELO / EHLO command. -smtp://mail.domain.com/client.domain.com - This will send client.domain.com in -the HELO / EHLO command to the mail server at domain.com. +smtp://mail.example.com/client.example.com - This will send client.example.com in +the HELO / EHLO command to the mail server at example.com. .B POP3 @@ -708,8 +708,8 @@ The path part of a POP3 request specifies the mailbox (message) to retrieve. If the mailbox is not specified then a list of waiting messages is returned instead. -pop3://user:password@mail.domain.com - This lists the available messages -pop3://user:password@mail.domain.com/1 - This retrieves the first message +pop3://user:password@mail.example.com - This lists the available messages +pop3://user:password@mail.example.com/1 - This retrieves the first message .B SCP @@ -843,8 +843,9 @@ Pass a pointer to a zero terminated string. This should be a comma separated list of hosts which do not use a proxy, if one is specified. The only wildcard is a single * character, which matches all hosts, and effectively disables the proxy. Each name in this list is matched as either a domain which -contains the hostname, or the hostname itself. For example, local.com would -match local.com, local.com:80, and www.local.com, but not www.notlocal.com. +contains the hostname, or the hostname itself. For example, example.com +would match example.com, example.com:80, and www.example.com, but not +www.notanexample.com. (Added in 7.19.4) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to 1 to make the library tunnel all operations through a -- cgit v1.2.1 From efb8471a69e0b5b9fe2296954b4917e294392372 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sat, 26 May 2012 14:15:33 +0100 Subject: DOCS: Fixed line spacing of authentication examples in CURLOPT_URL --- docs/libcurl/curl_easy_setopt.3 | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 0c88fead8..5174a6593 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -626,7 +626,9 @@ authentication. For example the following types of authentication support this: http://user:password@www.example.com + ftp://user:password@ftp.example.com + pop3://user:password@mail.example.com The port is optional and when not specified libcurl will use the default port -- cgit v1.2.1 From 3124a8df936182a9702e6357486c8f3bcb9a3d67 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sun, 27 May 2012 20:04:36 +0100 Subject: DOCS: Corrected the "Added in" version number for CURLOPT_MAIL_AUTH Additionally corrected another RFC link that I missed yesterday. --- docs/libcurl/curl_easy_setopt.3 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 5174a6593..a587f2e05 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1511,14 +1511,14 @@ specified within a pair of angled brackets (<>). However, if an empty string is used then a pair of brackets will be sent by libcurl as required by RFC2554. -(Added in 7.24.0) +(Added in 7.25.0) .SH TFTP OPTIONS .IP CURLOPT_TFTP_BLKSIZE -Specify block size to use for TFTP data transmission. Valid range as per RFC -2348 is 8-65464 bytes. The default of 512 bytes will be used if this option is -not specified. The specified block size will only be used pending support by -the remote server. If the server does not return an option acknowledgement or -returns an option acknowledgement with no blksize, the default of 512 bytes +Specify block size to use for TFTP data transmission. Valid range as per +RFC2348 is 8-65464 bytes. The default of 512 bytes will be used if this option +is not specified. The specified block size will only be used pending support +by the remote server. If the server does not return an option acknowledgement +or returns an option acknowledgement with no blksize, the default of 512 bytes will be used. (added in 7.19.4) .SH FTP OPTIONS .IP CURLOPT_FTPPORT -- cgit v1.2.1 From b511486fcd5f1344eccb126c16e05c485abc3abd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Jun 2012 19:59:48 +0200 Subject: curl_easy_setopt.3: proto updates + cleanups - For all *FUNCTION options, they now all show the complete prototype in the description. Previously some of them would just refer to a typedef'ed function pointer in the curl.h header. - I made the phrasing of that "Pass a pointer to a function that matches the following prototype" the same for all *FUNCTION option descriptions. - I removed some uses of 'should'. I think I sometimes over-use this word as in many places I actually mean MUST or otherwise more specific and not-so-optional synonyms. --- docs/libcurl/curl_easy_setopt.3 | 245 ++++++++++++++++++++-------------------- 1 file changed, 124 insertions(+), 121 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a587f2e05..807d3ba41 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -147,10 +147,10 @@ Using the rules above, a file name pattern can be constructed: (This was added in 7.21.0) .SH CALLBACK OPTIONS .IP CURLOPT_WRITEFUNCTION -Function pointer that should match the following prototype: \fBsize_t -function( char *ptr, size_t size, size_t nmemb, void *userdata);\fP This -function gets called by libcurl as soon as there is data received that needs -to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP +Pass a pointer to a function that matches the following prototype: +\fBsize_t function( char *ptr, size_t size, size_t nmemb, void *userdata);\fP +This function gets called by libcurl as soon as there is data received that +needs to be saved. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied with \fInmemb\fP, it will not be zero terminated. Return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the @@ -193,11 +193,11 @@ crashes. This option is also known with the older name \fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA\fP was introduced in 7.9.7. .IP CURLOPT_READFUNCTION -Function pointer that should match the following prototype: \fBsize_t -function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP This -function gets called by libcurl as soon as it needs to read data in order to -send it to the peer. The data area pointed at by the pointer \fIptr\fP may be -filled with at most \fIsize\fP multiplied with \fInmemb\fP number of +Pass a pointer to a function that matches the following prototype: +\fBsize_t function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP +This function gets called by libcurl as soon as it needs to read data in order +to send it to the peer. The data area pointed at by the pointer \fIptr\fP may +be filled with at most \fIsize\fP multiplied with \fInmemb\fP number of bytes. Your function must return the actual number of bytes that you stored in that memory area. Returning 0 will signal end-of-file to the library and cause it to stop the current transfer. @@ -234,13 +234,13 @@ If you're using libcurl as a win32 DLL, you MUST use a This option was also known by the older name \fICURLOPT_INFILE\fP, the name \fICURLOPT_READDATA\fP was introduced in 7.9.7. .IP CURLOPT_IOCTLFUNCTION -Function pointer that should match the \fIcurl_ioctl_callback\fP prototype -found in \fI\fP. This function gets called by libcurl when -something special I/O-related needs to be done that the library can't do by -itself. For now, rewinding the read data stream is the only action it can -request. The rewinding of the read data stream may be necessary when doing a -HTTP PUT or POST with a multi-pass authentication method. (Option added in -7.12.3). +Pass a pointer to a function that matches the following prototype: +\fBcurlioerr function(CURL *handle, int cmd, void *clientp);\fP. This function +gets called by libcurl when something special I/O-related needs to be done +that the library can't do by itself. For now, rewinding the read data stream +is the only action it can request. The rewinding of the read data stream may +be necessary when doing a HTTP PUT or POST with a multi-pass authentication +method. (Option added in 7.12.3). Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking! .IP CURLOPT_IOCTLDATA @@ -248,7 +248,7 @@ Pass a pointer that will be untouched by libcurl and passed as the 3rd argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP. (Option added in 7.12.3) .IP CURLOPT_SEEKFUNCTION -Function pointer that should match the following prototype: \fIint +Pass a pointer to a function that matches the following prototype: \fBint function(void *instream, curl_off_t offset, int origin);\fP This function gets called by libcurl to seek to a certain position in the input stream and can be used to fast forward a file in a resumed upload (instead of reading all @@ -270,18 +270,18 @@ Data pointer to pass to the file seek function. If you use the \fICURLOPT_SEEKFUNCTION\fP option, this is the pointer you'll get as input. If you don't specify a seek callback, NULL is passed. (Option added in 7.18.0) .IP CURLOPT_SOCKOPTFUNCTION -Function pointer that should match the \fIcurl_sockopt_callback\fP prototype -found in \fI\fP. This function gets called by libcurl after the -socket() call but before the connect() call. The callback's \fIpurpose\fP -argument identifies the exact purpose for this particular socket, and -currently only one value is supported: \fICURLSOCKTYPE_IPCXN\fP for the -primary connection (meaning the control connection in the FTP case). Future -versions of libcurl may support more purposes. It passes the newly created -socket descriptor so additional setsockopt() calls can be done at the user's -discretion. Return 0 (zero) from the callback on success. Return 1 from the -callback function to signal an unrecoverable error to the library and it will -close the socket and return \fICURLE_COULDNT_CONNECT\fP. (Option added in -7.16.0) +Pass a pointer to a function that matches the following prototype: \fBint +function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. This +function gets called by libcurl after the socket() call but before the +connect() call. The callback's \fIpurpose\fP argument identifies the exact +purpose for this particular socket, and currently only one value is supported: +\fICURLSOCKTYPE_IPCXN\fP for the primary connection (meaning the control +connection in the FTP case). Future versions of libcurl may support more +purposes. It passes the newly created socket descriptor so additional +setsockopt() calls can be done at the user's discretion. Return 0 (zero) from +the callback on success. Return 1 from the callback function to signal an +unrecoverable error to the library and it will close the socket and return +\fICURLE_COULDNT_CONNECT\fP. (Option added in 7.16.0) Added in 7.21.5, the callback function may return \fICURL_SOCKOPT_ALREADY_CONNECTED\fP, which tells libcurl that the socket is @@ -291,20 +291,21 @@ Pass a pointer that will be untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP. (Option added in 7.16.0) .IP CURLOPT_OPENSOCKETFUNCTION -Function pointer that should match the \fIcurl_opensocket_callback\fP -prototype found in \fI\fP. This function gets called by libcurl -instead of the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument -identifies the exact purpose for this particular socket: -\fICURLSOCKTYPE_IPCXN\fP is for IP based connections. Future versions of -libcurl may support more purposes. It passes the resolved peer address as a -\fIaddress\fP argument so the callback can modify the address or refuse to -connect at all. The callback function should return the socket or -\fICURL_SOCKET_BAD\fP in case no connection should be established or any error -detected. Any additional \fIsetsockopt(2)\fP calls can be done on the socket -at the user's discretion. \fICURL_SOCKET_BAD\fP return value from the -callback function will signal an unrecoverable error to the library and it -will return \fICURLE_COULDNT_CONNECT\fP. This return code can be used for IP -address blacklisting. The default behavior is: +Pass a pointer to a function that matches the following prototype: +\fBcurl_socket_t function(void *clientp, curlsocktype purpose, struct +curl_sockaddr *address);\fP. This function gets called by libcurl instead of +the \fIsocket(2)\fP call. The callback's \fIpurpose\fP argument identifies the +exact purpose for this particular socket: \fICURLSOCKTYPE_IPCXN\fP is for IP +based connections. Future versions of libcurl may support more purposes. It +passes the resolved peer address as a \fIaddress\fP argument so the callback +can modify the address or refuse to connect at all. The callback function +should return the socket or \fICURL_SOCKET_BAD\fP in case no connection could +be established or another error was detected. Any additional +\fIsetsockopt(2)\fP calls can be done on the socket at the user's discretion. +\fICURL_SOCKET_BAD\fP return value from the callback function will signal an +unrecoverable error to the library and it will return +\fICURLE_COULDNT_CONNECT\fP. This return code can be used for IP address +blacklisting. The default behavior is: .nf return socket(addr->family, addr->socktype, addr->protocol); .fi @@ -314,25 +315,26 @@ Pass a pointer that will be untouched by libcurl and passed as the first argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP. (Option added in 7.17.1.) .IP CURLOPT_CLOSESOCKETFUNCTION -Function pointer that should match the \fIcurl_closesocket_callback\fP -prototype found in \fI\fP. This function gets called by libcurl -instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when sockets are -closed (not for any other file descriptors). This is pretty much the reverse -to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal success and -1 if there was an error. (Option added in 7.21.7) +Pass a pointer to a function that matches the following prototype: \fBint +function(void *clientp, curl_socket_t item);\fP. This function gets called by +libcurl instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when +sockets are closed (not for any other file descriptors). This is pretty much +the reverse to the \fICURLOPT_OPENSOCKETFUNCTION\fP option. Return 0 to signal +success and 1 if there was an error. (Option added in 7.21.7) .IP CURLOPT_CLOSESOCKETDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the closesocket callback set with \fICURLOPT_CLOSESOCKETFUNCTION\fP. (Option added in 7.21.7) .IP CURLOPT_PROGRESSFUNCTION -Function pointer that should match the \fIcurl_progress_callback\fP prototype -found in \fI\fP. This function gets called by libcurl instead of -its internal equivalent with a frequent interval during operation (roughly -once per second or sooner) no matter if data is being transfered or not. -Unknown/unused argument values passed to the callback will be set to zero -(like if you only download data, the upload size will remain 0). Returning a -non-zero value from this callback will cause libcurl to abort the transfer and -return \fICURLE_ABORTED_BY_CALLBACK\fP. +Pass a pointer to a function that matches the following prototype: \fBint +function(void *clientp, double dltotal, double dlnow, double ultotal, double +ulnow); \fP. This function gets called by libcurl instead of its internal +equivalent with a frequent interval during operation (roughly once per second +or sooner) no matter if data is being transfered or not. Unknown/unused +argument values passed to the callback will be set to zero (like if you only +download data, the upload size will remain 0). Returning a non-zero value from +this callback will cause libcurl to abort the transfer and return +\fICURLE_ABORTED_BY_CALLBACK\fP. If you transfer data with the multi interface, this function will not be called during periods of idleness unless you call the appropriate libcurl @@ -344,14 +346,14 @@ get called. Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. .IP CURLOPT_HEADERFUNCTION -Function pointer that should match the following prototype: \fIsize_t -function( void *ptr, size_t size, size_t nmemb, void *userdata);\fP. This -function gets called by libcurl as soon as it has received header data. The -header callback will be called once for each header and only complete header -lines are passed on to the callback. Parsing headers is very easy using -this. The size of the data pointed to by \fIptr\fP is \fIsize\fP multiplied -with \fInmemb\fP. Do not assume that the header line is zero terminated! The -pointer named \fIuserdata\fP is the one you set with the +Pass a pointer to a function that matches the following prototype: +\fBsize_t function( void *ptr, size_t size, size_t nmemb, void +*userdata);\fP. This function gets called by libcurl as soon as it has +received header data. The header callback will be called once for each header +and only complete header lines are passed on to the callback. Parsing headers +is very easy using this. The size of the data pointed to by \fIptr\fP is +\fIsize\fP multiplied with \fInmemb\fP. Do not assume that the header line is +zero terminated! The pointer named \fIuserdata\fP is the one you set with the \fICURLOPT_WRITEHEADER\fP option. The callback function must return the number of bytes actually taken care of. If that amount differs from the amount passed to your function, it'll signal an error to the library. This will abort the @@ -391,7 +393,7 @@ the writing, this must be a valid FILE * as the internal default will then be a plain fwrite(). See also the \fICURLOPT_HEADERFUNCTION\fP option above on how to set a custom get-all-headers callback. .IP CURLOPT_DEBUGFUNCTION -Function pointer that should match the following prototype: \fIint +Pass a pointer to a function that matches the following prototype: \fBint curl_debug_callback (CURL *, curl_infotype, char *, size_t, void *);\fP \fICURLOPT_DEBUGFUNCTION\fP replaces the standard debug function used when \fICURLOPT_VERBOSE \fP is in effect. This callback receives debug information, @@ -420,11 +422,11 @@ used by libcurl, it is only passed to the callback. This option does only function for libcurl powered by OpenSSL. If libcurl was built against another SSL library, this functionality is absent. -Function pointer that should match the following prototype: \fBCURLcode -sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function gets called -by libcurl just before the initialization of a SSL connection after having -processed all other SSL related options to give a last chance to an -application to modify the behaviour of openssl's ssl initialization. The +Pass a pointer to a function that matches the following prototype: +\fBCURLcode sslctxfun(CURL *curl, void *sslctx, void *parm);\fP This function +gets called by libcurl just before the initialization of a SSL connection +after having processed all other SSL related options to give a last chance to +an application to modify the behaviour of openssl's ssl initialization. The \fIsslctx\fP parameter is actually a pointer to an openssl \fISSL_CTX\fP. If an error is returned no attempt to establish a connection is made and the perform operation will return the error code from this callback function. Set @@ -447,8 +449,8 @@ parameter, otherwise \fBNULL\fP. (Added in 7.11.0) .IP CURLOPT_CONV_TO_NETWORK_FUNCTION .IP CURLOPT_CONV_FROM_NETWORK_FUNCTION .IP CURLOPT_CONV_FROM_UTF8_FUNCTION -Function pointers that should match the following prototype: CURLcode -function(char *ptr, size_t length); +Pass a pointer to a function that matches the following prototype: +\fBCURLcode function(char *ptr, size_t length);\fP These three options apply to non-ASCII platforms only. They are available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. When @@ -490,16 +492,17 @@ follows: You will need to override these definitions if they are different on your system. .IP CURLOPT_INTERLEAVEFUNCTION -Function pointer that should match the following prototype: \fIsize_t -function( void *ptr, size_t size, size_t nmemb, void *userdata)\fP. This -function gets called by libcurl as soon as it has received interleaved RTP -data. This function gets called for each $ block and therefore contains -exactly one upper-layer protocol unit (e.g. one RTP packet). Curl writes the -interleaved header as well as the included data for each call. The first byte -is always an ASCII dollar sign. The dollar sign is followed by a one byte -channel identifier and then a 2 byte integer length in network byte order. See -\fIRFC2326 Section 10.12\fP for more information on how RTP interleaving -behaves. If unset or set to NULL, curl will use the default write function. +Pass a pointer to a function that matches the following prototype: +\fBsize_t function( void *ptr, size_t size, size_t nmemb, void +*userdata)\fP. This function gets called by libcurl as soon as it has received +interleaved RTP data. This function gets called for each $ block and therefore +contains exactly one upper-layer protocol unit (e.g. one RTP packet). Curl +writes the interleaved header as well as the included data for each call. The +first byte is always an ASCII dollar sign. The dollar sign is followed by a +one byte channel identifier and then a 2 byte integer length in network byte +order. See \fIRFC2326 Section 10.12\fP for more information on how RTP +interleaving behaves. If unset or set to NULL, curl will use the default write +function. Interleaved RTP poses some challeneges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service @@ -515,10 +518,10 @@ This is the userdata pointer that will be passed to \fICURLOPT_INTERLEAVEFUNCTION\fP when interleaved RTP data is received. (Added in 7.20.0) .IP CURLOPT_CHUNK_BGN_FUNCTION -Function pointer that should match the following prototype: \fBlong function -(const void *transfer_info, void *ptr, int remains)\fP. This function gets -called by libcurl before a part of the stream is going to be transferred (if -the transfer supports chunks). +Pass a pointer to a function that matches the following prototype: +\fBlong function (const void *transfer_info, void *ptr, int remains)\fP. This +function gets called by libcurl before a part of the stream is going to be +transferred (if the transfer supports chunks). This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH\fP option for now. @@ -535,9 +538,9 @@ Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine, \fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred. (This was added in 7.21.0) .IP CURLOPT_CHUNK_END_FUNCTION -Function pointer that should match the following prototype: \fBlong -function(void *ptr)\fP. This function gets called by libcurl as soon as a part -of the stream has been transferred (or skipped). +Pass a pointer to a function that matches the following prototype: +\fBlong function(void *ptr)\fP. This function gets called by libcurl as soon +as a part of the stream has been transferred (or skipped). Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or \fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred. @@ -547,9 +550,9 @@ Pass a pointer that will be untouched by libcurl and passed as the ptr argument to the \fICURL_CHUNK_BGN_FUNTION\fP and \fICURL_CHUNK_END_FUNTION\fP. (This was added in 7.21.0) .IP CURLOPT_FNMATCH_FUNCTION -Function pointer that should match \fBint function(void *ptr, const char -*pattern, const char *string)\fP prototype (see \fIcurl/curl.h\fP). It is used -internally for the wildcard matching feature. +Pass a pointer to a function that matches the following prototype: \fBint +function(void *ptr, const char *pattern, const char *string)\fP prototype (see +\fIcurl/curl.h\fP). It is used internally for the wildcard matching feature. Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, \fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an @@ -563,11 +566,11 @@ Pass a char * to a buffer that the libcurl may store human readable error messages in. This may be more helpful than just the return code from \fIcurl_easy_perform\fP. The buffer must be at least CURL_ERROR_SIZE big. Although this argument is a 'char *', it does not describe an input string. -Therefore the (probably undefined) contents of the buffer is NOT copied -by the library. You should keep the associated storage available until -libcurl no longer needs it. Failing to do so will cause very odd behavior -or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP -or you set the same option again to use a different pointer. +Therefore the (probably undefined) contents of the buffer is NOT copied by the +library. You must keep the associated storage available until libcurl no +longer needs it. Failing to do so will cause very odd behavior or even +crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP or you +set the same option again to use a different pointer. Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better debug/trace why errors happen. @@ -592,8 +595,9 @@ detected, like when a "100-continue" is received as a response to a POST/PUT and a 401 or 407 is received immediately afterwards. .SH NETWORK OPTIONS .IP CURLOPT_URL -The actual URL to deal with. The parameter should be a char * to a zero -terminated string which must be URL-encoded in the following format: +Pass in a pointer to the actual URL to deal with. The parameter should be a +char * to a zero terminated string which must be URL-encoded in the following +format: scheme://host:port/path @@ -841,14 +845,14 @@ affect how libcurl speaks to a proxy when CONNECT is used. The HTTP version used for "regular" HTTP requests is instead controlled with \fICURLOPT_HTTP_VERSION\fP. .IP CURLOPT_NOPROXY -Pass a pointer to a zero terminated string. This should be a comma separated -list of hosts which do not use a proxy, if one is specified. The only -wildcard is a single * character, which matches all hosts, and effectively -disables the proxy. Each name in this list is matched as either a domain which -contains the hostname, or the hostname itself. For example, example.com -would match example.com, example.com:80, and www.example.com, but not -www.notanexample.com. -(Added in 7.19.4) +Pass a pointer to a zero terminated string. The string consists of a comma +separated list of host names that do not require a proxy to get reached, even +if one is specified. The only wildcard available is a single * character, +which matches all hosts, and effectively disables the proxy. Each name in this +list is matched as either a domain which contains the hostname, or the +hostname itself. For example, example.com would match example.com, +example.com:80, and www.example.com, but not www.notanexample.com. (Added in +7.19.4) .IP CURLOPT_HTTPPROXYTUNNEL Set the parameter to 1 to make the library tunnel all operations through a given HTTP proxy. There is a big difference between using a proxy and to @@ -883,7 +887,7 @@ connection. This can be used in combination with \fICURLOPT_INTERFACE\fP and you are recommended to use \fICURLOPT_LOCALPORTRANGE\fP as well when this is set. Valid port numbers are 1 - 65535. (Added in 7.15.2) .IP CURLOPT_LOCALPORTRANGE -Pass a long. This is the number of attempts libcurl should make to find a +Pass a long. This is the number of attempts libcurl will make to find a working local port number. It starts with the given \fICURLOPT_LOCALPORT\fP and adds one to the number for each retry. Setting this to 1 or below will make libcurl do only one try for the exact port number. Port numbers by nature @@ -922,21 +926,20 @@ only makes sense to use this option if you want it smaller. Pass a long specifying what remote port number to connect to, instead of the one specified in the URL or the default port for the used protocol. .IP CURLOPT_TCP_NODELAY -Pass a long specifying whether the TCP_NODELAY option should be set or -cleared (1 = set, 0 = clear). The option is cleared by default. This -will have no effect after the connection has been established. +Pass a long specifying whether the TCP_NODELAY option is to be set or cleared +(1 = set, 0 = clear). The option is cleared by default. This will have no +effect after the connection has been established. -Setting this option will disable TCP's Nagle algorithm. The purpose of -this algorithm is to try to minimize the number of small packets on -the network (where "small packets" means TCP segments less than the -Maximum Segment Size (MSS) for the network). +Setting this option will disable TCP's Nagle algorithm. The purpose of this +algorithm is to try to minimize the number of small packets on the network +(where "small packets" means TCP segments less than the Maximum Segment Size +(MSS) for the network). Maximizing the amount of data sent per TCP segment is good because it -amortizes the overhead of the send. However, in some cases (most -notably telnet or rlogin) small segments may need to be sent -without delay. This is less efficient than sending larger amounts of -data at a time, and can contribute to congestion on the network if -overdone. +amortizes the overhead of the send. However, in some cases (most notably +telnet or rlogin) small segments may need to be sent without delay. This is +less efficient than sending larger amounts of data at a time, and can +contribute to congestion on the network if overdone. .IP CURLOPT_ADDRESS_SCOPE Pass a long specifying the scope_id value to use when connecting to IPv6 link-local or site-local addresses. (Added in 7.19.0) -- cgit v1.2.1 From 1eb74f94c46aa3168eb37da304288d84241e92ec Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Sun, 24 Jun 2012 23:23:30 +0100 Subject: DOCS: Added clarification to CURLOPT_CUSTOMREQUEST for the POP3 protocol Bug: http://curl.haxx.se/mail/lib-2012-06/0302.html Reported by: Nagai H --- docs/libcurl/curl_easy_setopt.3 | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 807d3ba41..a9fa239a8 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -1883,12 +1883,18 @@ something, you don't actually change how libcurl behaves or acts in regards to the particular request method, it will only change the actual string sent in the request. -For example: if you tell libcurl to do a HEAD request, but then change the -request to a "GET" with \fBCURLOPT_CUSTOMREQUEST\fP you'll still see libcurl -act as if it sent a HEAD even when it does send a GET. +For example: + +With the HTTP protocol when you tell libcurl to do a HEAD request, but then +specify a GET though a custom request libcurl will still act as if it sent a +HEAD. To switch to a proper HEAD use \fICURLOPT_NOBODY\fP, to switch to a +proper POST use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and to switch +to a proper GET use CURLOPT_HTTPGET. -To switch to a proper HEAD, use \fICURLOPT_NOBODY\fP, to switch to a proper -POST, use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and so on. +With the POP3 protocol when you tell libcurl to use a custom request it will +behave like a LIST or RETR command was sent where it expects data to be +returned by the server. As such \fICURLOPT_NOBODY\fP should be used when +specifing commands such as DELE and NOOP for example. Restore to the internal default by setting this to NULL. -- cgit v1.2.1 From 39a72bbcd122f63bcfff1eada45a899941451381 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 2 Jul 2012 00:10:59 +0200 Subject: errors: CURLM_CALL_MULTI_PERFORM is not returned anymore --- docs/libcurl/libcurl-errors.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index 8ad1facc6..ab37f876e 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -248,7 +248,10 @@ This is the generic return code used by functions in the libcurl multi interface. Also consider \fIcurl_multi_strerror(3)\fP. .IP "CURLM_CALL_MULTI_PERFORM (-1)" This is not really an error. It means you should call -\fIcurl_multi_perform(3)\fP again without doing select() or similar in between. +\fIcurl_multi_perform(3)\fP again without doing select() or similar in +between. Before version 7.20.0 this could be returned by +\fIcurl_multi_perform(3)\fP, but in later versions this return code is never +used. .IP "CURLM_OK (0)" Things are fine. .IP "CURLM_BAD_HANDLE (1)" -- cgit v1.2.1 From 304e24e2113d2a98d7a6fe851b2fc0a20ab0f1c9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 3 Jul 2012 17:18:36 +0200 Subject: docs: clarify how to start with curl_multi_socket_action Mention the CURL_SOCKET_TIMEOUT argument in step 6 of the typical application. --- docs/libcurl/curl_multi_socket_action.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_socket_action.3 b/docs/libcurl/curl_multi_socket_action.3 index f93e914da..ac3b176c7 100644 --- a/docs/libcurl/curl_multi_socket_action.3 +++ b/docs/libcurl/curl_multi_socket_action.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -132,8 +132,8 @@ timeout value to use when waiting for socket activities. them for activity. This can be done through your application code, or by way of an external library such as libevent or glib. -6. Call curl_multi_socket_action() to kickstart everything. To get one or more -callbacks called. +6. Call curl_multi_socket_action(...CURL_SOCKET_TIMEOUT...) to kickstart +everything. To get one or more callbacks called. 7. Wait for activity on any of libcurl's sockets, use the timeout value your callback has been told -- cgit v1.2.1 From b7298e49ae1a97ca9b53b29efc95bd1b7fee5dcf Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 12 Jul 2012 08:40:43 +0200 Subject: docs: mention CURL_GLOBAL_DEFAULT --- docs/libcurl/curl_global_init.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index 5fff6c556..d91e1bdb7 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -66,6 +66,10 @@ Initialize the Win32 socket libraries. .TP .B CURL_GLOBAL_NOTHING Initialise nothing extra. This sets no bit. +.TP +.B CURL_GLOBAL_DEFAULT +A sensible default. It will init both SSL and Win32. Right now, this equals +the functionality of the \fBCURL_GLOBAL_ALL\fP mask. .SH RETURN VALUE If this function returns non-zero, something went wrong and you cannot use the other curl functions. -- cgit v1.2.1 From cb787b70bf5fa16bc1f83405c16d6c092e6daf46 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Fri, 20 Jul 2012 21:02:58 +0200 Subject: Fixed some typos in documentation --- docs/libcurl/curl_easy_setopt.3 | 16 ++++++++-------- docs/libcurl/curl_share_setopt.3 | 2 +- docs/libcurl/libcurl-errors.3 | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a9fa239a8..710df3e84 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -330,7 +330,7 @@ Pass a pointer to a function that matches the following prototype: \fBint function(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow); \fP. This function gets called by libcurl instead of its internal equivalent with a frequent interval during operation (roughly once per second -or sooner) no matter if data is being transfered or not. Unknown/unused +or sooner) no matter if data is being transferred or not. Unknown/unused argument values passed to the callback will be set to zero (like if you only download data, the upload size will remain 0). Returning a non-zero value from this callback will cause libcurl to abort the transfer and return @@ -504,7 +504,7 @@ order. See \fIRFC2326 Section 10.12\fP for more information on how RTP interleaving behaves. If unset or set to NULL, curl will use the default write function. -Interleaved RTP poses some challeneges for the client application. Since the +Interleaved RTP poses some challenges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service the RTP in a timely fashion. If the RTP data is not handled quickly, subsequent response processing may become unreasonably delayed and the @@ -1173,8 +1173,8 @@ the server is ignored. See the special file lib/README.encoding for details. .IP CURLOPT_TRANSFER_ENCODING Adds a request for compressed Transfer Encoding in the outgoing HTTP request. If the server supports this and so desires, it can respond with the -HTTP resonse sent using a compressed Transfer-Encoding that will be -automatically uncompressed by libcurl on receival. +HTTP response sent using a compressed Transfer-Encoding that will be +automatically uncompressed by libcurl on reception. Transfer-Encoding differs slightly from the Content-Encoding you ask for with \fBCURLOPT_ACCEPT_ENCODING\fP in that a Transfer-Encoding is strictly meant to @@ -1636,7 +1636,7 @@ already exists or lack of permissions prevents creation. (Added in 7.16.3) Starting with 7.19.4, you can also set this value to 2, which will make libcurl retry the CWD command again if the subsequent MKD command fails. This -is especially useful if you're doing many simultanoes connections against the +is especially useful if you're doing many simultaneous connections against the same server and they all have this option enabled, as then CWD may first fail but then another connection does MKD before this connection and thus MKD fails but trying CWD works! 7.19.4 also introduced the \fICURLFTP_CREATE_DIR\fP and @@ -1723,7 +1723,7 @@ initialized. (Added in 7.20.0) .RS .IP CURL_RTSPREQ_OPTIONS Used to retrieve the available methods of the server. The application is -responsbile for parsing and obeying the response. \fB(The session ID is not +responsible for parsing and obeying the response. \fB(The session ID is not needed for this method.)\fP (Added in 7.20.0) .IP CURL_RTSPREQ_DESCRIBE Used to get the low level description of a stream. The application should note @@ -1894,7 +1894,7 @@ to a proper GET use CURLOPT_HTTPGET. With the POP3 protocol when you tell libcurl to use a custom request it will behave like a LIST or RETR command was sent where it expects data to be returned by the server. As such \fICURLOPT_NOBODY\fP should be used when -specifing commands such as DELE and NOOP for example. +specifying commands such as DELE and NOOP for example. Restore to the internal default by setting this to NULL. @@ -2379,7 +2379,7 @@ require you to disable this in order for you to succeed. (Added in 7.16.0) Pass a long with a bitmask to tell libcurl about specific SSL behaviors. CURLSSLOPT_ALLOW_BEAST is the only supported bit and by setting this the user -will tell libcurl to not attempt to use any work-arounds for a security flaw +will tell libcurl to not attempt to use any workarounds for a security flaw in the SSL3 and TLS1.0 protocols. If this option isn't used or this bit is set to 0, the SSL layer libcurl uses may use a work-around for this flaw although it might cause interoperability problems with some (older) SSL diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index 295423ae3..c196743ff 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -65,7 +65,7 @@ object. Note that when you use the multi interface, all easy handles added to the same multi handle will share DNS cache by default without this having to be used! .IP CURL_LOCK_DATA_SSL_SESSION -SSL session IDs will be shared accross the easy handles using this shared +SSL session IDs will be shared across the easy handles using this shared object. This will reduce the time spent in the SSL handshake when reconnecting to the same server. Note SSL session IDs are reused within the same easy handle by default. diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index ab37f876e..beee3971f 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -285,5 +285,5 @@ An invalid share object was passed to the function. Not enough memory was available. (Added in 7.12.0) .IP "CURLSHE_NOT_BUILT_IN (5)" -The requsted sharing could not be done because the library you use don't have +The requested sharing could not be done because the library you use don't have that particular feature enabled. (Added in 7.23.0) -- cgit v1.2.1 From 8a279d2275280c813b2f646e48129c93a9e863b0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 24 Jul 2012 00:29:39 +0200 Subject: curl_easy_setopt: fix typo Reported by: Santhana Todatry --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 710df3e84..25a7d5e68 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -69,7 +69,7 @@ output. This is only relevant for protocols that actually have headers preceding the data (like HTTP). .IP CURLOPT_NOPROGRESS Pass a long. If set to 1, it tells the library to shut off the progress meter -completely. It will also present the \fICURLOPT_PROGRESSFUNCTION\fP from +completely. It will also prevent the \fICURLOPT_PROGRESSFUNCTION\fP from getting called. Future versions of libcurl are likely to not have any built-in progress meter -- cgit v1.2.1 From 0774386b23fcf4c499f9ca010fbb16477a0e988b Mon Sep 17 00:00:00 2001 From: Armel Asselin Date: Fri, 16 Mar 2012 22:40:39 +0100 Subject: docs: mention CURLSSH_AUTH_AGENT --- docs/libcurl/curl_easy_setopt.3 | 7 +++++-- docs/libcurl/symbols-in-versions | 1 + 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 25a7d5e68..27f19b9d5 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2405,8 +2405,11 @@ GSS_C_DELEG_POLICY_FLAG was available at compile-time. .IP CURLOPT_SSH_AUTH_TYPES Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, -CURLSSH_AUTH_KEYBOARD. Set CURLSSH_AUTH_ANY to let libcurl pick one. Currently -CURLSSH_AUTH_HOST has no effect. (Added in 7.16.1) +CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT. Set CURLSSH_AUTH_ANY to let +libcurl pick a suitable one. Currently CURLSSH_AUTH_HOST has no effect. (Added +in 7.16.1) If CURLSSH_AUTH_AGENT is used, libcurl attempts to connect to +ssh-agent or pageant and let the agent attempt the authentication. (Added in +7.28.0) .IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 Pass a char * pointing to a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host's public key, and diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 41705fd29..c738259eb 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -568,6 +568,7 @@ CURLSHOPT_UNLOCKFUNC 7.10.3 CURLSHOPT_UNSHARE 7.10.3 CURLSHOPT_USERDATA 7.10.3 CURLSOCKTYPE_IPCXN 7.16.0 +CURLSSH_AUTH_AGENT 7.28.0 CURLSSH_AUTH_ANY 7.16.1 CURLSSH_AUTH_DEFAULT 7.16.1 CURLSSH_AUTH_HOST 7.16.1 -- cgit v1.2.1 From f208bf5a2d622ae525690dfba2ab58abd8d72264 Mon Sep 17 00:00:00 2001 From: Kamil Dudka Date: Thu, 9 Aug 2012 14:08:11 +0200 Subject: docs: update the links to cipher-suites supported by NSS ... and make the list of cipher-suites in nss.c readable by humans. Bug: http://curl.haxx.se/mail/archive-2012-08/0016.html --- docs/libcurl/curl_easy_setopt.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 27f19b9d5..68117d5cf 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2367,7 +2367,7 @@ this option then all known ciphers are disabled and only those passed in are enabled. You'll find more details about the NSS cipher lists on this URL: -\fIhttp://directory.fedora.redhat.com/docs/mod_nss.html#Directives\fP +\fIhttp://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives\fP .IP CURLOPT_SSL_SESSIONID_CACHE Pass a long set to 0 to disable libcurl's use of SSL session-ID caching. Set -- cgit v1.2.1 From 41a3bff3da6b13fb8cab952c41e81ecfb518ec87 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 16 Aug 2012 23:32:55 +0200 Subject: curl_easy_setopt: documented CURLSOCKTYPE_ACCEPT for SOCKOPTFUNCTION --- docs/libcurl/curl_easy_setopt.3 | 20 ++++++++++++-------- docs/libcurl/symbols-in-versions | 1 + 2 files changed, 13 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 68117d5cf..3b0dc6c9d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -274,14 +274,18 @@ Pass a pointer to a function that matches the following prototype: \fBint function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. This function gets called by libcurl after the socket() call but before the connect() call. The callback's \fIpurpose\fP argument identifies the exact -purpose for this particular socket, and currently only one value is supported: -\fICURLSOCKTYPE_IPCXN\fP for the primary connection (meaning the control -connection in the FTP case). Future versions of libcurl may support more -purposes. It passes the newly created socket descriptor so additional -setsockopt() calls can be done at the user's discretion. Return 0 (zero) from -the callback on success. Return 1 from the callback function to signal an -unrecoverable error to the library and it will close the socket and return -\fICURLE_COULDNT_CONNECT\fP. (Option added in 7.16.0) +purpose for this particular socket: + +\fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0 +\fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV +(in earlier versions these sockets weren't passed to this callback). + +Future versions of libcurl may support more purposes. It passes the newly +created socket descriptor so additional setsockopt() calls can be done at the +user's discretion. Return 0 (zero) from the callback on success. Return 1 +from the callback function to signal an unrecoverable error to the library and +it will close the socket and return \fICURLE_COULDNT_CONNECT\fP. (Option +added in 7.16.0) Added in 7.21.5, the callback function may return \fICURL_SOCKOPT_ALREADY_CONNECTED\fP, which tells libcurl that the socket is diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index c738259eb..74e2958f9 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -567,6 +567,7 @@ CURLSHOPT_SHARE 7.10.3 CURLSHOPT_UNLOCKFUNC 7.10.3 CURLSHOPT_UNSHARE 7.10.3 CURLSHOPT_USERDATA 7.10.3 +CURLSOCKTYPE_ACCEPT 7.28.0 CURLSOCKTYPE_IPCXN 7.16.0 CURLSSH_AUTH_AGENT 7.28.0 CURLSSH_AUTH_ANY 7.16.1 -- cgit v1.2.1 From ba569a27cc0248fba83163ce12540913774369d8 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 27 Aug 2012 00:16:03 +0200 Subject: curl_multi_perform.3: extended/clarified --- docs/libcurl/curl_multi_perform.3 | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_perform.3 b/docs/libcurl/curl_multi_perform.3 index 96ebb34e3..304197b1a 100644 --- a/docs/libcurl/curl_multi_perform.3 +++ b/docs/libcurl/curl_multi_perform.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -28,21 +28,24 @@ curl_multi_perform - reads/writes available data from each easy handle CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles); .ad .SH DESCRIPTION -When the app thinks there's data available for the multi_handle, it should -call this function to read/write whatever there is to read or write right -now. curl_multi_perform() returns as soon as the reads/writes are done. This +This function handles transfers on all the added handles that need attention +in an non-blocking fashion. + +When an application has found out there's data available for the multi_handle +or a timeout has elapsed, the application should call this function to +read/write whatever there is to read or write right now etc. +curl_multi_perform() returns as soon as the reads/writes are done. This function does not require that there actually is any data available for reading or that data can be written, it can be called just in case. It will write the number of handles that still transfer data in the second argument's integer-pointer. -When you call curl_multi_perform() and the amount of \fIrunning_handles\fP is -changed from the previous call (or is less than the amount of easy handles -you've added to the multi handle), you know that there is one or more -transfers less "running". You can then call \fIcurl_multi_info_read(3)\fP to -get information about each individual completed transfer, and that returned -info includes CURLcode and more. If an added handle fails very quickly, it may -never be counted as a running_handle. +If the amount of \fIrunning_handles\fP is changed from the previous call (or +is less than the amount of easy handles you've added to the multi handle), you +know that there is one or more transfers less "running". You can then call +\fIcurl_multi_info_read(3)\fP to get information about each individual +completed transfer, and that returned info includes CURLcode and more. If an +added handle fails very quickly, it may never be counted as a running_handle. When \fIrunning_handles\fP is set to zero (0) on the return of this function, there is no longer any transfers in progress. @@ -61,12 +64,14 @@ need to wait for \&"action" and then call this function again. This function 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. +function returns \fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure +out how individual transfers did. .SH "TYPICAL USAGE" Most applications will use \fIcurl_multi_fdset(3)\fP to get the multi_handle's -file descriptors, then it'll wait for action on them using \fBselect(3)\fP and -as soon as one or more of them are ready, \fIcurl_multi_perform(3)\fP gets -called. +file descriptors, and \fIcurl_multi_timeout(3)\fP to get a suitable timeout +period, then it'll wait for action on the file descriptors using +\fBselect(3)\fP. As soon as one or more file descriptor is ready, +\fIcurl_multi_perform(3)\fP gets called. .SH "SEE ALSO" .BR curl_multi_cleanup "(3), " curl_multi_init "(3), " .BR curl_multi_fdset "(3), " curl_multi_info_read "(3), " -- cgit v1.2.1 From 4eec66e479a5a2938dc186b763fdcb12a39718ed Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 27 Aug 2012 23:49:08 +0200 Subject: libcurl-share.3: remove wrong info of what can be shared "Currently you can only share DNS and/or COOKIE data" is incorrect since also SSL sessions can be shared. Bug: http://curl.haxx.se/bug/view.cgi?id=3562261 Reported by: Joe Mason --- docs/libcurl/libcurl-share.3 | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/libcurl-share.3 b/docs/libcurl/libcurl-share.3 index fc624088e..583902152 100644 --- a/docs/libcurl/libcurl-share.3 +++ b/docs/libcurl/libcurl-share.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -41,8 +41,7 @@ You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle for a newly created one. You tell the shared object what data you want it to share by using -\fIcurl_share_setopt(3)\fP. Currently you can only share DNS and/or COOKIE -data. +\fIcurl_share_setopt(3)\fP. Since you can use this share from multiple threads, and libcurl has no internal thread synchronization, you must provide mutex callbacks if you're -- cgit v1.2.1 From 925707c0f8e75333e31de128858b3d5ca780f183 Mon Sep 17 00:00:00 2001 From: Sara Golemon Date: Mon, 27 Aug 2012 13:06:28 -0700 Subject: Manpage for curl_multi_wait(). --- docs/libcurl/Makefile.am | 8 ++--- docs/libcurl/curl_multi_wait.3 | 68 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+), 4 deletions(-) create mode 100644 docs/libcurl/curl_multi_wait.3 (limited to 'docs/libcurl') diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index 50f1a3b23..3114e2b3b 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -5,7 +5,7 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +# Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms @@ -38,7 +38,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 \ curl_easy_pause.3 curl_easy_recv.3 curl_easy_send.3 \ - curl_multi_socket_action.3 + curl_multi_socket_action.3 curl_multi_wait.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -58,7 +58,7 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_unescape.html curl_multi_setopt.html curl_multi_socket.html \ curl_multi_timeout.html curl_formget.html curl_multi_assign.html \ curl_easy_pause.html curl_easy_recv.html curl_easy_send.html \ - curl_multi_socket_action.html + curl_multi_socket_action.html curl_multi_wait.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_init.pdf curl_easy_perform.pdf curl_easy_setopt.pdf \ @@ -77,7 +77,7 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf \ curl_easy_escape.pdf curl_easy_unescape.pdf curl_multi_setopt.pdf \ curl_multi_socket.pdf curl_multi_timeout.pdf curl_formget.pdf \ curl_multi_assign.pdf curl_easy_pause.pdf curl_easy_recv.pdf \ - curl_easy_send.pdf curl_multi_socket_action.pdf + curl_easy_send.pdf curl_multi_socket_action.pdf curl_multi_wait.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 new file mode 100644 index 000000000..96b3c7e66 --- /dev/null +++ b/docs/libcurl/curl_multi_wait.3 @@ -0,0 +1,68 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH curl_multi_wait 3 "12 Jul 2012" "libcurl 7.28.0" "libcurl Manual" +.SH NAME +curl_multi_select - polls on all easy handles in a multi handle +.SH SYNOPSIS +.nf +#include + +CURLMcode curl_multi_wait(CURLM *multi_handle, + struct curl_waitfd extra_fds[], + unsigned int extra_nfds, + int timeout_ms); +.ad +.SH DESCRIPTION +This function polls on all file descriptors used by the curl easy handles +contained in the given multi handle set. It will block until activity is +detected on at least one of the handles or \fItimeout_ms\fP has passed. + +The calling application may pass additional curl_waitfd structures which are +similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call. + +This function is encouraged to be used instead of select(3) when using the +multi interface to allow applications to easier circumvent the common problem +with 1024 maximum file descriptors. +.SH curl_waitfd +.nf +struct curl_waitfd { + curl_socket_t fd; + short events; + short revents; +}; +.fi +.IP CURL_WAIT_POLLIN +Bit flag to curl_waitfd.events indicating the socket should poll on read +events such as new data received. +.IP CURL_WAIT_POLLPRI +Bit flag to curl_waitfd.events indicating the socket should poll on high +priority read events such as out of band data. +.IP CURL_WAIT_POLLOUT +Bit flag to curl_waitfd.events indicating the socket should poll on write +events such as the socket being clear to write without blocking. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. See +\fIlibcurl-errors(3)\fP +.SH AVAILABILITY +This function was added in libcurl 7.28.0 +.SH "SEE ALSO" +.BR curl_multi_fdset "(3), " curl_multi_perform "(3)" -- cgit v1.2.1 From ca84361e4b0d6b0f45a9a874d376cb598bc6803d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 1 Sep 2012 23:53:15 +0200 Subject: symbols-in-versions: new CURL_WAIT_* symbols --- docs/libcurl/symbols-in-versions | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl') diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 74e2958f9..1de1aceb7 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -699,4 +699,7 @@ CURL_VERSION_SPNEGO 7.10.8 CURL_VERSION_SSL 7.10 CURL_VERSION_SSPI 7.13.2 CURL_VERSION_TLSAUTH_SRP 7.21.4 +CURL_WAIT_POLLIN 7.28.0 +CURL_WAIT_POLLOUT 7.28.0 +CURL_WAIT_POLLPRI 7.28.0 CURL_WRITEFUNC_PAUSE 7.18.0 -- cgit v1.2.1 From b78944146a0670b74be00e189f468adfc5fca5b7 Mon Sep 17 00:00:00 2001 From: Sara Golemon Date: Sat, 15 Sep 2012 10:38:52 -0700 Subject: curl_multi_wait: Add parameter to return number of active sockets Minor change to recently introduced function. BC breaking, but since curl_multi_wait() doesn't exist in any releases that should be fine. --- docs/libcurl/curl_multi_wait.3 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 index 96b3c7e66..9250a77eb 100644 --- a/docs/libcurl/curl_multi_wait.3 +++ b/docs/libcurl/curl_multi_wait.3 @@ -29,7 +29,8 @@ curl_multi_select - polls on all easy handles in a multi handle CURLMcode curl_multi_wait(CURLM *multi_handle, struct curl_waitfd extra_fds[], unsigned int extra_nfds, - int timeout_ms); + int timeout_ms, + int *ret); .ad .SH DESCRIPTION This function polls on all file descriptors used by the curl easy handles @@ -39,6 +40,9 @@ detected on at least one of the handles or \fItimeout_ms\fP has passed. The calling application may pass additional curl_waitfd structures which are similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call. +On completion, if \fIret\fI is supplied, it will be populated with the +number of file descriptors on which interesting events occured. + This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem with 1024 maximum file descriptors. -- cgit v1.2.1 From 211605f0c57e12dc7199a5972c8c720e7f6300d7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Oct 2012 14:32:15 +0200 Subject: curl_multi_wait.3: renamed the last argument variable for clarity --- docs/libcurl/curl_multi_wait.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 index 9250a77eb..e91c360bf 100644 --- a/docs/libcurl/curl_multi_wait.3 +++ b/docs/libcurl/curl_multi_wait.3 @@ -30,7 +30,7 @@ CURLMcode curl_multi_wait(CURLM *multi_handle, struct curl_waitfd extra_fds[], unsigned int extra_nfds, int timeout_ms, - int *ret); + int *numfds); .ad .SH DESCRIPTION This function polls on all file descriptors used by the curl easy handles @@ -40,7 +40,7 @@ detected on at least one of the handles or \fItimeout_ms\fP has passed. The calling application may pass additional curl_waitfd structures which are similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call. -On completion, if \fIret\fI is supplied, it will be populated with the +On completion, if \fInumfds\fI is supplied, it will be populated with the number of file descriptors on which interesting events occured. This function is encouraged to be used instead of select(3) when using the -- cgit v1.2.1 From 974d5d5921fcabf8958bf130dd8faf25008227fa Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Oct 2012 14:35:25 +0200 Subject: curl_multi_wait.3: fix the name of the man page --- docs/libcurl/curl_multi_wait.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 index e91c360bf..100d69de6 100644 --- a/docs/libcurl/curl_multi_wait.3 +++ b/docs/libcurl/curl_multi_wait.3 @@ -21,7 +21,7 @@ .\" ************************************************************************** .TH curl_multi_wait 3 "12 Jul 2012" "libcurl 7.28.0" "libcurl Manual" .SH NAME -curl_multi_select - polls on all easy handles in a multi handle +curl_multi_wait - polls on all easy handles in a multi handle .SH SYNOPSIS .nf #include -- cgit v1.2.1 From 542802af231d25d97cc03d0d67474fb8ace2f379 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 8 Oct 2012 16:31:42 +0200 Subject: curl_multi_wait.3: style formatting mistake --- docs/libcurl/curl_multi_wait.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 index 100d69de6..ad97d47c5 100644 --- a/docs/libcurl/curl_multi_wait.3 +++ b/docs/libcurl/curl_multi_wait.3 @@ -40,7 +40,7 @@ detected on at least one of the handles or \fItimeout_ms\fP has passed. The calling application may pass additional curl_waitfd structures which are similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call. -On completion, if \fInumfds\fI is supplied, it will be populated with the +On completion, if \fInumfds\fP is supplied, it will be populated with the number of file descriptors on which interesting events occured. This function is encouraged to be used instead of select(3) when using the -- cgit v1.2.1 From 8373ca3641ce793a868377600fb5fd7b8e8bf95a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 9 Oct 2012 22:19:49 +0200 Subject: curl_multi_wait: no wait if no descriptors to wait for This is a minor change in behavior after having been pointed out by Mark Tully and discussed on the list. Initially this case would internally call poll() with no sockets and a timeout which would equal a sleep for that specified time. Bug: http://curl.haxx.se/mail/lib-2012-10/0076.html Reported by: Mark Tully --- docs/libcurl/curl_multi_wait.3 | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_wait.3 b/docs/libcurl/curl_multi_wait.3 index ad97d47c5..b14760bf3 100644 --- a/docs/libcurl/curl_multi_wait.3 +++ b/docs/libcurl/curl_multi_wait.3 @@ -43,6 +43,9 @@ similar to \fIpoll(2)\fP's pollfd structure to be waited on in the same call. On completion, if \fInumfds\fP is supplied, it will be populated with the number of file descriptors on which interesting events occured. +If no extra file descriptors are provided and libcurl has no file descriptor +to offer to wait for, this function will return immediately. + This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem with 1024 maximum file descriptors. @@ -67,6 +70,6 @@ events such as the socket being clear to write without blocking. CURLMcode type, general libcurl multi interface error code. See \fIlibcurl-errors(3)\fP .SH AVAILABILITY -This function was added in libcurl 7.28.0 +This function was added in libcurl 7.28.0. .SH "SEE ALSO" .BR curl_multi_fdset "(3), " curl_multi_perform "(3)" -- cgit v1.2.1 From da82f59b697310229ccdf66104d5d65a44dfab98 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 27 Oct 2012 12:31:39 +0200 Subject: CURLOPT_SSL_VERIFYHOST: stop supporting the 1 value After a research team wrote a document[1] that found several live source codes out there in the wild that misused the CURLOPT_SSL_VERIFYHOST option thinking it was a boolean, this change now bans 1 as a value and will make libcurl return error for it. 1 was never a sensible value to use in production but was introduced back in the days to help debugging. It was always documented clearly this way. 1 was never supported by all SSL backends in libcurl, so this cleanup makes the treatment of it unified. The report's list of mistakes for this option were all PHP code and while there's a binding layer between libcurl and PHP, the PHP team has decided that they have an as thin layer as possible on top of libcurl so they will not alter or specifically filter a 'TRUE' value for this particular option. I sympathize with that position. [1] = http://daniel.haxx.se/blog/2012/10/25/libcurl-claimed-to-be-dangerous/ --- docs/libcurl/curl_easy_setopt.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 3b0dc6c9d..a388c2220 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2323,8 +2323,9 @@ Curl considers the server the intended one when the Common Name field or a Subject Alternate Name field in the certificate matches the host name in the URL to which you told Curl to connect. -When the value is 1, the certificate must contain a Common Name field, but it -doesn't matter what name it says. (This is not ordinarily a useful setting). +When the value is 1, libcurl will return a failure. It was previously (in +7.28.0 and earlier) a debug option of some sorts, but it is no longer +supported due to frequently leading to programmer mistakes. When the value is 0, the connection succeeds regardless of the names in the certificate. -- cgit v1.2.1 From 91dc73ef445c5d382a72db21468289ae8a9e80e3 Mon Sep 17 00:00:00 2001 From: Steve Holme Date: Fri, 23 Nov 2012 13:43:53 +0000 Subject: DOCS: Updated CURLOPT_CONNECT_ONLY to reflect usage in other protocols --- docs/libcurl/curl_easy_setopt.3 | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index a388c2220..9d712a45e 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -2093,11 +2093,12 @@ Resolve to IPv6 addresses. .IP CURLOPT_CONNECT_ONLY Pass a long. If the parameter equals 1, it tells the library to perform all the required proxy authentication and connection setup, but no data transfer. -This option is useful only on HTTP URLs. +This option is implemented for HTTP, SMTP and POP3. -This option is useful with the \fICURLINFO_LASTSOCKET\fP option to -\fIcurl_easy_getinfo(3)\fP. The library can set up the connection and then the -application can obtain the most recently used socket for special data +The option can be used to simply test a connection to a server, but is more +useful when used with the \fICURLINFO_LASTSOCKET\fP option to +\fIcurl_easy_getinfo(3)\fP as the library can set up the connection and then +the application can obtain the most recently used socket for special data transfers. (Added in 7.15.2) .IP CURLOPT_USE_SSL Pass a long using one of the values from below, to make libcurl use your -- cgit v1.2.1