From 220caed248ec990c137a9f197710eddad4a608eb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 9 Feb 2004 09:07:26 +0000 Subject: [PATCH] Dominick Meglio's added share interface documentation --- docs/libcurl/curl_share_cleanup.3 | 6 ++-- docs/libcurl/curl_share_init.3 | 4 +-- docs/libcurl/curl_share_setopt.3 | 47 +++++++++++++++++++------------ docs/libcurl/libcurl-errors.3 | 19 +++++++++++-- 4 files changed, 51 insertions(+), 25 deletions(-) diff --git a/docs/libcurl/curl_share_cleanup.3 b/docs/libcurl/curl_share_cleanup.3 index 2510213eb..b668d072f 100644 --- a/docs/libcurl/curl_share_cleanup.3 +++ b/docs/libcurl/curl_share_cleanup.3 @@ -13,7 +13,9 @@ This function deletes a shared object. The share handle cannot be used anymore when this function has been called. .SH RETURN VALUE -If this function returns non-zero, the object was not properly deleted and it -still remains! +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP +man page for the full list with descriptions. If an error occurs, then the +share object will not be deleted. .SH "SEE ALSO" .BR curl_share_init "(3), " curl_share_setopt "(3)" diff --git a/docs/libcurl/curl_share_init.3 b/docs/libcurl/curl_share_init.3 index 2f6581363..35fd5a1c9 100644 --- a/docs/libcurl/curl_share_init.3 +++ b/docs/libcurl/curl_share_init.3 @@ -14,8 +14,8 @@ share-functions, sometimes refered to as a share handle on some places in the documentation. This init call MUST have a corresponding call to \fIcurl_share_cleanup\fP when all operations using the share are complete. .SH RETURN VALUE -If this function returns NULL, something went wrong and you got no share -object to use. +If this function returns NULL, something went wrong (out of memory, etc.) +and therefore the share object was not created. .SH "SEE ALSO" .BR curl_share_cleanup "(3), " curl_share_setopt "(3)" diff --git a/docs/libcurl/curl_share_setopt.3 b/docs/libcurl/curl_share_setopt.3 index 583c14645..858b41cc9 100644 --- a/docs/libcurl/curl_share_setopt.3 +++ b/docs/libcurl/curl_share_setopt.3 @@ -11,8 +11,7 @@ CURLSHcode curl_share_setopt(CURLSH *share, CURLSHoption option, parameter); .SH DESCRIPTION Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP. .SH OPTIONS -.TP 0.4i -.B CURLSHOPT_LOCKFUNC +.IP CURLSHOPT_LOCKFUNC The \fIparameter\fP must be a pointer to a function matching the following prototype: @@ -24,23 +23,35 @@ only one lock is given at any time for each kind of data. \fIaccess\fP defines what access type libcurl wants, shared or single. -\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDAT\fP. +\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP. +.IP CURLSHOPT_UNLOCKFUNC +The \fIparameter\fP must be a pointer to a function matching the following +prototype: -.TP -.B CURLSHOPT_UNLOCKFUNC -hej -.TP -.B CURLSHOPT_SHARE -hej -.TP -.B CURLSHOPT_UNSHARE -hej -.TP -.B CURLSHOPT_USERDATA -hej -.PP +void unlock_function(CURL *handle, curl_lock_data data, void *userptr); + +\fIdata\fP defines what data libcurl wants to unlock, and you must make sure +that only one lick is given at any time for each kind of data. + +\fIuserptr\fP is the pointer you set with \fICURLSHOPT_USERDATA\fP. +.IP CURLSHOPT_SHARE +The \fIparameter\fP specifies a type of data that should be shared. This may +be set to one of the values described below. +.IP CURL_LOCK_DATA_COOKIE +COOKIE data will be shared across the easy handles using this shared object. +.IP CURL_LOCK_DATA_DNS +Cached DNS hosts will be shared across the easy handles using this shared +object. +.IP CURLSHOPT_UNSHARE +This option does the opposite of \fICURLSHOPT_SHARE\fP. It specifies that +the specified \fIparameter\fP will no longer be shared. Valid values are +the same as those for \fICURLSHOPT_SHARE\fP. +.IP CURLSHOPT_USERDATA +The \fIparameter\fP allows you to specify a pointer to data that will passed +to the lock_function and unlock_function each time it is called. .SH RETURN VALUE -If this function returns non-zero, something was wrong! - +CURLSHE_OK (zero) means that the option was set properly, non-zero means an +error occurred as \fI\fP defines. See the \fIlibcurl-errors.3\fP +man page for the full list with descriptions. .SH "SEE ALSO" .BR curl_share_cleanup "(3), " curl_share_init "(3)" diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index eae506558..9ca61752f 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -15,7 +15,6 @@ human readable error string that may offer more details about the error cause than just the error code does. CURLcode is one of the following: -.RS 0 .IP "CURLE_OK (0)" All fine. Proceed as usual. .IP "CURLE_UNSUPPORTED_PROTOCOL (1)" @@ -183,8 +182,22 @@ Unrecognized transfer encoding Invalid LDAP URL .IP "CURLE_FILESIZE_EXCEEDED (63)" Maximum file size exceeded -.RE - .SH "CURLMcode" This is the generic return code used by functions in the libcurl multi interface. + +This is left to be documented. +.SH "CURLSHcode" +The "share" interface will return a CURLSHcode to indicate when an +error has occurred. + +CURLSHcode is one of the following: +.IP "CURLSHE_OK (0)" +All fine. Proceed as usual. +.IP "CURLSHE_BAD_OPTION (1)" +An invalid option was passed to the function. +.IP "CURLSHE_IN_USE (2)" +The share object is currently in use. +.IP "CURLSHE_INVALID (3)" +An invalid share object was passed to the function. +