moved to the new libcurl/ directory

.\" 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!

.\" 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!

.\" 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!

.\" 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!

.\" 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!