docs: edited lots of libcurl docs for clarity

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" *

.\" * This software is licensed as described in the file COPYING, which

.\" * you should have received as part of this distribution. The terms

.\"

.TH curl_easy_cleanup 3 "22 aug 2007" "libcurl 7.17.0" "libcurl Manual"

.SH NAME

curl_easy_cleanup - End a libcurl easy session

curl_easy_cleanup - End a libcurl easy handle

.SH SYNOPSIS

.B #include <curl/curl.h>

.BI "void curl_easy_cleanup(CURL *" handle ");"

.SH DESCRIPTION

This function must be the last function to call for an easy session. It is the

opposite of the \fIcurl_easy_init(3)\fP function and must be called with the

same \fIhandle\fP as input that the curl_easy_init call returned.

same \fIhandle\fP as input that a \fIcurl_easy_init(3)\fP call returned.

This will effectively close all connections this handle has used and possibly

has kept open until now. Don't call this function if you intend to transfer

more files.

This might close all connections this handle has used and possibly has kept

open until now - unless it was attached to a multi handle while doing the

transfers. Don't call this function if you intend to transfer more files,

re-using handles is a key to good performance with libcurl.

Occasionally you may get your progress callback or header callback called from

within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using

connection and the protocol is of a kind that requires a command/response

sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP.

Any uses of the \fBhandle\fP after this function has been called and have

returned, are illegal. This kills the handle and all memory associated with

it!

Any use of the \fBhandle\fP after this function has been called and have

returned, is illegal. \fIcurl_easy_cleanup(3)\fP kills the handle and all

memory associated with it!

With libcurl versions prior to 7.17.: when you've called this, you can safely

remove all the strings you've previously told libcurl to use, as it won't use

them anymore now.

For libcurl versions before 7.17,: after you've called this function, you can

safely remove all the strings you've previously told libcurl to use, as it

won't use them anymore now.

.SH RETURN VALUE

None

.SH "SEE ALSO"

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" *

.\" * This software is licensed as described in the file COPYING, which

.\" * you should have received as part of this distribution. The terms

.B #include <curl/curl.h>

.BI "CURL *curl_easy_init( );"

.SH DESCRIPTION

This function must be the first function to call, and it returns a CURL easy

handle that you must use as input to other easy-functions. curl_easy_init

initializes curl and this call \fBMUST\fP have a corresponding call to

handle that you must use as input to other functions in the easy

interface. This call \fBMUST\fP have a corresponding call to

\fIcurl_easy_cleanup(3)\fP when the operation is complete.

If you did not already call \fIcurl_global_init(3)\fP,

\fIcurl_easy_init(3)\fP does it automatically.

This may be lethal in multi-threaded cases, since \fIcurl_global_init(3)\fP is

not thread-safe, and it may result in resource problems because there is

no corresponding cleanup.

You are strongly advised to not allow this automatic behaviour, by

calling \fIcurl_global_init(3)\fP yourself properly.

See the description in \fBlibcurl\fP(3) of global environment

requirements for details of how to use this function.

If you did not already call \fIcurl_global_init(3)\fP, \fIcurl_easy_init(3)\fP

does it automatically.  This may be lethal in multi-threaded cases, since

\fIcurl_global_init(3)\fP is not thread-safe, and it may result in resource

problems because there is no corresponding cleanup.

You are strongly advised to not allow this automatic behaviour, by calling

\fIcurl_global_init(3)\fP yourself properly.  See the description in

\fBlibcurl\fP(3) of global environment requirements for details of how to use

this function.

.SH RETURN VALUE

If this function returns NULL, something went wrong and you cannot use the

other curl functions.

CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);

.SH DESCRIPTION

curl_easy_setopt() is used to tell libcurl how to behave. By using the

appropriate options to \fIcurl_easy_setopt\fP, you can change libcurl's

behavior.  All options are set with the \fIoption\fP followed by a

\fIparameter\fP. That parameter can be a \fBlong\fP, a \fBfunction pointer\fP,

an \fBobject pointer\fP or a \fBcurl_off_t\fP, depending on what the specific

option expects. Read this manual carefully as bad input values may cause

libcurl to behave badly!  You can only set one option in each function call. A

typical application uses many curl_easy_setopt() calls in the setup phase.

\fIcurl_easy_setopt(3)\fP is used to tell libcurl how to behave. By setting

the appropriate options, the application can change libcurl's behavior.  All

options are set with an \fIoption\fP followed by a \fIparameter\fP. That

parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject

pointer\fP or a \fBcurl_off_t\fP, depending on what the specific option

expects. Read this manual carefully as bad input values may cause libcurl to

behave badly!  You can only set one option in each function call. A typical

application uses many \fIcurl_easy_setopt(3)\fP calls in the setup phase.

Options set with this function call are valid for all forthcoming transfers

performed using this \fIhandle\fP.  The options are not in any way reset

Strings passed to libcurl as 'char *' arguments, are copied by the library;

thus the string storage associated to the pointer argument may be overwritten

after curl_easy_setopt() returns. The only exception to this rule is really

\fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies the string

after \fIcurl_easy_setopt(3)\fP returns. The only exception to this rule is

really \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies the string

\fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you need to

read up on.

the option was disabled at compile-time, it will return

\fICURLE_NOT_BUILT_IN\fP.

.SH "SEE ALSO"

.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3)"

.BR curl_easy_init "(3), " curl_easy_cleanup "(3), " curl_easy_reset "(3), "

.BR curl_multi_setopt "(3), "

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" *

.\" * This software is licensed as described in the file COPYING, which

.\" * you should have received as part of this distribution. The terms

const char *curl_easy_strerror(CURLcode errornum);

.SH DESCRIPTION

The curl_easy_strerror() function returns a string describing the CURLcode

error code passed in the argument \fIerrornum\fP.

The \fIcurl_easy_strerror(3)\fP function returns a string describing the

CURLcode error code passed in the argument \fIerrornum\fP.

Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more

specific error descriptions generated at run-time.

.SH AVAILABILITY

This function was added in libcurl 7.12.0

.SH RETURN VALUE

.ad

.SH DESCRIPTION

curl_free reclaims memory that has been obtained through a libcurl call.  Use

curl_free() instead of free() to avoid anomalies that can result from

\fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from

differences in memory management between your application and libcurl.

.SH "SEE ALSO"

.BR curl_unescape "(3)"

.BR curl_easy_unescape "(3), " curl_easy_escape "(3) "