From 22f348ca27ab76281e20ee3bcba81ab7c54944b7 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Thu, 20 Apr 2006 21:21:42 +0000 Subject: [PATCH] Note more clearly that fd_set args can be NULL; various other minor edits and ffixes --- man2/select.2 | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/man2/select.2 b/man2/select.2 index be7abe1ad..6901260b4 100644 --- a/man2/select.2 +++ b/man2/select.2 @@ -105,7 +105,8 @@ argument, and behaves as called with NULL .IR sigmask . .PP -Three independent sets of descriptors are watched. Those listed in +Three independent sets of file descriptors are watched. +Those listed in .I readfds will be watched to see if characters become available for reading (more precisely, to see if a read will not @@ -116,7 +117,10 @@ will be watched to see if a write will not block, and those in .I exceptfds will be watched for exceptions. On exit, the sets are modified in place -to indicate which descriptors actually changed status. +to indicate which file descriptors actually changed status. +Each of the three file descriptor sets may be specified as NULL +if no file descriptors are to be watched for the corresponding class +of events. .PP Four macros are provided to manipulate the sets. .BR FD_ZERO () @@ -124,14 +128,15 @@ clears a set. .BR FD_SET () and .BR FD_CLR () -respectively add and remove a given descriptor from a set. +respectively add and remove a given file descriptor from a set. .BR FD_ISSET () -tests to see if a descriptor is part of the set; this is useful after +tests to see if a file descriptor is part of the set; +this is useful after .BR select () returns. .PP .I n -is the highest-numbered descriptor in any of the three sets, plus 1. +is the highest-numbered file descriptor in any of the three sets, plus 1. .PP .I timeout is an upper bound on the amount of time elapsed before @@ -226,7 +231,7 @@ Some code calls .BR select () with all three sets empty, .I n -zero, and a non-null +zero, and a non-NULL .I timeout as a fairly portable way to sleep with subsecond precision. .PP @@ -256,8 +261,8 @@ On success, .BR select () and .BR pselect () -return the number of descriptors contained in the three returned -descriptor sets (that is, the total number of one bits in +return the number of file descriptors contained in the three returned +descriptor sets (that is, the total number of bits that are set in .IR readfds , .IR writefds , .IR exceptfds ) @@ -331,7 +336,14 @@ sets the timeout variable before exit, but the BSD variant does not. is defined in IEEE Std 1003.1g-2000 (POSIX.1g), and in POSIX 1003.1-2001. .SH NOTES -An fd_set is a fixed size buffer. Executing FD_CLR or FD_SET with a value of +An +.I fd_set +is a fixed size buffer. +Executing +.BR FD_CLR () +or +.BR FD_SET () +with a value of .I fd that is negative or is equal to or larger than FD_SETSIZE will result in undefined behavior. Moreover, POSIX requires @@ -339,8 +351,10 @@ in undefined behavior. Moreover, POSIX requires to be a valid file descriptor. Concerning the types involved, the classical situation is that -the two fields of a struct timeval are longs (as shown above), -and the struct is defined in +the two fields of a +.I timeval +structure are longs (as shown above), +and the structure is defined in .IR . The POSIX 1003.1-2001 situation is @@ -353,9 +367,13 @@ struct timeval { .fi .RE -where the struct is defined in +where the structure is defined in .I -and the data types time_t and suseconds_t are defined in +and the data types i +.I time_t +and +.I suseconds_t +are defined in .IR . .LP Concerning prototypes, the classical situation is that one should