Return to curl_multi_fdset.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl

Annotation of embedaddon/curl/docs/libcurl/curl_multi_fdset.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
                      9: .\" *
                     10: .\" * This software is licensed as described in the file COPYING, which
                     11: .\" * you should have received as part of this distribution. The terms
                     12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
                     13: .\" *
                     14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
                     15: .\" * copies of the Software, and permit persons to whom the Software is
                     16: .\" * furnished to do so, under the terms of the COPYING file.
                     17: .\" *
                     18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
                     19: .\" * KIND, either express or implied.
                     20: .\" *
                     21: .\" **************************************************************************
                     22: .TH curl_multi_fdset 3 "November 09, 2017" "libcurl 7.70.0" "libcurl Manual"
                     23: 
                     24: .SH NAME
                     25: curl_multi_fdset - extracts file descriptor information from a multi handle
                     26: .SH SYNOPSIS
                     27: .nf
                     28: #include <curl/curl.h>
                     29: 
                     30: CURLMcode curl_multi_fdset(CURLM *multi_handle,
                     31:                            fd_set *read_fd_set,
                     32:                            fd_set *write_fd_set,
                     33:                            fd_set *exc_fd_set,
                     34:                            int *max_fd);
                     35: .ad
                     36: .SH DESCRIPTION
                     37: This function extracts file descriptor information from a given multi_handle.
                     38: libcurl returns its fd_set sets. The application can use these to select() on,
                     39: but be sure to FD_ZERO them before calling this function as
                     40: \fIcurl_multi_fdset(3)\fP only adds its own descriptors, it doesn't zero or
                     41: otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should
                     42: be called as soon as one of them is ready to be read from or written to.
                     43: 
                     44: If the \fIread_fd_set\fP argument is not a null pointer, it points to an
                     45: object of type fd_set that on returns specifies the file descriptors to be
                     46: checked for being ready to read.
                     47: 
                     48: If the \fIwrite_fd_set\fP argument is not a null pointer, it points to an
                     49: object of type fd_set that on return specifies the file descriptors to be
                     50: checked for being ready to write.
                     51: 
                     52: If the \fIexc_fd_set\fP argument is not a null pointer, it points to an object
                     53: of type fd_set that on return specifies the file descriptors to be checked for
                     54: error conditions pending.
                     55: 
                     56: If no file descriptors are set by libcurl, \fImax_fd\fP will contain -1 when
                     57: this function returns. Otherwise it will contain the highest descriptor number
                     58: libcurl set. When libcurl returns -1 in \fImax_fd\fP, it is because libcurl
                     59: currently does something that isn't possible for your application to monitor
                     60: with a socket and unfortunately you can then not know exactly when the current
                     61: action is completed using select(). You then need to wait a while before you
                     62: proceed and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless
                     63: \fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100
                     64: milliseconds or so, but you may want to test it out in your own particular
                     65: conditions to find a suitable value.
                     66: 
                     67: When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out
                     68: how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no
                     69: activity has been seen on the fd_sets after the timeout expires as otherwise
                     70: internal retries and timeouts may not work as you'd think and want.
                     71: 
                     72: If one of the sockets used by libcurl happens to be larger than what can be
                     73: set in an fd_set, which on POSIX systems means that the file descriptor is
                     74: larger than FD_SETSIZE, then libcurl will try to not set it. Setting a too
                     75: large file descriptor in an fd_set implies an out of bounds write which can
                     76: cause crashes, or worse. The effect of NOT storing it will possibly save you
                     77: from the crash, but will make your program NOT wait for sockets it should wait
                     78: for...
                     79: .SH RETURN VALUE
                     80: CURLMcode type, general libcurl multi interface error code. See
                     81: \fIlibcurl-errors(3)\fP
                     82: .SH "SEE ALSO"
                     83: .BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
                     84: .BR curl_multi_wait "(3), "
                     85: .BR curl_multi_timeout "(3), " curl_multi_perform "(3), " select "(2) "