X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/21362eb3e66fd2c787aee132bce100a44d71a99c..cb3231590a3c94ab4375e2228bd5e86b0cf1ad7e:/bsd/man/man2/poll.2

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 .
-