From 62b5926d581d8c4939d3be36bcc197b60abc75d7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 1 Mar 2002 15:34:23 +0000 Subject: [PATCH] initial and still basic curl multi interface documentation --- docs/curl_multi_add_handle.3 | 17 ++++++++++++++++ docs/curl_multi_cleanup.3 | 18 +++++++++++++++++ docs/curl_multi_fdset.3 | 23 ++++++++++++++++++++++ docs/curl_multi_info_read.3 | 35 +++++++++++++++++++++++++++++++++ docs/curl_multi_init.3 | 21 ++++++++++++++++++++ docs/curl_multi_perform.3 | 30 ++++++++++++++++++++++++++++ docs/curl_multi_remove_handle.3 | 17 ++++++++++++++++ 7 files changed, 161 insertions(+) create mode 100644 docs/curl_multi_add_handle.3 create mode 100644 docs/curl_multi_cleanup.3 create mode 100644 docs/curl_multi_fdset.3 create mode 100644 docs/curl_multi_info_read.3 create mode 100644 docs/curl_multi_init.3 create mode 100644 docs/curl_multi_perform.3 create mode 100644 docs/curl_multi_remove_handle.3 diff --git a/docs/curl_multi_add_handle.3 b/docs/curl_multi_add_handle.3 new file mode 100644 index 000000000..b8b274da9 --- /dev/null +++ b/docs/curl_multi_add_handle.3 @@ -0,0 +1,17 @@ +.\" $Id$ +.\" +.TH curl_multi_add_handle 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_add_handle - add an easy handle to a multi session +.SH SYNOPSIS +#include + +CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle); +.ad +.SH DESCRIPTION +Adds a standard easy handle to the multi stack. This will make this multi +handle control the specified easy handle. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" diff --git a/docs/curl_multi_cleanup.3 b/docs/curl_multi_cleanup.3 new file mode 100644 index 000000000..d7830e7ac --- /dev/null +++ b/docs/curl_multi_cleanup.3 @@ -0,0 +1,18 @@ +.\" $Id$ +.\" +.TH curl_multi_cleanup 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_cleanup - close down a multi session +.SH SYNOPSIS +.B #include +.sp +.BI "CURLMcode curl_multi_cleanup( CURLM *multi_handle );" +.ad +.SH DESCRIPTION +Cleans up and removes a whole multi stack. It does not free or touch any +individual easy handles in any way - they still need to be closed +individually, using the usual curl_easy_cleanup() way. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_init "(3)," curl_easy_cleanup "(3)," curl_easy_init "(3)" diff --git a/docs/curl_multi_fdset.3 b/docs/curl_multi_fdset.3 new file mode 100644 index 000000000..48aadad8b --- /dev/null +++ b/docs/curl_multi_fdset.3 @@ -0,0 +1,23 @@ +.\" $Id$ +.\" +.TH curl_multi_fdset 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_fdset - add an easy handle to a multi session +.SH SYNOPSIS +#include + +CURLMcode curl_multi_fdset(CURLM *multi_handle, + fd_set *read_fd_set, + fd_set *write_fd_set, + fd_set *exc_fd_set, + int *max_fd); +.ad +.SH DESCRIPTION +This function extracts file descriptor information from a given multi_handle. +libcurl returns its fd_set sets. The application can use these to select() or +poll() on. The curl_multi_perform() function should be called as soon as one +of them are ready to be read from or written to. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" diff --git a/docs/curl_multi_info_read.3 b/docs/curl_multi_info_read.3 new file mode 100644 index 000000000..8fcaeb576 --- /dev/null +++ b/docs/curl_multi_info_read.3 @@ -0,0 +1,35 @@ +.\" $Id$ +.\" +.TH curl_multi_info_read 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_info_read - read multi stack informationals +.SH SYNOPSIS +#include + +CURLMsg *curl_multi_info_read( CURLM *multi_handle, + int *msgs_in_queue); +.ad +.SH DESCRIPTION +Ask the multi handle if there's any messages/informationals from the +individual transfers. Messages include informationals such as an error code +from the transfer or just the fact that a transfer is completed. More details +on these should be written down as well. + +Repeated calls to this function will return a new struct each time, until a +special "end of msgs" struct is returned as a signal that there is no more to +get at this point. The integer pointed to with \fImsgs_in_queue\fP will +contain the number of remaining messages after this function was called. + +The data the returned pointer points to will not survive calling +curl_multi_cleanup(). + +The 'CURLMsg' struct is very simple and only contain very basic informations. +If more involved information is wanted, the particular "easy handle" in +present in that struct and can thus be used in subsequent regular +curl_easy_getinfo() calls (or similar). +.SH "RETURN VALUE" +A pointer to a filled-in struct, or NULL if it failed or ran out of +structs. It also writes the number of messages left in the queue (after this +read) in the integer the second argument points to. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)," curl_multi_perform "(3)" diff --git a/docs/curl_multi_init.3 b/docs/curl_multi_init.3 new file mode 100644 index 000000000..36336b1ff --- /dev/null +++ b/docs/curl_multi_init.3 @@ -0,0 +1,21 @@ +.\" $Id$ +.\" +.TH curl_multi_init 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_init - Start a multi session +.SH SYNOPSIS +.B #include +.sp +.BI "CURLM *curl_multi_init( );" +.ad +.SH DESCRIPTION +This function returns a CURLM handle to be used as input to all the other +multi-functions. This init call MUST have a corresponding call to +\fIcurl_multi_cleanup\fP when the operation is complete. +.SH RETURN VALUE +If this function returns NULL, something went wrong and you cannot use the +other curl functions. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_global_init "(3)," curl_easy_init "(3)" +.SH BUGS +Surely there are some, you tell me! diff --git a/docs/curl_multi_perform.3 b/docs/curl_multi_perform.3 new file mode 100644 index 000000000..dae41ace8 --- /dev/null +++ b/docs/curl_multi_perform.3 @@ -0,0 +1,30 @@ +.\" $Id$ +.\" +.TH curl_multi_perform 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_perform - add an easy handle to a multi session +.SH SYNOPSIS +#include + +CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles); +.ad +.SH DESCRIPTION +When the app thinks there's data available for the multi_handle, it should +call this function to read/write whatever there is to read or write right +now. curl_multi_perform() returns as soon as the reads/writes are done. This +function does not require that there actually is any data available for +reading or that data can be written, it can be called just in case. It will +write the number of handles that still transfer data in the second argument's +integer-pointer. +.SH "RETURN VALUE" +CURLMcode type, general libcurl multi interface error code. + +NOTE that this only returns errors etc regarding the whole multi stack. There +might still have occurred problems on invidual transfers even when this +function returns OK. +.SH "TYPICAL USAGE" +Most application will use \fIcurl_multi_fdset\fP to get the multi_handle's +file descriptors, then it'll wait for action on them using select() and as +soon as one or more of them are ready, \fIcurl_multi_perform\fP gets called. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)" diff --git a/docs/curl_multi_remove_handle.3 b/docs/curl_multi_remove_handle.3 new file mode 100644 index 000000000..11cc6c587 --- /dev/null +++ b/docs/curl_multi_remove_handle.3 @@ -0,0 +1,17 @@ +.\" $Id$ +.\" +.TH curl_multi_remove_handle 3 "1 March 2002" "libcurl 7.9.5" "libcurl Manual" +.SH NAME +curl_multi_remove_handle - add an easy handle to a multi session +.SH SYNOPSIS +#include + +CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle); +.ad +.SH DESCRIPTION +Removes a given easy_handle from the multi_handle. This will make the +specified easy handle be removed from this multi handle's control. +.SH RETURN VALUE +CURLMcode type, general libcurl multi interface error code. +.SH "SEE ALSO" +.BR curl_multi_cleanup "(3)," curl_multi_init "(3)"