diff options
Diffstat (limited to 'docs/libcurl')
31 files changed, 1928 insertions, 0 deletions
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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +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 <curl/curl.h> + +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<curl/curl.h>\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<curl/curl.h>\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 <curl/curl.h> +.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 <curl/curl.h> +.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[] = "<HTML>test buffer</HTML>"; + 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, "<HTML></HTML>", + 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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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 <smb@research.att.com> while at the +University of North Carolina at Chapel Hill. Later tweaked by a couple of +people on Usenet. Completely overhauled by Rich $alz <rsalz@bbn.com> and Jim +Berets <jberets@bbn.com> 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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/mprintf.h> +.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 <curl/mprintf.h> 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 <curl/curl.h> + +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 <curl/curl.h> +.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 <curl/curl.h> + +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 <curl/curl.h> + +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 <curl/curl.h> +.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 <curl/curl.h> + +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 <curl/curl.h> + +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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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 <curl/curl.h> +.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> +<HEAD> +<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> +<TITLE>Index to Curl documentation</TITLE> +</HEAD> + +<BODY> +<H1 ALIGN="CENTER">Index to Curl documentation</H1> + +<H2>Programs</H2> +<P><A HREF="curl-config.html">curl-config.html</A> +<P><A HREF="curl.html">curl.html</A> + +<H2>Library routines</H2> +<P><A HREF="libcurl.html">libcurl.html</A> +<P><A HREF="curl_easy_cleanup.html">curl_easy_cleanup.html</A> +<P><A HREF="curl_easy_duphandle.html">curl_easy_duphandle.html</A> +<P><A HREF="curl_easy_getinfo.html">curl_easy_getinfo.html</A> +<P><A HREF="curl_easy_init.html">curl_easy_init.html</A> +<P><A HREF="curl_easy_perform.html">curl_easy_perform.html</A> +<P><A HREF="curl_easy_setopt.html">curl_easy_setopt.html</A> +<P><A HREF="curl_escape.html">curl_escape.html</A> +<P><A HREF="curl_formadd.html">curl_formadd.html</A> +<P><A HREF="curl_formfree.html">curl_formfree.html</A> +<P><A HREF="curl_formparse.html">curl_formparse.html</A> +<P><A HREF="curl_getdate.html">curl_getdate.html</A> +<P><A HREF="curl_getenv.html">curl_getenv.html</A> +<P><A HREF="curl_global_cleanup.html">curl_global_cleanup.html</A> +<P><A HREF="curl_global_init.html">curl_global_init.html</A> +<P><A HREF="curl_mprintf.html">curl_mprintf.html</A> +<P><A HREF="curl_slist_append.html">curl_slist_append.html</A> +<P><A HREF="curl_slist_free_all.html">curl_slist_free_all.html</A> +<P><A HREF="curl_strequal.html">curl_strequal.html</A> +<P><A HREF="curl_strnequal.html">curl_strnequal.html</A> +<P><A HREF="curl_unescape.html">curl_unescape.html</A> +<P><A HREF="curl_version.html">curl_version.html</A> +</BODY> +</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. + |