Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:55 2009

## Asterisk developer's documentation

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Directories

# poll.c

Go to the documentation of this file.

    00001 /*---------------------------------------------------------------------------*\
    00002   $Id: poll.c 7221 2005-11-29 18:24:39Z kpfleming $
    00003
    00004   NAME
    00005
    00006    poll - select(2)-based poll() emulation function for BSD systems.
    00007
    00008   SYNOPSIS
    00009    #include "poll.h"
    00010
    00011    struct pollfd
    00012    {
    00013        int     fd;
    00014        short   events;
    00015        short   revents;
    00016    }
    00017
    00018    int poll (struct pollfd *pArray, unsigned long n_fds, int timeout)
    00019
    00020   DESCRIPTION
    00021
    00022    This file, and the accompanying "poll.h", implement the System V
    00023    poll(2) system call for BSD systems (which typically do not provide
    00024    poll()).  Poll() provides a method for multiplexing input and output
    00025    on multiple open file descriptors; in traditional BSD systems, that
    00026    capability is provided by select().  While the semantics of select()
    00027    differ from those of poll(), poll() can be readily emulated in terms
    00028    of select() -- which is how this function is implemented.
    00029
    00030   REFERENCES
    00031    Stevens, W. Richard. Unix Network Programming.  Prentice-Hall, 1990.
    00032
    00033   NOTES
    00034    1. This software requires an ANSI C compiler.
    00035
    00036   LICENSE
    00037
    00038    This software is released under the following license:
    00039
    00040       Copyright (c) 1995-2002 Brian M. Clapper
    00041       All rights reserved.
    00042
    00043       Redistribution and use in source and binary forms are
    00044       permitted provided that: (1) source distributions retain
    00045       this entire copyright notice and comment; (2) modifications
    00046       made to the software are prominently mentioned, and a copy
    00047       of the original software (or a pointer to its location) are
    00048       included; and (3) distributions including binaries display
    00049       the following acknowledgement: "This product includes
    00050       software developed by Brian M. Clapper <bmc@clapper.org>"
    00051       in the documentation or other materials provided with the
    00052       distribution. The name of the author may not be used to
    00053       endorse or promote products derived from this software
    00054       without specific prior written permission.
    00055
    00056       THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS
    00057       OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE
    00058       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
    00059       PARTICULAR PURPOSE.
    00060
    00061    Effectively, this means you can do what you want with the software
    00062    except remove this notice or take advantage of the author's name.
    00063    If you modify the software and redistribute your modified version,
    00064    you must indicate that your version is a modification of the
    00065    original, and you must provide either a pointer to or a copy of the
    00066    original.
    00067 \*---------------------------------------------------------------------------*/
    00068
    00069
    00070 /*---------------------------------------------------------------------------*\
    00071              Includes
    00072 \*---------------------------------------------------------------------------*/
    00073
    00074 #include <unistd.h>             /* standard Unix definitions */
    00075 #include <sys/types.h>                       /* system types */
    00076 #include <sys/time.h>                        /* time definitions */
    00077 #include <assert.h>                          /* assertion macros */
    00078 #include <string.h>                          /* string functions */
    00079
    00080 #include "asterisk/poll-compat.h"                            /* this package */
    00081
    00082 /*---------------------------------------------------------------------------*\
    00083               Macros
    00084 \*---------------------------------------------------------------------------*/
    00085
    00086 #ifndef MAX
    00087 #define MAX(a,b)  ((a) > (b) ? (a) : (b))
    00088 #endif
    00089
    00090
    00091 /*---------------------------------------------------------------------------*\
    00092               Private Functions
    00093 \*---------------------------------------------------------------------------*/
    00094
    00095 static int map_poll_spec
    00096 #if __STDC__ > 0
    00097          (struct pollfd *pArray,
    00098            unsigned long  n_fds,
    00099            fd_set        *pReadSet,
    00100            fd_set        *pWriteSet,
    00101            fd_set        *pExceptSet)
    00102 #else
    00103           (pArray, n_fds, pReadSet, pWriteSet, pExceptSet)
    00104            struct pollfd *pArray;
    00105            unsigned long  n_fds;
    00106            fd_set        *pReadSet;
    00107            fd_set        *pWriteSet;
    00108            fd_set        *pExceptSet;
    00109 #endif
    00110 {
    00111     register unsigned long  i;                   /* loop control */
    00112     register struct      pollfd *pCur;        /* current array element */
    00113     register int      max_fd = -1;         /* return value */
    00114
    00115     /*
    00116        Map the poll() structures into the file descriptor sets required
    00117        by select().
    00118     */
    00119     for (i = 0, pCur = pArray; i < n_fds; i++, pCur++)
    00120     {
    00121         /* Skip any bad FDs in the array. */
    00122
    00123         if (pCur->fd < 0)
    00124             continue;
    00125
    00126    if (pCur->events & POLLIN)
    00127    {
    00128        /* "Input Ready" notification desired. */
    00129        FD_SET (pCur->fd, pReadSet);
    00130    }
    00131
    00132    if (pCur->events & POLLOUT)
    00133    {
    00134        /* "Output Possible" notification desired. */
    00135        FD_SET (pCur->fd, pWriteSet);
    00136    }
    00137
    00138    if (pCur->events & POLLPRI)
    00139    {
    00140        /*
    00141           "Exception Occurred" notification desired.  (Exceptions
    00142           include out of band data.
    00143        */
    00144        FD_SET (pCur->fd, pExceptSet);
    00145    }
    00146
    00147    max_fd = MAX (max_fd, pCur->fd);
    00148     }
    00149
    00150     return max_fd;
    00151 }
    00152
    00153 static struct timeval *map_timeout
    00154 #if __STDC__ > 0
    00155          (int poll_timeout, struct timeval *pSelTimeout)
    00156 #else
    00157          (poll_timeout, pSelTimeout)
    00158           int             poll_timeout;
    00159           struct timeval *pSelTimeout;
    00160 #endif
    00161 {
    00162     struct timeval *pResult;
    00163
    00164     /*
    00165        Map the poll() timeout value into a select() timeout.  The possible
    00166        values of the poll() timeout value, and their meanings, are:
    00167
    00168        VALUE   MEANING
    00169
    00170        -1   wait indefinitely (until signal occurs)
    00171         0   return immediately, don't block
    00172        >0   wait specified number of milliseconds
    00173
    00174        select() uses a "struct timeval", which specifies the timeout in
    00175        seconds and microseconds, so the milliseconds value has to be mapped
    00176        accordingly.
    00177     */
    00178
    00179     assert (pSelTimeout != (struct timeval *) NULL);
    00180
    00181     switch (poll_timeout)
    00182     {
    00183    case -1:
    00184        /*
    00185           A NULL timeout structure tells select() to wait indefinitely.
    00186        */
    00187        pResult = (struct timeval *) NULL;
    00188        break;
    00189
    00190    case 0:
    00191        /*
    00192           "Return immediately" (test) is specified by all zeros in
    00193           a timeval structure.
    00194        */
    00195        pSelTimeout->tv_sec  = 0;
    00196        pSelTimeout->tv_usec = 0;
    00197        pResult = pSelTimeout;
    00198        break;
    00199
    00200    default:
    00201        /* Wait the specified number of milliseconds. */
    00202        pSelTimeout->tv_sec  = poll_timeout / 1000; /* get seconds */
    00203        poll_timeout        %= 1000;                /* remove seconds */
    00204        pSelTimeout->tv_usec = poll_timeout * 1000; /* get microseconds */
    00205        pResult = pSelTimeout;
    00206        break;
    00207     }
    00208
    00209
    00210     return pResult;
    00211 }
    00212
    00213 static void map_select_results
    00214 #if __STDC__ > 0
    00215           (struct pollfd *pArray,
    00216            unsigned long  n_fds,
    00217            fd_set        *pReadSet,
    00218            fd_set        *pWriteSet,
    00219            fd_set        *pExceptSet)
    00220 #else
    00221           (pArray, n_fds, pReadSet, pWriteSet, pExceptSet)
    00222            struct pollfd *pArray;
    00223            unsigned long  n_fds;
    00224            fd_set        *pReadSet;
    00225            fd_set        *pWriteSet;
    00226            fd_set        *pExceptSet;
    00227 #endif
    00228 {
    00229     register unsigned long  i;                   /* loop control */
    00230     register struct      pollfd *pCur;        /* current array element */
    00231
    00232     for (i = 0, pCur = pArray; i < n_fds; i++, pCur++)
    00233     {
    00234         /* Skip any bad FDs in the array. */
    00235
    00236         if (pCur->fd < 0)
    00237             continue;
    00238
    00239    /* Exception events take priority over input events. */
    00240
    00241    pCur->revents = 0;
    00242    if (FD_ISSET (pCur->fd, pExceptSet))
    00243        pCur->revents |= POLLPRI;
    00244
    00245    else if (FD_ISSET (pCur->fd, pReadSet))
    00246        pCur->revents |= POLLIN;
    00247
    00248    if (FD_ISSET (pCur->fd, pWriteSet))
    00249        pCur->revents |= POLLOUT;
    00250     }
    00251
    00252     return;
    00253 }
    00254
    00255 /*---------------------------------------------------------------------------*\
    00256               Public Functions
    00257 \*---------------------------------------------------------------------------*/
    00258
    00259 int poll
    00260
    00261 #if __STDC__ > 0
    00262    (struct pollfd *pArray, unsigned long n_fds, int timeout)
    00263 #else
    00264    (pArray, n_fds, timeout)
    00265     struct         pollfd *pArray;
    00266     unsigned long n_fds;
    00267     int         timeout;
    00268 #endif
    00269
    00270 {
    00271     fd_set  read_descs;                          /* input file descs */
    00272     fd_set  write_descs;                         /* output file descs */
    00273     fd_set  except_descs;                        /* exception descs */
    00274     struct  timeval stime;                       /* select() timeout value */
    00275     int      ready_descriptors;                   /* function result */
    00276     int      max_fd;                              /* maximum fd value */
    00277     struct  timeval *pTimeout;                   /* actually passed */
    00278
    00279     FD_ZERO (&read_descs);
    00280     FD_ZERO (&write_descs);
    00281     FD_ZERO (&except_descs);
    00282
    00283     assert (pArray != (struct pollfd *) NULL);
    00284
    00285     /* Map the poll() file descriptor list in the select() data structures. */
    00286
    00287     max_fd = map_poll_spec (pArray, n_fds,
    00288              &read_descs, &write_descs, &except_descs);
    00289
    00290     /* Map the poll() timeout value in the select() timeout structure. */
    00291
    00292     pTimeout = map_timeout (timeout, &stime);
    00293
    00294     /* Make the select() call. */
    00295
    00296     ready_descriptors = select (max_fd + 1, &read_descs, &write_descs,
    00297             &except_descs, pTimeout);
    00298
    00299     if (ready_descriptors >= 0)
    00300     {
    00301    map_select_results (pArray, n_fds,
    00302              &read_descs, &write_descs, &except_descs);
    00303     }
    00304
    00305     return ready_descriptors;
    00306 }