logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

poll.3p (10765B)


  1. '\" et
  2. .TH POLL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. poll
  12. \(em input/output multiplexing
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <poll.h>
  17. .P
  18. int poll(struct pollfd \fIfds\fP[], nfds_t \fInfds\fP, int \fItimeout\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIpoll\fR()
  23. function provides applications with a mechanism for multiplexing
  24. input/output over a set of file descriptors. For each member of the
  25. array pointed to by
  26. .IR fds ,
  27. \fIpoll\fR()
  28. shall examine the given file descriptor for the event(s) specified in
  29. .IR events .
  30. The number of
  31. .BR pollfd
  32. structures in the
  33. .IR fds
  34. array is specified by
  35. .IR nfds .
  36. The
  37. \fIpoll\fR()
  38. function shall identify those file descriptors on which an application
  39. can read or write data, or on which certain events have occurred.
  40. .P
  41. The
  42. .IR fds
  43. argument specifies the file descriptors to be examined
  44. and the events of interest for each file descriptor. It is a pointer to
  45. an array with one member for each open file descriptor of interest. The
  46. array's members are
  47. .BR pollfd
  48. structures within which
  49. .IR fd
  50. specifies an open file descriptor and
  51. .IR events
  52. and
  53. .IR revents
  54. are bitmasks constructed by OR'ing a combination of the following event
  55. flags:
  56. .IP POLLIN 12
  57. Data other than high-priority data may be read without blocking.
  58. .RS 12
  59. .P
  60. For STREAMS, this flag is set in
  61. .IR revents
  62. even if the message is of zero length. This flag shall be equivalent
  63. to POLLRDNORM | POLLRDBAND.
  64. .RE
  65. .IP POLLRDNORM 12
  66. Normal data may be read without blocking.
  67. .RS 12
  68. .P
  69. For STREAMS, data on priority band 0 may be read without blocking. This
  70. flag is set in
  71. .IR revents
  72. even if the message is of zero length.
  73. .RE
  74. .IP POLLRDBAND 12
  75. Priority data may be read without blocking.
  76. .RS 12
  77. .P
  78. For STREAMS, data on priority bands greater than 0 may be read without
  79. blocking. This flag is set in
  80. .IR revents
  81. even if the message is of zero length.
  82. .RE
  83. .IP POLLPRI 12
  84. High-priority data may be read without blocking.
  85. .RS 12
  86. .P
  87. For STREAMS, this flag is set in
  88. .IR revents
  89. even if the message is of zero length.
  90. .RE
  91. .IP POLLOUT 12
  92. Normal data may be written without blocking.
  93. .RS 12
  94. .P
  95. For STREAMS, data on priority band 0 may be written without blocking.
  96. .RE
  97. .IP POLLWRNORM 12
  98. Equivalent to POLLOUT.
  99. .IP POLLWRBAND 12
  100. Priority data may be written.
  101. .RS 12
  102. .P
  103. For STREAMS, data on priority bands greater than 0 may be written
  104. without blocking. If any priority band has been written to on this
  105. STREAM, this event only examines bands that have been written
  106. to at least once.
  107. .RE
  108. .IP POLLERR 12
  109. An error has occurred on the device or stream. This flag is only valid
  110. in the
  111. .IR revents
  112. bitmask; it shall be ignored in the
  113. .IR events
  114. member.
  115. .IP POLLHUP 12
  116. A device has been disconnected, or a pipe or FIFO has been closed by the
  117. last process that had it open for writing. Once set, the hangup state of a
  118. FIFO shall persist until some process opens the FIFO for writing or until
  119. all read-only file descriptors for the FIFO are closed. This event and
  120. POLLOUT are mutually-exclusive; a stream can never be writable if a hangup
  121. has occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND,
  122. or POLLPRI are not mutually-exclusive. This flag is only valid in the
  123. .IR revents
  124. bitmask; it shall be ignored in the
  125. .IR events
  126. member.
  127. .IP POLLNVAL 12
  128. The specified
  129. .IR fd
  130. value is invalid. This flag is only valid in the
  131. .IR revents
  132. member; it shall ignored in the
  133. .IR events
  134. member.
  135. .P
  136. The significance and semantics of normal, priority, and high-priority
  137. data are file and device-specific.
  138. .P
  139. If the value of
  140. .IR fd
  141. is less than 0,
  142. .IR events
  143. shall be ignored, and
  144. .IR revents
  145. shall be set to 0 in that entry on return from
  146. \fIpoll\fR().
  147. .P
  148. In each
  149. .BR pollfd
  150. structure,
  151. \fIpoll\fR()
  152. shall clear the
  153. .IR revents
  154. member, except that where the application requested a report on a
  155. condition by setting one of the bits of
  156. .IR events
  157. listed above,
  158. \fIpoll\fR()
  159. shall set the corresponding bit in
  160. .IR revents
  161. if the requested condition is true. In addition,
  162. \fIpoll\fR()
  163. shall set the POLLHUP, POLLERR, and POLLNVAL flag in
  164. .IR revents
  165. if the condition is true, even if the application did not set the
  166. corresponding bit in
  167. .IR events .
  168. .P
  169. If none of the defined events have occurred on any selected file
  170. descriptor,
  171. \fIpoll\fR()
  172. shall wait at least
  173. .IR timeout
  174. milliseconds for an event to occur on any of the selected file
  175. descriptors. If the value of
  176. .IR timeout
  177. is 0,
  178. \fIpoll\fR()
  179. shall return immediately. If the value of
  180. .IR timeout
  181. is \-1,
  182. \fIpoll\fR()
  183. shall block until a requested event occurs or until the call is
  184. interrupted.
  185. .P
  186. Implementations may place limitations on the granularity of timeout
  187. intervals. If the requested timeout interval requires a finer
  188. granularity than the implementation supports, the actual timeout
  189. interval shall be rounded up to the next supported value.
  190. .P
  191. The
  192. \fIpoll\fR()
  193. function shall not be affected by the O_NONBLOCK flag.
  194. .P
  195. The
  196. \fIpoll\fR()
  197. function shall support regular files, terminal and pseudo-terminal
  198. devices, FIFOs, pipes, sockets and
  199. STREAMS-based files.
  200. The behavior of
  201. \fIpoll\fR()
  202. on elements of
  203. .IR fds
  204. that refer to other types of file is unspecified.
  205. .P
  206. Regular files shall always poll TRUE for reading and writing.
  207. .P
  208. A file descriptor for a socket that is listening for connections shall
  209. indicate that it is ready for reading, once connections are available.
  210. A file descriptor for a socket that is connecting asynchronously shall
  211. indicate that it is ready for writing, once a connection has been
  212. established.
  213. .P
  214. Provided the application does not perform any action that results in
  215. unspecified or undefined behavior, the value of the
  216. .IR fd
  217. and
  218. .IR events
  219. members of each element of
  220. .IR fds
  221. shall not be modified by
  222. \fIpoll\fR().
  223. .SH "RETURN VALUE"
  224. Upon successful completion,
  225. \fIpoll\fR()
  226. shall return a non-negative value. A positive value indicates the total
  227. number of
  228. .BR pollfd
  229. structures that have selected events (that is, those for which the
  230. .IR revents
  231. member is non-zero). A value of 0 indicates that the call timed out and
  232. no file descriptors have been selected. Upon failure,
  233. \fIpoll\fR()
  234. shall return \-1 and set
  235. .IR errno
  236. to indicate the error.
  237. .SH ERRORS
  238. The
  239. \fIpoll\fR()
  240. function shall fail if:
  241. .TP
  242. .BR EAGAIN
  243. The allocation of internal data structures failed but a subsequent
  244. request may succeed.
  245. .TP
  246. .BR EINTR
  247. A signal was caught during
  248. \fIpoll\fR().
  249. .TP
  250. .BR EINVAL
  251. The
  252. .IR nfds
  253. argument is greater than
  254. {OPEN_MAX},
  255. or one of the
  256. .IR fd
  257. members refers to a STREAM or multiplexer that is linked (directly or
  258. indirectly) downstream from a multiplexer.
  259. .LP
  260. .IR "The following sections are informative."
  261. .SH EXAMPLES
  262. .SS "Checking for Events on a Stream"
  263. .P
  264. The following example opens a pair of STREAMS devices and then waits
  265. for either one to become writable. This example proceeds as follows:
  266. .IP " 1." 4
  267. Sets the
  268. .IR timeout
  269. parameter to 500 milliseconds.
  270. .IP " 2." 4
  271. Opens the STREAMS devices
  272. .BR /dev/dev0
  273. and
  274. .BR /dev/dev1 ,
  275. and then polls them, specifying POLLOUT and POLLWRBAND as the events of
  276. interest.
  277. .RS 4
  278. .P
  279. The STREAMS device names
  280. .BR /dev/dev0
  281. and
  282. .BR /dev/dev1
  283. are only examples of how STREAMS devices can be named; STREAMS naming
  284. conventions may vary among systems conforming to the POSIX.1\(hy2008.
  285. .RE
  286. .IP " 3." 4
  287. Uses the
  288. .IR ret
  289. variable to determine whether an event has occurred on either of the
  290. two STREAMS. The
  291. \fIpoll\fR()
  292. function is given 500 milliseconds to wait for an event to occur (if it
  293. has not occurred prior to the
  294. \fIpoll\fR()
  295. call).
  296. .IP " 4." 4
  297. Checks the returned value of
  298. .IR ret .
  299. If a positive value is returned, one of the following can be done:
  300. .RS 4
  301. .IP " a." 4
  302. Priority data can be written to the open STREAM on priority bands
  303. greater than 0, because the POLLWRBAND event occurred on the open
  304. STREAM (\c
  305. .IR fds [0]
  306. or
  307. .IR fds [1]).
  308. .IP " b." 4
  309. Data can be written to the open STREAM on priority-band 0, because the
  310. POLLOUT event occurred on the open STREAM (\c
  311. .IR fds [0]
  312. or
  313. .IR fds [1]).
  314. .RE
  315. .IP " 5." 4
  316. If the returned value is not a positive value, permission to write data
  317. to the open STREAM (on any priority band) is denied.
  318. .IP " 6." 4
  319. If the POLLHUP event occurs on the open STREAM (\c
  320. .IR fds [0]
  321. or
  322. .IR fds [1]),
  323. the device on the open STREAM has disconnected.
  324. .sp
  325. .RS 4
  326. .nf
  327. #include <stropts.h>
  328. #include <poll.h>
  329. \&...
  330. struct pollfd fds[2];
  331. int timeout_msecs = 500;
  332. int ret;
  333. int i;
  334. .P
  335. /* Open STREAMS device. */
  336. fds[0].fd = open("/dev/dev0", ...);
  337. fds[1].fd = open("/dev/dev1", ...);
  338. fds[0].events = POLLOUT | POLLWRBAND;
  339. fds[1].events = POLLOUT | POLLWRBAND;
  340. .P
  341. ret = poll(fds, 2, timeout_msecs);
  342. .P
  343. if (ret > 0) {
  344. /* An event on one of the fds has occurred. */
  345. for (i=0; i<2; i++) {
  346. if (fds[i].revents & POLLWRBAND) {
  347. /* Priority data may be written on device number i. */
  348. \&...
  349. }
  350. if (fds[i].revents & POLLOUT) {
  351. /* Data may be written on device number i. */
  352. \&...
  353. }
  354. if (fds[i].revents & POLLHUP) {
  355. /* A hangup has occurred on device number i. */
  356. \&...
  357. }
  358. }
  359. }
  360. .fi
  361. .P
  362. .RE
  363. .SH "APPLICATION USAGE"
  364. None.
  365. .SH RATIONALE
  366. The POLLHUP event does not occur for FIFOs just because the FIFO is not
  367. open for writing. It only occurs when the FIFO is closed by the last
  368. writer and persists until some process opens the FIFO for writing or
  369. until all read-only file descriptors for the FIFO are closed.
  370. .SH "FUTURE DIRECTIONS"
  371. None.
  372. .SH "SEE ALSO"
  373. .IR "Section 2.6" ", " "STREAMS",
  374. .IR "\fIgetmsg\fR\^(\|)",
  375. .IR "\fIpselect\fR\^(\|)",
  376. .IR "\fIputmsg\fR\^(\|)",
  377. .IR "\fIread\fR\^(\|)",
  378. .IR "\fIwrite\fR\^(\|)"
  379. .P
  380. The Base Definitions volume of POSIX.1\(hy2017,
  381. .IR "\fB<poll.h>\fP",
  382. .IR "\fB<stropts.h>\fP"
  383. .\"
  384. .SH COPYRIGHT
  385. Portions of this text are reprinted and reproduced in electronic form
  386. from IEEE Std 1003.1-2017, Standard for Information Technology
  387. -- Portable Operating System Interface (POSIX), The Open Group Base
  388. Specifications Issue 7, 2018 Edition,
  389. Copyright (C) 2018 by the Institute of
  390. Electrical and Electronics Engineers, Inc and The Open Group.
  391. In the event of any discrepancy between this version and the original IEEE and
  392. The Open Group Standard, the original IEEE and The Open Group Standard
  393. is the referee document. The original Standard can be obtained online at
  394. http://www.opengroup.org/unix/online.html .
  395. .PP
  396. Any typographical or formatting errors that appear
  397. in this page are most likely
  398. to have been introduced during the conversion of the source files to
  399. man page format. To report such errors, see
  400. https://www.kernel.org/doc/man-pages/reporting_bugs.html .