| 1 |
.\" ************************************************************************** |
| 2 |
.\" * _ _ ____ _ |
| 3 |
.\" * Project ___| | | | _ \| | |
| 4 |
.\" * / __| | | | |_) | | |
| 5 |
.\" * | (__| |_| | _ <| |___ |
| 6 |
.\" * \___|\___/|_| \_\_____| |
| 7 |
.\" * |
| 8 |
.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <[email protected]>, et al. |
| 9 |
.\" * |
| 10 |
.\" * This software is licensed as described in the file COPYING, which |
| 11 |
.\" * you should have received as part of this distribution. The terms |
| 12 |
.\" * are also available at https://curl.haxx.se/docs/copyright.html. |
| 13 |
.\" * |
| 14 |
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| 15 |
.\" * copies of the Software, and permit persons to whom the Software is |
| 16 |
.\" * furnished to do so, under the terms of the COPYING file. |
| 17 |
.\" * |
| 18 |
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| 19 |
.\" * KIND, either express or implied. |
| 20 |
.\" * |
| 21 |
.\" ************************************************************************** |
| 22 |
.TH libcurl 3 "19 Sep 2014" "libcurl" "libcurl easy interface" |
| 23 |
.SH NAME |
| 24 |
libcurl-easy \- easy interface overview |
| 25 |
.SH DESCRIPTION |
| 26 |
When using libcurl's "easy" interface you init your session and get a handle |
| 27 |
(often referred to as an "easy handle"), which you use as input to the easy |
| 28 |
interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle. |
| 29 |
|
| 30 |
You continue by setting all the options you want in the upcoming transfer, the |
| 31 |
most important among them is the URL itself (you can't transfer anything |
| 32 |
without a specified URL as you may have figured out yourself). You might want |
| 33 |
to set some callbacks as well that will be called from the library when data |
| 34 |
is available etc. \fIcurl_easy_setopt(3)\fP is used for all this. |
| 35 |
|
| 36 |
\fICURLOPT_URL(3)\fP is only option you really must set, as otherwise there |
| 37 |
can be no transfer. Another commonly used option is \fICURLOPT_VERBOSE(3)\fP |
| 38 |
that will help you see what libcurl is doing under the hood, very useful when |
| 39 |
debugging for example. The \fIcurl_easy_setopt(3)\fP man page has a full index |
| 40 |
of the over 200 available options. |
| 41 |
|
| 42 |
If you at any point would like to blank all previously set options for a |
| 43 |
single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also |
| 44 |
make a clone of an easy handle (with all its set options) using |
| 45 |
\fIcurl_easy_duphandle(3)\fP. |
| 46 |
|
| 47 |
When all is setup, you tell libcurl to perform the transfer using |
| 48 |
\fIcurl_easy_perform(3)\fP. It will then do the entire operation and won't |
| 49 |
return until it is done (successfully or not). |
| 50 |
|
| 51 |
After the transfer has been made, you can set new options and make another |
| 52 |
transfer, or if you're done, cleanup the session by calling |
| 53 |
\fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you don't |
| 54 |
cleanup immediately, but instead run ahead and perform other transfers using |
| 55 |
the same easy handle. |
| 56 |
.SH "SEE ALSO" |
| 57 |
.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_setopt "(3), " |
| 58 |
.BR libcurl-errors "(3), " libcurl-multi "(3), " libcurl "(3) " |