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     ! 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) "