-.\" You can view this file with:
-.\" nroff -man [file]
-.\" $Id$
-.\"
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * Project ___| | | | _ \| |
+.\" * / __| | | | |_) | |
+.\" * | (__| |_| | _ <| |___
+.\" * \___|\___/|_| \_\_____|
+.\" *
+.\" * 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
+.\" * are also available at http://curl.haxx.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
.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 ");
+.BI "CURLcode curl_easy_perform(CURL *" easy_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.
+Invoke this function after \fIcurl_easy_init(3)\fP and all the
+\fIcurl_easy_setopt(3)\fP calls are made, and will perform the transfer as
+described in the options. It must be called with the same \fBeasy_handle\fP as
+input as the \fIcurl_easy_init(3)\fP 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.
+\fIcurl_easy_perform(3)\fP performs the entire request in a blocking manner
+and returns when done, or if it failed. For non-blocking behavior, see
+\fIcurl_multi_perform(3)\fP.
+
+You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the
+same \fBeasy_handle\fP. 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 \fIcurl_easy_setopt(3)\fP 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.
+same \fBeasy_handle\fP. Let the function return first before invoking it
+another time. If you want parallel transfers, you must use several curl
+easy_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.
+While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by
+\fIcurl_easy_perform(3)\fP.
.SH RETURN VALUE
-0 means everything was ok, non-zero means an error occurred as
+CURLE_OK (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.
+defines - see \fIlibcurl-errors(3)\fP. If the \fBCURLOPT_ERRORBUFFER(3)\fP was
+set with \fIcurl_easy_setopt(3)\fP 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!
+.BR curl_multi_add_handle "(3), " curl_multi_perform "(3), "
+.BR libcurl-errors "(3), "
+
projects / platform / upstream / curl.git / blobdiff