diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libcurl/Makefile.am | 10 | ||||
| -rw-r--r-- | docs/libcurl/curl_global_init.3 | 34 | ||||
| -rw-r--r-- | docs/libcurl/curl_multi_assign.3 | 44 | ||||
| -rw-r--r-- | docs/libcurl/curl_multi_setopt.3 | 5 | ||||
| -rw-r--r-- | docs/libcurl/curl_multi_socket.3 | 48 |
5 files changed, 102 insertions, 39 deletions
diff --git a/docs/libcurl/Makefile.am b/docs/libcurl/Makefile.am index e43a0b67c..ea96cea1d 100644 --- a/docs/libcurl/Makefile.am +++ b/docs/libcurl/Makefile.am @@ -18,7 +18,7 @@ man_MANS = curl_easy_cleanup.3 curl_easy_getinfo.3 curl_easy_init.3 \ curl_multi_strerror.3 curl_share_strerror.3 curl_global_init_mem.3 \ libcurl-tutorial.3 curl_easy_reset.3 curl_easy_escape.3 \ curl_easy_unescape.3 curl_multi_setopt.3 curl_multi_socket.3 \ - curl_multi_timeout.3 curl_formget.3 + curl_multi_timeout.3 curl_formget.3 curl_multi_assign.3 HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ curl_easy_init.html curl_easy_perform.html curl_easy_setopt.html \ @@ -35,8 +35,8 @@ HTMLPAGES = curl_easy_cleanup.html curl_easy_getinfo.html \ libcurl-errors.html curl_easy_strerror.html curl_multi_strerror.html \ curl_share_strerror.html curl_global_init_mem.html libcurl-tutorial.html \ curl_easy_reset.html curl_easy_escape.html curl_easy_unescape.html \ - curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \ - curl_formget.html + curl_multi_setopt.html curl_multi_socket.html curl_multi_timeout.html \ + curl_formget.html curl_multi_assign.html PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ curl_easy_perform.pdf curl_easy_setopt.pdf curl_easy_duphandle.pdf \ @@ -52,8 +52,8 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf curl_easy_init.pdf \ libcurl-errors.pdf curl_easy_strerror.pdf curl_multi_strerror.pdf \ curl_share_strerror.pdf curl_global_init_mem.pdf libcurl-tutorial.pdf \ curl_easy_reset.pdf curl_easy_escape.pdf curl_easy_unescape.pdf \ - curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \ - curl_formget.pdf + curl_multi_setopt.pdf curl_multi_socket.pdf curl_multi_timeout.pdf \ + curl_formget.pdf curl_multi_assign.pdf CLEANFILES = $(HTMLPAGES) $(PDFPAGES) diff --git a/docs/libcurl/curl_global_init.3 b/docs/libcurl/curl_global_init.3 index 0729ef787..ba15ad4e0 100644 --- a/docs/libcurl/curl_global_init.3 +++ b/docs/libcurl/curl_global_init.3 @@ -11,30 +11,30 @@ curl_global_init - Global libcurl initialisation .BI "CURLcode curl_global_init(long " flags ");" .ad .SH DESCRIPTION -This function sets up the program environment that libcurl needs. Think -of it as an extension of the library loader. +This function sets up the program environment that libcurl needs. Think of it +as an extension of the library loader. -This function must be called at least once within a program (a program is -all the code that shares a memory space) before the program calls any other -function in libcurl. The environment it sets up is constant for the life -of the program and is the same for every program, so multiple calls have -the same effect as one call. +This function must be called at least once within a program (a program is all +the code that shares a memory space) before the program calls any other +function in libcurl. The environment it sets up is constant for the life of +the program and is the same for every program, so multiple calls have the same +effect as one call. The flags option is a bit pattern that tells libcurl exactly what features to init, as described below. Set the desired bits by ORing the values together. In normal operation, you must specify CURL_GLOBAL_ALL. Don't use any other -value unless you are familiar with and mean to control internal operations -of libcurl. +value unless you are familiar with and mean to control internal operations of +libcurl. -\fBThis function is not thread safe.\fP You must not call it when any -other thread in the program (i.e. a thread sharing the same memory) is -running. This doesn't just mean no other thread that is using -libcurl. Because \fIcurl_global_init()\fP calls functions of other -libraries that are similarly thread unsafe, it could conflict with any -other thread that uses these other libraries. +\fBThis function is not thread safe.\fP You must not call it when any other +thread in the program (i.e. a thread sharing the same memory) is running. +This doesn't just mean no other thread that is using libcurl. Because +\fIcurl_global_init()\fP calls functions of other libraries that are similarly +thread unsafe, it could conflict with any other thread that uses these other +libraries. -See the description in \fBlibcurl\fP(3) of global environment -requirements for details of how to use this function. +See the description in \fBlibcurl\fP(3) of global environment requirements for +details of how to use this function. .SH FLAGS .TP 5 diff --git a/docs/libcurl/curl_multi_assign.3 b/docs/libcurl/curl_multi_assign.3 new file mode 100644 index 000000000..cb47a5e25 --- /dev/null +++ b/docs/libcurl/curl_multi_assign.3 @@ -0,0 +1,44 @@ +.\" $Id$ +.\" +.TH curl_multi_assign 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" +.SH NAME +curl_multi_assign \- set data to associated with an internal socket +.SH SYNOPSIS +#include <curl/curl.h> + +CURLMcode curl_multi_assign(CURLM *multi_handle, curl_socket_t sockfd, + void *sockptr); +.SH DESCRIPTION +This function assigns an association in the multi handle between the given +socket and a private pointer of the application. This is (only) useful for +\fIcurl_multi_socket(3)\fP uses. + +When set, the \fIsockptr\fP pointer will be passed to all future socket +callbacks for the specific \fIsockfd\fP socket. + +If the given \fIsockfd\fP isn't already in use by libcurl, this function will +return an error. + +libcurl only keeps one single pointer associated with a socket, so calling +this function several times for the same socket will make the last set pointer +get used. + +The idea here being that this association (socket to private pointer) is +something that just about every application that uses this API will need and +then libcurl can just as well do it since it already has an internal hash +table lookup for this. +.SH "RETURN VALUE" +The standard CURLMcode for multi interface error codes. +.SH "TYPICAL USAGE" +In a typical application you allocate a struct or at least use some kind of +semi-dynamic data for each socket that we must wait for action on when using +the \fIcurl_multi_socket(3)\fP approach. + +When our socket-callback get called by libcurl and we get to know about yet +another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out +the particular data so that when we get updates about this same socket again, +we don't have to find the struct associated with this socket by ourselves. +.SH AVAILABILITY +This function was added in libcurl 7.15.5, although not deemed stable yet. +.SH "SEE ALSO" +.BR curl_multi_setopt "(3), " curl_multi_socket "(3) " diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 623daa53f..0228e3d64 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -25,8 +25,9 @@ the socket (file descriptor) status by doing none, one or multiple calls to the curl_socket_callback given in the \fBparam\fP argument. They update the status with changes since the previous time a \fIcurl_multi_socket(3)\fP function was called. If the given callback pointer is NULL, no callback will -be called. Set the callback's fourth argument with \fICURLMOPT_SOCKETDATA\fP. -See \fIcurl_multi_socket(3)\fP for more callback details. +be called. Set the callback's \fBuserp\fP argument with +\fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more callback +details. .IP CURLMOPT_SOCKETDATA Pass a pointer to whatever you want passed to the curl_socket_callback's forth argument, the userp pointer. This is not used by libcurl but only passed-thru diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3 index e5312c840..0c5ba7345 100644 --- a/docs/libcurl/curl_multi_socket.3 +++ b/docs/libcurl/curl_multi_socket.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_socket 3 "21 Dec 2005" "libcurl 7.16.0" "libcurl Manual" +.TH curl_multi_socket 3 "9 Jul 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_socket \- reads/writes available data .SH SYNOPSIS @@ -19,32 +19,41 @@ application has detected action on a socket handled by libcurl, it should call with the action. These functions inform the application about updates in the socket (file -descriptor) status by doing none, one or multiple calls to the -curl_socket_callback given with the CURLMOPT_SOCKETFUNCTION option to +descriptor) status by doing none, one or multiple calls to the callback +function set with the CURLMOPT_SOCKETFUNCTION option to \fIcurl_multi_setopt(3)\fP. They update the status with changes since the previous time this function was called. -If you want to force libcurl to (re-)check all its internal sockets and -transfers instead of just a single one, you call -\fBcurl_multi_socket_all(3)\fP instead. +To force libcurl to (re-)check all its internal sockets and transfers instead +of just a single one, you call \fBcurl_multi_socket_all(3)\fP. -An application should call \fBcurl_multi_timeout(3)\fP to figure out how long -it should wait for socket actions \- at most \- before doing the timeout -action: call the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP -argument set to CURL_SOCKET_TIMEOUT. +Applications should call \fBcurl_multi_timeout(3)\fP to figure out how long to +wait for socket actions \- at most \- before doing the timeout action: call +the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to +CURL_SOCKET_TIMEOUT. + +.SH "CALLBACK DETAILS" The socket \fBcallback\fP function uses a prototype like this .nf - int curl_socket_callback(CURL *easy, /* easy handle */ - curl_socket_t s, /* socket */ - int action, /* see values below */ - void *userp); /* "private" pointer */ + int curl_socket_callback(CURL *easy, /* easy handle */ + curl_socket_t s, /* socket */ + int action, /* see values below */ + void *userp, /* private callback pointer */ + void *socketp); /* private socket pointer */ .fi The callback MUST return 0. -The \fIaction\fP (third) argument to the callback has one of five values: +The \fIeasy\fP argument is a pointer to the easy handle that deals with this +particular socket. Note that a single handle may work with several sockets +simultaneously. + +The \fIs\fP argument is the actual socket value as you use it within your +system. + +The \fIaction\fP argument to the callback has one of five values: .RS .IP "CURL_POLL_NONE (0)" register, not interested in readiness (yet) @@ -57,6 +66,15 @@ register, interested in both read and write readiness .IP "CURL_POLL_REMOVE (4)" deregister .RE + +The \fIsocketp\fP argument is a private pointer you have previously set with +\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no +pointer has been set, socketp will be NULL. This argument is of course a +service to applications that want to keep certain data or structs that are +strictly associated to the given socket. + +The \fIuserp\fP argument is a private pointer you have previously set with +\fIcurl_multi_setopt(3)\fP and the CURLMOPT_SOCKETDATA option. .SH "RETURN VALUE" CURLMcode type, general libcurl multi interface error code. |