[src/trunk]: src/lib/libc/sys bring in openbsd BUGS section (modulo some stro...

[itojun <itojun%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6ef6058b82dd
branches:  trunk
changeset: 535085:6ef6058b82dd
user:      itojun <itojun%NetBSD.org@localhost>
date:      Sat Aug 10 01:04:19 2002 +0000

description:
bring in openbsd BUGS section (modulo some strong wording).  nroff nits

diffstat:

 lib/libc/sys/select.2 |  93 +++++++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 79 insertions(+), 14 deletions(-)

diffs (132 lines):

diff -r 3db974adf6d8 -r 6ef6058b82dd lib/libc/sys/select.2
--- a/lib/libc/sys/select.2     Sat Aug 10 00:48:35 2002 +0000
+++ b/lib/libc/sys/select.2     Sat Aug 10 01:04:19 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: select.2,v 1.15 2002/02/08 01:28:21 ross Exp $
+.\"    $NetBSD: select.2,v 1.16 2002/08/10 01:04:19 itojun Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -106,11 +106,19 @@
 If
 .Fa timeout
 is a non-nil pointer, it specifies a maximum interval to wait for the
-selection to complete.  If
+selection to complete.
+If
 .Fa timeout
-is a nil pointer, the select blocks indefinitely.  To affect a poll, the
+is a nil pointer, the select blocks indefinitely.
+To affect a poll, the
 .Fa timeout
 argument should be non-nil, pointing to a zero-valued timeval structure.
+.Fa timeout
+is not changed by
+.Fn select ,
+and may be reused on subsequent calls; however, it is good style to
+re-initialize it before each invocation of
+.Fn select .
 .Pp
 Any of
 .Fa readfds ,
@@ -149,8 +157,8 @@
 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.
+The specified time limit is invalid.
+One of its components is negative or too large.
 .El
 .Sh SEE ALSO
 .Xr accept 2 ,
@@ -173,10 +181,13 @@
 was intended to allow user programs to be written independent
 of the kernel limit on the number of open files, the dimension
 of a sufficiently large bit field for select remains a problem.
-The default size
+The default bit size of
+.Ft fd_set
+is based on the symbol
 .Dv FD_SETSIZE
-(currently 256) is somewhat larger than
-the current kernel limit to the number of open files.
+(currently 256),
+but that is somewhat smaller than the current kernel limit
+to the number of open files.
 However, in order to accommodate programs which might potentially
 use a larger number of open files with select, it is possible
 to increase this size within a program by providing
@@ -184,12 +195,66 @@
 .Dv FD_SETSIZE
 before the inclusion of
 .Aq Pa sys/types.h .
+The kernel will cope, and the userland libraries provided with the
+system are also ready for large numbers of file descriptors.
+.Pp
+Alternatively, to be really safe, it is possible to allocate
+.Ft fd_set
+bit-arrays dynamically.
+The idea is to permit a program to work properly even if it is
+.Xr execve 2 Ns 'd
+with 4000 file descriptors pre-allocated.
+The following illustrates the technique which is used by
+userland libraries:
+.Pp
+.Bd -literal -offset indent -compact
+       fd_set *fdsr;
+       int max = fd;
+
+       fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
+           sizeof(fd_mask));
+       if (fdsr == NULL) {
+               ...
+               return (-1);
+       }
+       FD_SET(fd, fdsr);
+       n = select(max+1, fdsr, NULL, NULL, &tv);
+       ...
+       free(fdsr);
+.Ed
+.Pp
+Alternatively, it is possible to use the
+.Xr poll 2
+interface.
+.Xr poll 2
+is more efficient when the size of
+.Fn select Ns 's
+.Ft fd_set
+bit-arrays are very large, and for fixed numbers of
+file descriptors one need not size and dynamically allocate a
+memory object.
 .Pp
 .Fn select
-should probably return the time remaining from the original timeout,
-if any, by modifying the time value in place.
-This may be implemented in future versions of the system.
-Thus, it is unwise to assume that the timeout value will be unmodified
-by the
+should probably have been designed to return the time remaining from the
+original timeout, if any, by modifying the time value in place.
+Even though some systems stupidly act in this different way, it is
+unlikely this semantic will ever be commonly implemented, as the
+change causes massive source code compatibility problems.
+Furthermore, recent new standards have dictated the current behaviour.
+In general, due to the existence of those
+non-conforming systems, it is unwise to assume that the timeout
+value will be unmodified by the
 .Fn select
-call.
+call, and the caller should reinitialize it on each invocation.
+Calculating the delta is easily done by calling
+.Xr gettimeofday 2
+before and after the call to
+.Fn select Ns ,
+and using
+.Fn timersub
+(as described in
+.Xr getitimer 2 ) .
+.Pp
+Internally to the kernel,
+.Fn select
+works poorly if multiple processes wait on the same file descriptor.