aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2007-08-01 21:20:01 +0000
committerDaniel Stenberg <daniel@haxx.se>2007-08-01 21:20:01 +0000
commit50c10aa5bf545eedfdbe561116656b6ec12654cd (patch)
treeae3de37fd3877d42ffd4c0cdcd03c4530e68a326 /docs
parent006878686cfd3faa9eca92fc8fe60cb8f8073a59 (diff)
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.
Diffstat (limited to 'docs')
-rw-r--r--docs/libcurl/curl_easy_getinfo.34
-rw-r--r--docs/libcurl/curl_easy_setopt.322
2 files changed, 18 insertions, 8 deletions
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)