xnu-2782.30.5.tar.gz

[apple/xnu.git] / bsd / man / man2 / select.2

diff --git a/bsd/man/man2/select.2 b/bsd/man/man2/select.2
index 39fd5d84b449fe7f7d063ed61b5e100d5e43a908..eeb8aceb8e467e3203afae274e6ee8b9476352ca 100644 (file)
--- a/bsd/man/man2/select.2
+++ b/bsd/man/man2/select.2
@@ -37,27 +37,55 @@
 .Dt SELECT 2
 .Os BSD 4.2
 .Sh NAME
+.Nm FD_CLR ,
+.Nm FD_COPY ,
+.Nm FD_ISSET ,
+.Nm FD_SET ,
+.Nm FD_ZERO ,
 .Nm select
 .Nd synchronous I/O multiplexing
 .Sh SYNOPSIS
 .Fd #include <sys/select.h>
-.D1 "- or -"
-.Fd #include <sys/types.h>
-.Fd #include <sys/time.h>
-.Fd #include <unistd.h>
+.\"
+.Ft void
+.Fo FD_CLR
+.Fa fd
+.Fa "fd_set *fdset"
+.Fc
+.Ft void
+.Fo FD_COPY
+.Fa "fd_set *fdset_orig"
+.Fa "fd_set *fdset_copy"
+.Fc
 .Ft int
-.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout"
-.Fn FD_SET fd &fdset
-.Fn FD_CLR fd &fdset
-.Fn FD_ISSET fd &fdset
-.Fn FD_ZERO &fdset
+.Fo FD_ISSET
+.Fa fd
+.Fa "fd_set *fdset"
+.Fc
+.Ft void
+.Fo FD_SET
+.Fa fd
+.Fa "fd_set *fdset"
+.Fc
+.Ft void
+.Fo FD_ZERO
+.Fa "fd_set *fdset"
+.Fc
+.Ft int
+.Fo select
+.Fa "int nfds"
+.Fa "fd_set *restrict readfds"
+.Fa "fd_set *restrict writefds"
+.Fa "fd_set *restrict errorfds"
+.Fa "struct timeval *restrict timeout"
+.Fc
 .Sh DESCRIPTION
 .Fn Select
 examines the I/O descriptor sets whose addresses are passed in
 .Fa readfds ,
 .Fa writefds ,
 and
-.Fa exceptfds
+.Fa errorfds
 to see if some of their descriptors
 are ready for reading, are ready for writing, or have an exceptional
 condition pending, respectively.
@@ -66,7 +94,9 @@ The first
 descriptors are checked in each set;
 i.e., the descriptors from 0 through
 .Fa nfds Ns No -1
-in the descriptor sets are examined.
+in the descriptor sets are examined.  (Example: If you have set two file descriptors "4" and "17",
+.Fa nfds
+should  not be "2", but rather "17 + 1" or "18".)
 On return,
 .Fn select
 replaces the given descriptor sets
@@ -97,6 +127,11 @@ is non-zero if
 is a member of
 .Fa fdset ,
 zero otherwise.
+.Fn FD_COPY &fdset_orig &fdset_copy
+replaces an already allocated 
+.Fa &fdset_copy
+file descriptor set with a copy of
+.Fa &fdset_orig .
 The behavior of these macros is undefined if
 a descriptor value is less than zero or greater than or equal to
 .Dv FD_SETSIZE ,
@@ -122,7 +157,7 @@ Any of
 .Fa readfds ,
 .Fa writefds ,
 and
-.Fa exceptfds
+.Fa errorfds
 may be given as nil pointers if no descriptors are of interest.
 .Sh RETURN VALUES
 .Fn Select
@@ -136,21 +171,74 @@ If
 .Fn select
 returns with an error,
 including one due to an interrupted call,
-the descriptor sets will be unmodified.
+the descriptor sets will be unmodified and the global variable
+.Va errno
+will be set to indicate the error.
 .Sh ERRORS
 An error return from
 .Fn select
 indicates:
 .Bl -tag -width Er
+.\" ===========
+.It Bq Er EAGAIN
+The kernel was (perhaps temporarily) unable
+to allocate the requested number of file descriptors.
+.\" ===========
 .It Bq Er EBADF
 One of the descriptor sets specified an invalid descriptor.
+.\" ===========
 .It Bq Er EINTR
 A signal was delivered before the time limit expired and
 before any of the selected events occurred.
+.\" ===========
 .It Bq Er EINVAL
 The specified time limit is invalid.  One of its components is
 negative or too large.
+.\" ===========
+.It Bq Er EINVAL
+.Fa ndfs
+is greater than FD_SETSIZE and _DARWIN_UNLIMITED_SELECT is not defined.
 .El
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/select.h>
+.D1 "- or -"
+.Fd #include <sys/types.h>
+.Fd #include <sys/time.h>
+.Fd #include <unistd.h>
+.Pp
+.Fo FD_SET
+.Fa fd
+.Fa &fdset
+.Fc ;
+.Pp
+.Fo FD_CLR
+.Fa fd
+.Fa &fdset
+.Fc ;
+.Pp
+.Fo FD_ISSET
+.Fa fd
+.Fa &fdset
+.Fc ;
+.Pp
+.Fo FD_COPY
+.Fa &fdset_orig
+.Fa &fdset_copy
+.Fc ;
+.Pp
+.Fo FD_ZERO
+.Fa &fdset
+.Fc ;
+.Sh COMPATIBILITY
+.Fn select
+now returns with
+.Va errno
+set to EINVAL when 
+.Fa nfds  
+is greater than FD_SETSIZE.
+Use a smaller value for
+.Fa nfds  
+or compile with -D_DARWIN_UNLIMITED_SELECT.
 .Sh SEE ALSO
 .Xr accept 2 ,
 .Xr connect 2 ,
@@ -159,7 +247,8 @@ negative or too large.
 .Xr read 2 ,
 .Xr recv 2 ,
 .Xr send 2 ,
-.Xr write 2
+.Xr write 2 ,
+.Xr compat 5
 .Sh BUGS
 Although the provision of
 .Xr getdtablesize 2