KallistiOS  2.0.0
poll.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2
3  poll.h
4  Copyright (C) 2012 Lawrence Sebald
5 */
6
7 /** \file poll.h
8  \brief Definitions for the poll() function.
9
10  This file contains the definitions needed for using the poll() function, as
11  directed by the POSIX 2008 standard (aka The Open Group Base Specifications
12  Issue 7). Currently the functionality defined herein only works for sockets,
13  and that is likely how it will stay for some time.
14
15  The poll() function works quite similarly to the select() function that it
16  is quite likely that you'd be more familiar with.
17
18  \author Lawrence Sebald
19 */
20
21 #ifndef __POLL_H
22 #define __POLL_H
23
24 #include <sys/cdefs.h>
25 #include <sys/types.h>
26
27 __BEGIN_DECLS
28
29 /** \brief Type representing a number of file descriptors. */
30 typedef __uint32_t nfds_t;
31
32 /** \brief Structure representing a single file descriptor used by poll().
33  \headerfile poll.h
34 */
35 struct pollfd {
36  int fd; /**< \brief The file descriptor in question. */
37  short events; /**< \brief Events to poll for on input. */
38  short revents; /**< \brief Events signalled for output. */
39 };
40
41 /** \defgroup poll_events Events for the poll() function
42
43  These are the events that can be set in the events or revents fields of the
44  struct pollfd.
45
46  @{
47 */
48 #define POLLRDNORM (1 << 0) /**< \brief Normal data may be read */
49 #define POLLRDBAND (1 << 1) /**< \brief Priority data may be read */
50 #define POLLPRI (1 << 2) /**< \brief High-priority data may be read */
51 #define POLLOUT (1 << 3) /**< \brief Normal data may be written */
52 #define POLLWRNORM POLLOUT /**< \brief Normal data may be written */
53 #define POLLWRBAND (1 << 4) /**< \brief Priority data may be written */
54 #define POLLERR (1 << 5) /**< \brief Error has occurred (revents only) */
55 #define POLLHUP (1 << 6) /**< \brief Peer disconnected (revents only) */
56 #define POLLNVAL (1 << 7) /**< \brief Invalid fd (revents only) */
57
58 /** \brief Data other than high-priority data may be read */
59 #define POLLIN (POLLRDNORM | POLLRDBAND)
60 /** @} */
61
62 /** \brief Poll a group of file descriptors for activity.
63
64  This function will poll a group of file descriptors to check for the events
65  specified on them. The function shall block for the specified period of time
66  (in milliseconds) waiting for an event to occur. The function shall return
67  as soon as at least one fd matches the events specified (or one of the error
68  conditions), or when timeout expires.
69
70  \param fds The file descriptors to check, and what events to look
71  for on each.
72  \param nfds Number of elements in fds.
73  \param timeout Maximum amount of time to block, in milliseconds. Pass
74  0 to ensure the function does not block and -1 to block
75  for an "infinite" amount of time, until an event occurs.
76  \return -1 on error (sets errno as appropriate), or the number
77  of file descriptors that matched the event flags before
78  the function returns.
79  \sa poll_events
80 */
81 int poll(struct pollfd fds[], nfds_t nfds, int timeout);
82
83 __END_DECLS
84
85 #endif /* !POLL_H */