Mon Sep 18 09:13:27 2006

Asterisk developer's documentation


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 }

Generated on Mon Sep 18 09:13:27 2006 for Asterisk - the Open Source PBX by  doxygen 1.4.7