From 50c10aa5bf545eedfdbe561116656b6ec12654cd Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 1 Aug 2007 21:20:01 +0000 Subject: Patrick Monnerat and I modified libcurl so that now it *copies* all strings passed to it with curl_easy_setopt()! Previously it has always just refered to the data, forcing the user to keep the data around until libcurl is done with it. That is now history and libcurl will instead clone the given strings and keep private copies. --- docs/libcurl/curl_easy_getinfo.3 | 4 +++- docs/libcurl/curl_easy_setopt.3 | 22 +++++++++++++++------- 2 files changed, 18 insertions(+), 8 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_getinfo.3 b/docs/libcurl/curl_easy_getinfo.3 index fe13f07c9..95455e3a1 100644 --- a/docs/libcurl/curl_easy_getinfo.3 +++ b/docs/libcurl/curl_easy_getinfo.3 @@ -133,7 +133,9 @@ protocol used doesn't support this. .IP CURLINFO_PRIVATE Pass a pointer to a 'char *' to receive the pointer to the private data associated with the curl handle (set with the CURLOPT_PRIVATE option to -\fIcurl_easy_setopt(3)\fP). (Added in 7.10.3) +\fIcurl_easy_setopt(3)\fP). Please note that for internal reasons, the +value is returned as a 'char *', although effectively being a 'void *'. +(Added in 7.10.3) .IP CURLINFO_HTTPAUTH_AVAIL Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available. The meaning of the bits is explained in the diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 63b53f7c4..016bb9181 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -21,7 +21,7 @@ .\" * $Id$ .\" ************************************************************************** .\" -.TH curl_easy_setopt 3 "22 Feb 2007" "libcurl 7.16.2" "libcurl Manual" +.TH curl_easy_setopt 3 "1 Aug 2007" "libcurl 7.17.0" "libcurl Manual" .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS @@ -44,11 +44,13 @@ between transfers, so if you want subsequent transfers with different options, you must change them between the transfers. You can optionally reset all options back to internal default with \fIcurl_easy_reset(3)\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. libcurl -will need them until you call \fIcurl_easy_cleanup(3)\fP or you set the same -option again to use a different pointer. +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. Exceptions to this rule are described in +the option details below. + +NOTE: before 7.17.0 strings were not copied. Instead the user was forced keep +them available until libcurl no longer needed them. The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. @@ -330,6 +332,12 @@ system. 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 \fIcurl_easy_perform\fP. The buffer must be at least CURL_ERROR_SIZE big. +Although this argument is a 'char *', it does not describe an input string. +Therefore the (probably undefined) contents of the buffer is NOT copied +by the library. You should keep the associated storage available until +libcurl no longer needs it. Failing to do so will cause very odd behavior +or even crashes. libcurl will need it until you call \fIcurl_easy_cleanup(3)\fP +or you set the same option again to use a different pointer. Use \fICURLOPT_VERBOSE\fP and \fICURLOPT_DEBUGFUNCTION\fP to better debug/trace why errors happen. @@ -1397,7 +1405,7 @@ If the file is password-protected, set the password with \fICURLOPT_SSLKEYPASSWD (Added in 7.16.1) .SH OTHER OPTIONS .IP CURLOPT_PRIVATE -Pass a char * as parameter, pointing to data that should be associated with +Pass a void * as parameter, pointing to data that should be associated with this curl handle. The pointer can subsequently be retrieved using \fIcurl_easy_getinfo(3)\fP with the CURLINFO_PRIVATE option. libcurl itself does nothing with this data. (Added in 7.10.3) -- cgit v1.2.3