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

pselect.3p (15226B)


  1. '\" et
  2. .TH PSELECT "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. pselect,
  12. select
  13. \(em synchronous I/O multiplexing
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <sys/select.h>
  18. .P
  19. int pselect(int \fInfds\fP, fd_set *restrict \fIreadfds\fP,
  20. fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP,
  21. const struct timespec *restrict \fItimeout\fP,
  22. const sigset_t *restrict \fIsigmask\fP);
  23. int select(int \fInfds\fP, fd_set *restrict \fIreadfds\fP,
  24. fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP,
  25. struct timeval *restrict \fItimeout\fP);
  26. void FD_CLR(int \fIfd\fP, fd_set *\fIfdset\fP);
  27. int FD_ISSET(int \fIfd\fP, fd_set *\fIfdset\fP);
  28. void FD_SET(int \fIfd\fP, fd_set *\fIfdset\fP);
  29. void FD_ZERO(fd_set *\fIfdset\fP);
  30. .fi
  31. .SH DESCRIPTION
  32. The
  33. \fIpselect\fR()
  34. function shall examine the file descriptor sets whose addresses are
  35. passed in the
  36. .IR readfds ,
  37. .IR writefds ,
  38. and
  39. .IR errorfds
  40. parameters to see whether some of their descriptors are ready for reading,
  41. are ready for writing, or have an exceptional condition pending,
  42. respectively.
  43. .P
  44. The
  45. \fIselect\fR()
  46. function shall be equivalent to the
  47. \fIpselect\fR()
  48. function, except as follows:
  49. .IP " *" 4
  50. For the
  51. \fIselect\fR()
  52. function, the timeout period is given in seconds and microseconds in an
  53. argument of type
  54. .BR "struct timeval" ,
  55. whereas for the
  56. \fIpselect\fR()
  57. function the timeout period is given in seconds and nanoseconds in an
  58. argument of type
  59. .BR "struct timespec" .
  60. .IP " *" 4
  61. The
  62. \fIselect\fR()
  63. function has no
  64. .IR sigmask
  65. argument; it shall behave as
  66. \fIpselect\fR()
  67. does when
  68. .IR sigmask
  69. is a null pointer.
  70. .IP " *" 4
  71. Upon successful completion, the
  72. \fIselect\fR()
  73. function may modify the object pointed to by the
  74. .IR timeout
  75. argument.
  76. .P
  77. The
  78. \fIpselect\fR()
  79. and
  80. \fIselect\fR()
  81. functions shall support regular files, terminal and pseudo-terminal
  82. devices,
  83. STREAMS-based files,
  84. FIFOs, pipes, and sockets. The behavior of
  85. \fIpselect\fR()
  86. and
  87. \fIselect\fR()
  88. on file descriptors that refer to other types of file is unspecified.
  89. .P
  90. The
  91. .IR nfds
  92. argument specifies the range of descriptors to be tested. The first
  93. .IR nfds
  94. descriptors shall be checked in each set; that is, the descriptors from
  95. zero through
  96. .IR nfds \-1
  97. in the descriptor sets shall be examined.
  98. .P
  99. If the
  100. .IR readfds
  101. argument is not a null pointer, it points to an object of type
  102. .BR fd_set
  103. that on input specifies the file descriptors to be checked for being
  104. ready to read, and on output indicates which file descriptors are ready
  105. to read.
  106. .P
  107. If the
  108. .IR writefds
  109. argument is not a null pointer, it points to an object of type
  110. .BR fd_set
  111. that on input specifies the file descriptors to be checked for being
  112. ready to write, and on output indicates which file descriptors are
  113. ready to write.
  114. .P
  115. If the
  116. .IR errorfds
  117. argument is not a null pointer, it points to an object of type
  118. .BR fd_set
  119. that on input specifies the file descriptors to be checked for error
  120. conditions pending, and on output indicates which file descriptors have
  121. error conditions pending.
  122. .P
  123. Upon successful completion, the
  124. \fIpselect\fR()
  125. or
  126. \fIselect\fR()
  127. function shall modify the objects pointed to by the
  128. .IR readfds ,
  129. .IR writefds ,
  130. and
  131. .IR errorfds
  132. arguments to indicate which file descriptors are ready for reading,
  133. ready for writing, or have an error condition pending, respectively,
  134. and shall return the total number of ready descriptors in all the
  135. output sets. For each file descriptor less than
  136. .IR nfds ,
  137. the corresponding bit shall be set upon successful completion if it
  138. was set on input and the associated condition is true for that file
  139. descriptor.
  140. .P
  141. If none of the selected descriptors are ready for the requested
  142. operation, the
  143. \fIpselect\fR()
  144. or
  145. \fIselect\fR()
  146. function shall block until at least one of the requested operations
  147. becomes ready, until the
  148. .IR timeout
  149. occurs, or until interrupted by a signal.
  150. The
  151. .IR timeout
  152. parameter controls how long the
  153. \fIpselect\fR()
  154. or
  155. \fIselect\fR()
  156. function shall take before timing out. If the
  157. .IR timeout
  158. parameter is not a null pointer, it specifies a maximum interval to
  159. wait for the selection to complete. If the specified time interval
  160. expires without any requested operation becoming ready, the function
  161. shall return. If the
  162. .IR timeout
  163. parameter is a null pointer, then the call to
  164. \fIpselect\fR()
  165. or
  166. \fIselect\fR()
  167. shall block indefinitely until at least one descriptor meets the
  168. specified criteria. To effect a poll, the
  169. .IR timeout
  170. parameter should not be a null pointer, and should point to a
  171. zero-valued
  172. .BR timespec
  173. structure.
  174. .P
  175. The use of a timeout does not affect any pending timers set up by
  176. \fIalarm\fR()
  177. or
  178. \fIsetitimer\fR().
  179. .P
  180. Implementations may place limitations on the maximum timeout interval
  181. supported. All implementations shall support a maximum timeout interval
  182. of at least 31 days. If the
  183. .IR timeout
  184. argument specifies a timeout interval greater than the
  185. implementation-defined maximum value, the maximum value shall be used
  186. as the actual timeout value. Implementations may also place limitations
  187. on the granularity of timeout intervals. If the requested timeout
  188. interval requires a finer granularity than the implementation supports,
  189. the actual timeout interval shall be rounded up to the next supported
  190. value.
  191. .P
  192. If
  193. .IR sigmask
  194. is not a null pointer, then the
  195. \fIpselect\fR()
  196. function shall replace the signal mask of the caller by the set of
  197. signals pointed to by
  198. .IR sigmask
  199. before examining the descriptors, and shall restore the signal mask of
  200. the calling thread before returning.
  201. .P
  202. A descriptor shall be considered ready for reading when a call to an
  203. input function with O_NONBLOCK clear would not block, whether or not
  204. the function would transfer data successfully. (The function might
  205. return data, an end-of-file indication, or an error other than one
  206. indicating that it is blocked, and in each of these cases the
  207. descriptor shall be considered ready for reading.)
  208. .P
  209. A descriptor shall be considered ready for writing when a call to an
  210. output function with O_NONBLOCK clear would not block, whether or not
  211. the function would transfer data successfully.
  212. .P
  213. If a socket has a pending error, it shall be considered to have an
  214. exceptional condition pending. Otherwise, what constitutes an
  215. exceptional condition is file type-specific. For a file descriptor for
  216. use with a socket, it is protocol-specific except as noted below. For
  217. other file types it is implementation-defined. If the operation is
  218. meaningless for a particular file type,
  219. \fIpselect\fR()
  220. or
  221. \fIselect\fR()
  222. shall indicate that the descriptor is ready for read or write
  223. operations, and shall indicate that the descriptor has no exceptional
  224. condition pending.
  225. .P
  226. If a descriptor refers to a socket, the implied input function is the
  227. \fIrecvmsg\fR()
  228. function with parameters requesting normal and ancillary data, such
  229. that the presence of either type shall cause the socket to be marked as
  230. readable. The presence of out-of-band data shall be checked if the
  231. socket option SO_OOBINLINE has been enabled, as out-of-band data is
  232. enqueued with normal data. If the socket is currently listening, then
  233. it shall be marked as readable if an incoming connection request has
  234. been received, and a call to the
  235. \fIaccept\fR()
  236. function shall complete without blocking.
  237. .P
  238. If a descriptor refers to a socket, the implied output function is the
  239. \fIsendmsg\fR()
  240. function supplying an amount of normal data equal to the current value
  241. of the SO_SNDLOWAT option for the socket. If a non-blocking call to
  242. the
  243. \fIconnect\fR()
  244. function has been made for a socket, and the connection attempt has
  245. either succeeded or failed leaving a pending error, the socket shall be
  246. marked as writable.
  247. .P
  248. A socket shall be considered to have an exceptional condition pending
  249. if a receive operation with O_NONBLOCK clear for the open file
  250. description and with the MSG_OOB flag set would return out-of-band data
  251. without blocking. (It is protocol-specific whether the MSG_OOB flag
  252. would be used to read out-of-band data.) A socket shall also be
  253. considered to have an exceptional condition pending if an out-of-band
  254. data mark is present in the receive queue. Other circumstances under
  255. which a socket may be considered to have an exceptional condition
  256. pending are protocol-specific and implementation-defined.
  257. .P
  258. If the
  259. .IR readfds ,
  260. .IR writefds ,
  261. and
  262. .IR errorfds
  263. arguments are all null pointers and the
  264. .IR timeout
  265. argument is not a null pointer, the
  266. \fIpselect\fR()
  267. or
  268. \fIselect\fR()
  269. function shall block for the time specified, or until interrupted by
  270. a signal. If the
  271. .IR readfds ,
  272. .IR writefds ,
  273. and
  274. .IR errorfds
  275. arguments are all null pointers and the
  276. .IR timeout
  277. argument is a null pointer, the
  278. \fIpselect\fR()
  279. or
  280. \fIselect\fR()
  281. function shall block until interrupted by a signal.
  282. .P
  283. File descriptors associated with regular files shall always select true
  284. for ready to read, ready to write, and error conditions.
  285. .P
  286. On failure, the objects pointed to by the
  287. .IR readfds ,
  288. .IR writefds ,
  289. and
  290. .IR errorfds
  291. arguments shall not be modified. If the timeout interval expires
  292. without the specified condition being true for any of the specified
  293. file descriptors, the objects pointed to by the
  294. .IR readfds ,
  295. .IR writefds ,
  296. and
  297. .IR errorfds
  298. arguments shall have all bits set to 0.
  299. .P
  300. File descriptor masks of type
  301. .BR fd_set
  302. can be initialized and tested with
  303. \fIFD_CLR\fR(),
  304. \fIFD_ISSET\fR(),
  305. \fIFD_SET\fR(),
  306. and
  307. \fIFD_ZERO\fR().
  308. It is unspecified whether each of these is a macro or a function. If a
  309. macro definition is suppressed in order to access an actual function,
  310. or a program defines an external identifier with any of these names,
  311. the behavior is undefined.
  312. .P
  313. \fIFD_CLR\fR(\fIfd\fR, \fIfdsetp\fR) shall remove the file descriptor
  314. .IR fd
  315. from the set pointed to by
  316. .IR fdsetp .
  317. If
  318. .IR fd
  319. is not a member of this set, there shall be no effect on the set, nor
  320. will an error be returned.
  321. .P
  322. \fIFD_ISSET\fR(\fIfd\fR, \fIfdsetp\fR) shall evaluate to non-zero if
  323. the file descriptor
  324. .IR fd
  325. is a member of the set pointed to by
  326. .IR fdsetp ,
  327. and shall evaluate to zero otherwise.
  328. .P
  329. \fIFD_SET\fR(\fIfd\fR, \fIfdsetp\fR) shall add the file descriptor
  330. .IR fd
  331. to the set pointed to by
  332. .IR fdsetp .
  333. If the file descriptor
  334. .IR fd
  335. is already in this set, there shall be no effect on the set, nor will
  336. an error be returned.
  337. .P
  338. \fIFD_ZERO\fR(\fIfdsetp\fR) shall initialize the descriptor set pointed
  339. to by
  340. .IR fdsetp
  341. to the null set. No error is returned if the set is not empty at the
  342. time
  343. \fIFD_ZERO\fR()
  344. is invoked.
  345. .P
  346. The behavior of these macros is undefined if the
  347. .IR fd
  348. argument is less than 0 or greater than or equal to FD_SETSIZE, or if
  349. .IR fd
  350. is not a valid file descriptor, or if any of the arguments are
  351. expressions with side-effects.
  352. .P
  353. If a thread gets canceled during a
  354. \fIpselect\fR()
  355. call, the signal mask in effect when executing the registered cleanup
  356. functions is either the original signal mask or the signal mask
  357. installed as part of the
  358. \fIpselect\fR()
  359. call.
  360. .SH "RETURN VALUE"
  361. Upon successful completion, the
  362. \fIpselect\fR()
  363. and
  364. \fIselect\fR()
  365. functions shall return the total number of bits set in the bit masks.
  366. Otherwise, \-1 shall be returned, and
  367. .IR errno
  368. shall be set to indicate the error.
  369. .P
  370. \fIFD_CLR\fR(),
  371. \fIFD_SET\fR(),
  372. and
  373. \fIFD_ZERO\fR()
  374. do not return a value.
  375. \fIFD_ISSET\fR()
  376. shall return a non-zero value if the bit for the file descriptor
  377. .IR fd
  378. is set in the file descriptor set pointed to by
  379. .IR fdset ,
  380. and 0 otherwise.
  381. .SH ERRORS
  382. Under the following conditions,
  383. \fIpselect\fR()
  384. and
  385. \fIselect\fR()
  386. shall fail and set
  387. .IR errno
  388. to:
  389. .TP
  390. .BR EBADF
  391. One or more of the file descriptor sets specified a file descriptor
  392. that is not a valid open file descriptor.
  393. .TP
  394. .BR EINTR
  395. The function was interrupted while blocked waiting for any of the
  396. selected descriptors to become ready and before the timeout interval
  397. expired.
  398. .RS 12
  399. .P
  400. If SA_RESTART has been set for the interrupting signal, it is
  401. implementation-defined whether the function restarts or returns with
  402. .BR [EINTR] .
  403. .RE
  404. .TP
  405. .BR EINVAL
  406. An invalid timeout interval was specified.
  407. .TP
  408. .BR EINVAL
  409. The
  410. .IR nfds
  411. argument is less than 0 or greater than FD_SETSIZE.
  412. .TP
  413. .BR EINVAL
  414. One of the specified file descriptors refers to a STREAM or multiplexer
  415. that is linked (directly or indirectly) downstream from a multiplexer.
  416. .LP
  417. .IR "The following sections are informative."
  418. .SH EXAMPLES
  419. None.
  420. .SH "APPLICATION USAGE"
  421. None.
  422. .SH RATIONALE
  423. In earlier versions of the Single UNIX Specification, the
  424. \fIselect\fR()
  425. function was defined in the
  426. .IR <sys/time.h>
  427. header. This is now changed to
  428. .IR <sys/select.h> .
  429. The rationale for this change was as follows: the introduction of the
  430. \fIpselect\fR()
  431. function included the
  432. .IR <sys/select.h>
  433. header and the
  434. .IR <sys/select.h>
  435. header defines all the related definitions for the
  436. \fIpselect\fR()
  437. and
  438. \fIselect\fR()
  439. functions. Backwards-compatibility to existing XSI implementations is
  440. handled by allowing
  441. .IR <sys/time.h>
  442. to include
  443. .IR <sys/select.h> .
  444. .P
  445. Code which wants to avoid the ambiguity of the signal mask for thread
  446. cancellation handlers can install an additional cancellation handler
  447. which resets the signal mask to the expected value.
  448. .sp
  449. .RS 4
  450. .nf
  451. void cleanup(void *arg)
  452. {
  453. sigset_t *ss = (sigset_t *) arg;
  454. pthread_sigmask(SIG_SETMASK, ss, NULL);
  455. }
  456. .P
  457. int call_pselect(int nfds, fd_set *readfds, fd_set *writefds,
  458. fd_set errorfds, const struct timespec *timeout,
  459. const sigset_t *sigmask)
  460. {
  461. sigset_t oldmask;
  462. int result;
  463. pthread_sigmask(SIG_SETMASK, NULL, &oldmask);
  464. pthread_cleanup_push(cleanup, &oldmask);
  465. result = pselect(nfds, readfds, writefds, errorfds, timeout, sigmask);
  466. pthread_cleanup_pop(0);
  467. return result;
  468. }
  469. .fi
  470. .P
  471. .RE
  472. .SH "FUTURE DIRECTIONS"
  473. None.
  474. .SH "SEE ALSO"
  475. .IR "\fIaccept\fR\^(\|)",
  476. .IR "\fIalarm\fR\^(\|)",
  477. .IR "\fIconnect\fR\^(\|)",
  478. .IR "\fIfcntl\fR\^(\|)",
  479. .IR "\fIgetitimer\fR\^(\|)",
  480. .IR "\fIpoll\fR\^(\|)",
  481. .IR "\fIread\fR\^(\|)",
  482. .IR "\fIrecvmsg\fR\^(\|)",
  483. .IR "\fIsendmsg\fR\^(\|)",
  484. .IR "\fIwrite\fR\^(\|)"
  485. .P
  486. The Base Definitions volume of POSIX.1\(hy2017,
  487. .IR "\fB<sys_select.h>\fP",
  488. .IR "\fB<sys_time.h>\fP"
  489. .\"
  490. .SH COPYRIGHT
  491. Portions of this text are reprinted and reproduced in electronic form
  492. from IEEE Std 1003.1-2017, Standard for Information Technology
  493. -- Portable Operating System Interface (POSIX), The Open Group Base
  494. Specifications Issue 7, 2018 Edition,
  495. Copyright (C) 2018 by the Institute of
  496. Electrical and Electronics Engineers, Inc and The Open Group.
  497. In the event of any discrepancy between this version and the original IEEE and
  498. The Open Group Standard, the original IEEE and The Open Group Standard
  499. is the referee document. The original Standard can be obtained online at
  500. http://www.opengroup.org/unix/online.html .
  501. .PP
  502. Any typographical or formatting errors that appear
  503. in this page are most likely
  504. to have been introduced during the conversion of the source files to
  505. man page format. To report such errors, see
  506. https://www.kernel.org/doc/man-pages/reporting_bugs.html .