1poll(2)                          System Calls                          poll(2)
2
3
4

NAME

6       poll - input/output multiplexing
7

SYNOPSIS

9       #include <poll.h>
10
11       int poll(struct pollfd fds[], nfds_t nfds, int timeout);
12
13

DESCRIPTION

15       The  poll()  function provides applications with a mechanism for multi‐
16       plexing input/output over a set of file descriptors.  For  each  member
17       of the array pointed to by fds, poll() examines the given file descrip‐
18       tor for the event(s) specified in events. The number of  pollfd  struc‐
19       tures  in the fds array is specified by nfds. The poll() function iden‐
20       tifies those file descriptors on which an application can read or write
21       data, or on which certain events have occurred.
22
23
24       The  fds argument specifies the file descriptors to be examined and the
25       events of interest for each file descriptor.  It is  a  pointer  to  an
26       array  with  one member for each open file descriptor of interest.  The
27       array's members are pollfd structures, which contain the following mem‐
28       bers:
29
30         int     fd;        /* file descriptor */
31         short   events;    /* requested events */
32         short   revents;   /* returned events */
33
34
35
36       The  fd  member  specifies  an  open file descriptor and the events and
37       revents members are bitmasks constructed by a logical OR  operation  of
38       any combination of the following event flags:
39
40       POLLIN        Data  other  than  high priority data may be read without
41                     blocking. For streams, this flag is set in  revents  even
42                     if the message is of zero length.
43
44
45       POLLRDNORM    Normal  data (priority band equals 0) may be read without
46                     blocking. For streams, this flag is set in  revents  even
47                     if the message is of zero length.
48
49
50       POLLRDBAND    Data  from  a  non-zero priority band may be read without
51                     blocking. For streams, this flag is set in  revents  even
52                     if the message is of zero length.
53
54
55       POLLPRI       High  priority data may be received without blocking. For
56                     streams, this flag is set in revents even if the  message
57                     is of zero length.
58
59
60       POLLOUT       Normal data (priority band equals 0) may be written with‐
61                     out blocking.
62
63
64       POLLWRNORM    The same as  POLLOUT.
65
66
67       POLLWRBAND    Priority data (priority band > 0) may be  written.   This
68                     event  only  examines  bands that have been written to at
69                     least once.
70
71
72       POLLERR       An error has occurred on the device or stream.  This flag
73                     is  only  valid in the revents bitmask; it is not used in
74                     the events member.
75
76
77       POLLHUP       A hangup has occurred  on  the  stream.  This  event  and
78                     POLLOUT  are  mutually  exclusive;  a stream can never be
79                     writable if a hangup has occurred.  However,  this  event
80                     and   POLLIN, POLLRDNORM, POLLRDBAND, or  POLLPRI are not
81                     mutually exclusive.  This  flag  is  only  valid  in  the
82                     revents bitmask; it is not used in the events member.
83
84
85       POLLNVAL      The  specified  fd value does not belong to an open file.
86                     This flag is only valid in the revents member; it is  not
87                     used in the events member.
88
89
90
91       If the value fd is less than 0, events is ignored and revents is set to
92       0 in that entry on return from  poll().
93
94
95       The results of the poll() query are stored in the revents member in the
96       pollfd structure. Bits are set in the revents bitmask to indicate which
97       of the requested events are true. If none are true, none of the  speci‐
98       fied  bits  are  set in revents when the poll() call returns. The event
99       flags  POLLHUP, POLLERR, and  POLLNVAL are always  set  in  revents  if
100       the  conditions  they  indicate are true; this occurs even though these
101       flags were not present in events.
102
103
104       If none of the defined  events  have  occurred  on  any  selected  file
105       descriptor,  poll() waits at least timeout milliseconds for an event to
106       occur on any of the selected file descriptors. On a computer where mil‐
107       lisecond timing accuracy is not available, timeout is rounded up to the
108       nearest legal value available on that system. If the value  timeout  is
109       0,  poll()  returns immediately. If the value of timeout is  −1, poll()
110       blocks until a requested event occurs or until the call is interrupted.
111       The  poll()  function  is  not affected by the O_NDELAY and  O_NONBLOCK
112       flags.
113
114
115       The poll() function supports regular files, terminal and  pseudo-termi‐
116       nal  devices,  streams-based  files,  FIFOs and pipes.  The behavior of
117       poll() on elements of fds that refer to other types of file is unspeci‐
118       fied.
119
120
121       The poll() function supports sockets.
122
123
124       A  file  descriptor for a socket that is listening for connections will
125       indicate that it is ready for reading, once connections are  available.
126       A  file  descriptor for a socket that is connecting asynchronously will
127       indicate that it is ready for  writing,  once  a  connection  has  been
128       established.
129
130
131       Regular files always poll() TRUE for reading and writing.
132

RETURN VALUES

134       Upon  successful  completion, a non-negative value is returned. A posi‐
135       tive value indicates the total number of file descriptors that has been
136       selected  (that  is,  file  descriptors for which the revents member is
137       non-zero). A value of 0 indicates that the call timed out and  no  file
138       descriptors  have been selected. Upon failure, −1 is returned and errno
139       is set to indicate the error.
140

ERRORS

142       The poll() function will fail if:
143
144       EAGAIN    Allocation  of  internal  data  structures  failed,  but  the
145                 request may be attempted again.
146
147
148       EFAULT    Some argument points to an illegal address.
149
150
151       EINTR     A signal was caught during the poll() function.
152
153
154       EINVAL    The  argument  nfds is greater than {OPEN_MAX}, or one of the
155                 fd members refers to a stream or multiplexer that  is  linked
156                 (directly or indirectly) downstream from a multiplexer.
157
158

ATTRIBUTES

160       See attributes(5) for descriptions of the following attributes:
161
162
163
164
165       ┌─────────────────────────────┬─────────────────────────────┐
166       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
167       ├─────────────────────────────┼─────────────────────────────┤
168       │Interface Stability          │Standard                     │
169       └─────────────────────────────┴─────────────────────────────┘
170

SEE ALSO

172       Intro(2),   getmsg(2),   getrlimit(2),  putmsg(2),  read(2),  write(2),
173       select(3C), attributes(5), standards(5), chpoll(9E)
174
175
176       STREAMS Programming Guide
177

NOTES

179       Non-STREAMS drivers use   chpoll(9E)  to  implement   poll()  on  these
180       devices.
181
182
183
184SunOS 5.11                        23 Aug 2001                          poll(2)
Impressum