rustix/event/
poll.rs

1use crate::event::Timespec;
2use crate::{backend, io};
3
4pub use backend::event::poll_fd::{PollFd, PollFlags};
5
6/// `poll(self.fds, timeout)`—Wait for events on lists of file descriptors.
7///
8/// Some platforms (those that don't support `ppoll`) don't support timeouts
9/// greater than `c_int::MAX` milliseconds; if an unsupported timeout is
10/// passed, this function fails with [`io::Errno::INVAL`].
11///
12/// On macOS, `poll` doesn't work on fds for /dev/tty or /dev/null, however
13/// [`select`] is available and does work on these fds.
14///
15/// [`select`]: crate::event::select()
16///
17/// This function does not use the [`Buffer`] trait because the `fds` list is
18/// both an input and output buffer.
19///
20/// [`Buffer`]: crate::buffer::Buffer
21///
22/// # References
23///  - [Beej's Guide to Network Programming]
24///  - [POSIX]
25///  - [Linux]
26///  - [Apple]
27///  - [Winsock]
28///  - [FreeBSD]
29///  - [NetBSD]
30///  - [OpenBSD]
31///  - [DragonFly BSD]
32///  - [illumos]
33///
34/// [Beej's Guide to Network Programming]: https://beej.us/guide/bgnet/html/split/slightly-advanced-techniques.html#poll
35/// [POSIX]: https://pubs.opengroup.org/onlinepubs/9799919799/functions/poll.html
36/// [Linux]: https://man7.org/linux/man-pages/man2/poll.2.html
37/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/poll.2.html
38/// [Winsock]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsapoll
39/// [FreeBSD]: https://man.freebsd.org/cgi/man.cgi?query=poll&sektion=2
40/// [NetBSD]: https://man.netbsd.org/poll.2
41/// [OpenBSD]: https://man.openbsd.org/poll.2
42/// [DragonFly BSD]: https://man.dragonflybsd.org/?command=poll&section=2
43/// [illumos]: https://illumos.org/man/2/poll
44#[inline]
45pub fn poll(fds: &mut [PollFd<'_>], timeout: Option<&Timespec>) -> io::Result<usize> {
46    backend::event::syscalls::poll(fds, timeout)
47}