X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/21362eb3e66fd2c787aee132bce100a44d71a99c..cb3231590a3c94ab4375e2228bd5e86b0cf1ad7e:/bsd/man/man2/poll.2?ds=sidebyside diff --git a/bsd/man/man2/poll.2 b/bsd/man/man2/poll.2 index 7bae4dda4..c0fa79ea2 100644 --- a/bsd/man/man2/poll.2 +++ b/bsd/man/man2/poll.2 @@ -1,7 +1,7 @@ .\" .\" Copyright (c) 2005 Apple Computer, Inc. All rights reserved. .\" -.\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@ +.\" @APPLE_LICENSE_HEADER_START@ .\" .\" This file contains Original Code and/or Modifications of Original Code .\" as defined in and that are subject to the Apple Public Source License @@ -18,7 +18,7 @@ .\" Please see the License for the specific language governing rights and .\" limitations under the License. .\" -.\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@ +.\" @APPLE_LICENSE_HEADER_END@ .\" .\" .\" Copyright (c) 1996 Charles M. Hannum. All rights reserved. @@ -48,7 +48,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd February 27, 2005 +.Dd March 18, 2015 .Dt POLL 2 .Os .Sh NAME @@ -57,18 +57,24 @@ .Sh SYNOPSIS .In poll.h .Ft int -.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout" +.Fo poll +.Fa "struct pollfd fds[]" +.Fa "nfds_t nfds" +.Fa "int timeout" +.Fc .Sh DESCRIPTION -.Fn Poll -examines a set of file descriptors to see if some of them are ready for -I/O or if certain events have occurred on them. +.Fn poll +examines a set of file descriptors +to see if some of them are ready for I/O +or if certain events have occurred on them. The .Fa fds -argument is a pointer to an array of pollfd structures as defined in +argument is a pointer to an array of pollfd structures, +as defined in .Aq Pa poll.h (shown below). The .Fa nfds -argument determines the size of the +argument specifies the size of the .Fa fds array. .Bd -literal @@ -82,7 +88,7 @@ struct pollfd { The fields of .Fa struct pollfd are as follows: -.Bl -tag -width XXXrevents +.Bl -tag -width XXXPOLLWRNORM .It fd File descriptor to poll. .It events @@ -97,49 +103,63 @@ and .Fa revents have the following bits: .Bl -tag -width XXXPOLLWRNORM -.It POLLIN -Data other than high priority data may be read without blocking. -This is equivalent to ( POLLRDNORM | POLLRDBAND ). -.It POLLRDNORM -Normal data may be read without blocking. -.It POLLRDBAND -Priority data may be read without blocking. -.It POLLPRI -High priority data may be read without blocking. -.It POLLOUT -.It POLLWRNORM -Normal data may be written without blocking. -.It POLLWRBAND -Priority data may be written without blocking. +.\" =========== .It POLLERR -An exceptional condition has occurred on the device or socket. This -flag is output only, and ignored if present in the input +An exceptional condition has occurred on the device or socket. +This flag is output only, and ignored if present in the input .Fa events bitmask. +.\" =========== .It POLLHUP -The device or socket has been disconnected. This flag is output only, +The device or socket has been disconnected. +This flag is output only, and ignored if present in the input .Fa events -bitmask. Note that -POLLHUP -and -POLLOUT +bitmask. +Note that POLLHUP and POLLOUT are mutually exclusive and should never be present in the .Fa revents bitmask at the same time. +.\" =========== +.It POLLIN +Data other than high priority data may be read without blocking. +This is equivalent to ( POLLRDNORM | POLLRDBAND ). +.\" =========== .It POLLNVAL -The file descriptor is not open. This flag is output only, and ignored if present in the input +The file descriptor is not open. +This flag is output only, and ignored if present in the input .Fa events bitmask. +.\" =========== +.It POLLOUT +Normal data may be written without blocking. +This is equivalent to POLLWRNORM. +.\" =========== +.It POLLPRI +High priority data may be read without blocking. +.\" =========== +.It POLLRDBAND +Priority data may be read without blocking. +.\" =========== +.It POLLRDNORM +Normal data may be read without blocking. +.\" =========== +.It POLLWRBAND +Priority data may be written without blocking. +.\" =========== +.It POLLWRNORM +Normal data may be written without blocking. .El .Pp -The distinction between normal, priority, and high-priority data is file type -or device specific. +The distinction between normal, priority, and high-priority data +is specific to particular file types or devices. .Pp If .Fa timeout -is greater than zero, it specifies a maximum interval to -wait for any file descriptor to become ready, in milliseconds. If +is greater than zero, +it specifies a maximum interval (in milliseconds) +to wait for any file descriptor to become ready. +If .Fa timeout is zero, then .Fn poll @@ -147,9 +167,10 @@ will return without blocking. If the value of .Fa timeout is -1, the poll blocks indefinitely. .Sh RETURN VALUES -.Fn Poll -returns the number of descriptors that are ready for I/O, or -1 if an -error occured. If the time limit expires, +.Fn poll +returns the number of descriptors that are ready for I/O, +or -1 if an error occurred. +If the time limit expires, .Fn poll returns 0. If @@ -158,22 +179,30 @@ returns with an error, including one due to an interrupted call, the .Fa fds -array will be unmodified. +array will be unmodified and the global variable +.Va errno +will be set to indicate the error. .Sh ERRORS -An error return from .Fn poll -indicates: +will fail if: .Bl -tag -width Er +.\" =========== +.It Bq Er EAGAIN +Allocation of internal data structures fails. +A subsequent request may succeed. +.\" =========== .It Bq Er EFAULT .Fa Fds points outside the process's allocated address space. +.\" =========== .It Bq Er EINTR -A signal was delivered before the time limit expired and -before any of the selected events occurred. +A signal is delivered before the time limit expires +and before any of the selected events occurs. +.\" =========== .It Bq Er EINVAL The .Fa nfds -argument is greater than OPEN_MAX, or the +argument is greater than OPEN_MAX or the .Fa timeout argument is less than -1. .El @@ -184,6 +213,7 @@ system call currently does not support devices. .Sh SEE ALSO .Xr accept 2 , .Xr connect 2 , +.Xr connectx 2 , .Xr kevent 2 , .Xr read 2 , .Xr recv 2 , @@ -195,4 +225,3 @@ The .Fn poll function call appeared in .At V . -