moparisthebest/curl
1
0
Fork 0
mirror of https://github.com/moparisthebest/curl synced 2024-12-21 23:58:49 -05:00
Code Issues Releases Wiki Activity

ripped out from ../ and put in its own directory now

Browse Source
This commit is contained in:
Daniel Stenberg 2002-03-04 10:09:48 +00:00
parent 34f9ab1046
commit 01f04b9a41
31 changed files with 1928 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/libcurl/Makefile.am Normal file
View File

@ -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)

29
docs/libcurl/curl_easy_cleanup.3 Normal file
View File

@ -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!

37
docs/libcurl/curl_easy_duphandle.3 Normal file
View File

@ -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!

114
docs/libcurl/curl_easy_getinfo.3 Normal file
View File

@ -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!

26
docs/libcurl/curl_easy_init.3 Normal file
View File

@ -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!

46
docs/libcurl/curl_easy_perform.3 Normal file
View File

@ -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!

627
docs/libcurl/curl_easy_setopt.3 Normal file
View File

@ -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.

28
docs/libcurl/curl_escape.3 Normal file
View File

@ -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

165
docs/libcurl/curl_formadd.3 Normal file
View File

@ -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!

27
docs/libcurl/curl_formfree.3 Normal file
View File

@ -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.

18
docs/libcurl/curl_formparse.3 Normal file
View File

@ -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.

80
docs/libcurl/curl_getdate.3 Normal file
View File

@ -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!

32
docs/libcurl/curl_getenv.3 Normal file
View File

@ -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!

27
docs/libcurl/curl_global_cleanup.3 Normal file
View File

@ -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?

49
docs/libcurl/curl_global_init.3 Normal file
View File

@ -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.

88
docs/libcurl/curl_mprintf.3 Normal file
View File

@ -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) "

17
docs/libcurl/curl_multi_add_handle.3 Normal file
View File

@ -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)"

18
docs/libcurl/curl_multi_cleanup.3 Normal file
View File

@ -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)"

23
docs/libcurl/curl_multi_fdset.3 Normal file
View File

@ -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)"

35
docs/libcurl/curl_multi_info_read.3 Normal file
View File

@ -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)"

21
docs/libcurl/curl_multi_init.3 Normal file
View File

@ -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!

30
docs/libcurl/curl_multi_perform.3 Normal file
View File

@ -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)"

17
docs/libcurl/curl_multi_remove_handle.3 Normal file
View File

@ -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)"

29
docs/libcurl/curl_slist_append.3 Normal file
View File

@ -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!

22
docs/libcurl/curl_slist_free_all.3 Normal file
View File

@ -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!

30
docs/libcurl/curl_strequal.3 Normal file
View File

@ -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)"

1
docs/libcurl/curl_strnequal.3 Normal file
View File

@ -0,0 +1 @@
.so curl_strequal.3

27
docs/libcurl/curl_unescape.3 Normal file
View File

@ -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

27
docs/libcurl/curl_version.3 Normal file
View File

@ -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!

38
docs/libcurl/index.html Normal file
View File

@ -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>

132
docs/libcurl/libcurl.3 Normal file
View File

@ -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.