| poll.2 (131365) | poll.2 (131504) |
|---|---|
| 1.\" $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $ | 1.\" $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $ |
| 2.\" $FreeBSD: head/lib/libc/sys/poll.2 131365 2004-06-30 20:09:10Z ru $ | 2.\" $FreeBSD: head/lib/libc/sys/poll.2 131504 2004-07-02 23:52:20Z ru $ |
| 3.\" 4.\" Copyright (c) 1996 Charles M. Hannum. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. --- 34 unchanged lines hidden (view full) --- 45.Fn poll 46system call 47examines a set of file descriptors to see if some of them are ready for 48I/O. 49The 50.Fa fds 51argument is a pointer to an array of pollfd structures as defined in 52.In poll.h | 3.\" 4.\" Copyright (c) 1996 Charles M. Hannum. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. --- 34 unchanged lines hidden (view full) --- 45.Fn poll 46system call 47examines a set of file descriptors to see if some of them are ready for 48I/O. 49The 50.Fa fds 51argument is a pointer to an array of pollfd structures as defined in 52.In poll.h |
| 53(shown below). The | 53(shown below). 54The |
| 54.Fa nfds 55argument determines the size of the 56.Fa fds 57array. 58.Bd -literal 59struct pollfd { 60 int fd; /* file descriptor */ 61 short events; /* events to look for */ 62 short revents; /* events returned */ 63}; 64.Ed 65.Pp 66The fields of 67.Fa struct pollfd 68are as follows: 69.Bl -tag -width XXXrevents 70.It fd | 55.Fa nfds 56argument determines the size of the 57.Fa fds 58array. 59.Bd -literal 60struct pollfd { 61 int fd; /* file descriptor */ 62 short events; /* events to look for */ 63 short revents; /* events returned */ 64}; 65.Ed 66.Pp 67The fields of 68.Fa struct pollfd 69are as follows: 70.Bl -tag -width XXXrevents 71.It fd |
| 71File descriptor to poll. If fd is equal to -1 then | 72File descriptor to poll. 73If fd is equal to -1 then |
| 72.Fa revents 73is cleared (set to zero), and that pollfd is not checked. 74.It events | 74.Fa revents 75is cleared (set to zero), and that pollfd is not checked. 76.It events |
| 75Events to poll for. (See below.) | 77Events to poll for. 78(See below.) |
| 76.It revents | 79.It revents |
| 77Events which may occur. (See below.) | 80Events which may occur. 81(See below.) |
| 78.El 79.Pp 80The event bitmasks in 81.Fa events 82and 83.Fa revents 84have the following bits: 85.Bl -tag -width XXXPOLLWRNORM --- 6 unchanged lines hidden (view full) --- 92.It POLLPRI 93High priority data may be read without blocking. 94.It POLLOUT 95.It POLLWRNORM 96Normal data may be written without blocking. 97.It POLLWRBAND 98Data with a non-zero priority may be written without blocking. 99.It POLLERR | 82.El 83.Pp 84The event bitmasks in 85.Fa events 86and 87.Fa revents 88have the following bits: 89.Bl -tag -width XXXPOLLWRNORM --- 6 unchanged lines hidden (view full) --- 96.It POLLPRI 97High priority data may be read without blocking. 98.It POLLOUT 99.It POLLWRNORM 100Normal data may be written without blocking. 101.It POLLWRBAND 102Data with a non-zero priority may be written without blocking. 103.It POLLERR |
| 100An exceptional condition has occurred on the device or socket. This | 104An exceptional condition has occurred on the device or socket. 105This |
| 101flag is always checked, even if not present in the 102.Fa events 103bitmask. 104.It POLLHUP | 106flag is always checked, even if not present in the 107.Fa events 108bitmask. 109.It POLLHUP |
| 105The device or socket has been disconnected. This flag is always | 110The device or socket has been disconnected. 111This flag is always |
| 106checked, even if not present in the 107.Fa events | 112checked, even if not present in the 113.Fa events |
| 108bitmask. Note that | 114bitmask. 115Note that |
| 109POLLHUP 110and 111POLLOUT 112should never be present in the 113.Fa revents 114bitmask at the same time. 115.It POLLNVAL | 116POLLHUP 117and 118POLLOUT 119should never be present in the 120.Fa revents 121bitmask at the same time. 122.It POLLNVAL |
| 116The file descriptor is not open. This flag is always checked, even | 123The file descriptor is not open. 124This flag is always checked, even |
| 117if not present in the 118.Fa events 119bitmask. 120.El 121.Pp 122If 123.Fa timeout 124is neither zero nor INFTIM (-1), it specifies a maximum interval to | 125if not present in the 126.Fa events 127bitmask. 128.El 129.Pp 130If 131.Fa timeout 132is neither zero nor INFTIM (-1), it specifies a maximum interval to |
| 125wait for any file descriptor to become ready, in milliseconds. If | 133wait for any file descriptor to become ready, in milliseconds. 134If |
| 126.Fa timeout | 135.Fa timeout |
| 127is INFTIM (-1), the poll blocks indefinitely. If | 136is INFTIM (-1), the poll blocks indefinitely. 137If |
| 128.Fa timeout 129is zero, then 130.Fn poll 131will return without blocking. 132.Sh RETURN VALUES 133The 134.Fn poll 135system call 136returns the number of descriptors that are ready for I/O, or -1 if an | 138.Fa timeout 139is zero, then 140.Fn poll 141will return without blocking. 142.Sh RETURN VALUES 143The 144.Fn poll 145system call 146returns the number of descriptors that are ready for I/O, or -1 if an |
| 137error occurred. If the time limit expires, | 147error occurred. 148If the time limit expires, |
| 138.Fn poll 139returns 0. 140If 141.Fn poll 142returns with an error, 143including one due to an interrupted system call, 144the 145.Fa fds 146array will be unmodified. 147.Sh COMPATIBILITY 148This implementation differs from the historical one in that a given 149file descriptor may not cause 150.Fn poll | 149.Fn poll 150returns 0. 151If 152.Fn poll 153returns with an error, 154including one due to an interrupted system call, 155the 156.Fa fds 157array will be unmodified. 158.Sh COMPATIBILITY 159This implementation differs from the historical one in that a given 160file descriptor may not cause 161.Fn poll |
| 151to return with an error. In cases where this would have happened in 152the historical implementation (e.g. trying to poll a | 162to return with an error. 163In cases where this would have happened in 164the historical implementation (e.g.\& trying to poll a |
| 153.Xr revoke 2 Ns ed 154descriptor), this implementation instead copies the 155.Fa events 156bitmask to the 157.Fa revents | 165.Xr revoke 2 Ns ed 166descriptor), this implementation instead copies the 167.Fa events 168bitmask to the 169.Fa revents |
| 158bitmask. Attempting to perform I/O on this descriptor will then 159return an error. This behaviour is believed to be more useful. | 170bitmask. 171Attempting to perform I/O on this descriptor will then 172return an error. 173This behaviour is believed to be more useful. |
| 160.Sh ERRORS 161An error return from 162.Fn poll 163indicates: 164.Bl -tag -width Er 165.It Bq Er EFAULT 166The 167.Fa fds --- 14 unchanged lines hidden (view full) --- 182.Xr select 2 , 183.Xr send 2 , 184.Xr write 2 185.Sh BUGS 186The distinction between some of the fields in the 187.Fa events 188and 189.Fa revents | 174.Sh ERRORS 175An error return from 176.Fn poll 177indicates: 178.Bl -tag -width Er 179.It Bq Er EFAULT 180The 181.Fa fds --- 14 unchanged lines hidden (view full) --- 196.Xr select 2 , 197.Xr send 2 , 198.Xr write 2 199.Sh BUGS 200The distinction between some of the fields in the 201.Fa events 202and 203.Fa revents |
| 190bitmasks is really not useful without STREAMS. The fields are | 204bitmasks is really not useful without STREAMS. 205The fields are |
| 191defined for compatibility with existing software. 192.Sh HISTORY 193The 194.Fn poll 195function appeared in 196.At V . 197This manual page and the core of the implementation was taken from 198.Nx . | 206defined for compatibility with existing software. 207.Sh HISTORY 208The 209.Fn poll 210function appeared in 211.At V . 212This manual page and the core of the implementation was taken from 213.Nx . |