X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/8ad349bb6ed4a0be06e34c92be0d98b92e078db4..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/bsd/man/man2/poll.2?ds=inline diff --git a/bsd/man/man2/poll.2 b/bsd/man/man2/poll.2 index a0445eff4..c0fa79ea2 100644 --- a/bsd/man/man2/poll.2 +++ b/bsd/man/man2/poll.2 @@ -1,31 +1,24 @@ .\" .\" Copyright (c) 2005 Apple Computer, Inc. All rights reserved. .\" -.\" @APPLE_LICENSE_OSREFERENCE_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 -.\" Version 2.0 (the "License"). You may not use this file except in -.\" compliance with the License. The rights granted to you under the -.\" License may not be used to create, or enable the creation or -.\" redistribution of, unlawful or unlicensed copies of an Apple operating -.\" system, or to circumvent, violate, or enable the circumvention or -.\" violation of, any terms of an Apple operating system software license -.\" agreement. +.\" @APPLE_LICENSE_HEADER_START@ .\" -.\" Please obtain a copy of the License at -.\" http://www.opensource.apple.com/apsl/ and read it before using this +.\" This file contains Original Code and/or Modifications of Original Code +.\" as defined in and that are subject to the Apple Public Source License +.\" Version 2.0 (the 'License'). You may not use this file except in +.\" compliance with the License. Please obtain a copy of the License at +.\" http://www.opensource.apple.com/apsl/ and read it before using this .\" file. .\" -.\" The Original Code and all software distributed under the License are -.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER -.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, -.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, -.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. -.\" Please see the License for the specific language governing rights and +.\" The Original Code and all software distributed under the License are +.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER +.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, +.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, +.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. +.\" Please see the License for the specific language governing rights and .\" limitations under the License. .\" -.\" @APPLE_LICENSE_OSREFERENCE_HEADER_END@ +.\" @APPLE_LICENSE_HEADER_END@ .\" .\" .\" Copyright (c) 1996 Charles M. Hannum. All rights reserved. @@ -55,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 @@ -64,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 @@ -89,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 @@ -104,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 @@ -154,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 @@ -165,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 @@ -191,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 , @@ -202,4 +225,3 @@ The .Fn poll function call appeared in .At V . -