Commit | Line | Data |
---|---|---|
da268306 KB |
1 | .\" Copyright (c) 1983 The Regents of the University of California. |
2 | .\" All rights reserved. | |
0f4ff25c | 3 | .\" |
da268306 KB |
4 | .\" Redistribution and use in source and binary forms are permitted |
5 | .\" provided that the above copyright notice and this paragraph are | |
6 | .\" duplicated in all such forms and that any documentation, | |
7 | .\" advertising materials, and other materials related to such | |
8 | .\" distribution and use acknowledge that the software was developed | |
9 | .\" by the University of California, Berkeley. The name of the | |
10 | .\" University may not be used to endorse or promote products derived | |
11 | .\" from this software without specific prior written permission. | |
12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
14 | .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
15 | .\" | |
16 | .\" @(#)select.2 6.6 (Berkeley) %G% | |
0f4ff25c | 17 | .\" |
a4c6a717 | 18 | .TH SELECT 2 "" |
0f4ff25c KM |
19 | .UC 5 |
20 | .SH NAME | |
3dc1a400 | 21 | select \- synchronous I/O multiplexing |
0f4ff25c KM |
22 | .SH SYNOPSIS |
23 | .nf | |
24 | .ft B | |
71f64171 | 25 | #include <sys/types.h> |
0f4ff25c KM |
26 | #include <sys/time.h> |
27 | .PP | |
28 | .ft B | |
a4c6a717 | 29 | nfound = select(nfds, readfds, writefds, exceptfds, timeout) |
71f64171 DS |
30 | int nfound, nfds; |
31 | fd_set *readfds, *writefds, *exceptfds; | |
0f4ff25c | 32 | struct timeval *timeout; |
71f64171 DS |
33 | .PP |
34 | .ft B | |
71f64171 DS |
35 | FD_SET(fd, &fdset) |
36 | FD_CLR(fd, &fdset) | |
37 | FD_ISSET(fd, &fdset) | |
38 | FD_ZERO(&fdset) | |
3dc1a400 MK |
39 | int fd; |
40 | fd_set fdset; | |
0f4ff25c KM |
41 | .fi |
42 | .SH DESCRIPTION | |
43 | .I Select | |
3dc1a400 | 44 | examines the I/O descriptor sets whose addresses are passed in |
0f4ff25c KM |
45 | .IR readfds , |
46 | .IR writefds , | |
47 | and | |
a4c6a717 | 48 | .I exceptfds |
71f64171 DS |
49 | to see if some of their descriptors |
50 | are ready for reading, are ready for writing, or have an exceptional | |
0f4ff25c | 51 | condition pending, respectively. |
71f64171 DS |
52 | The first |
53 | .I nfds | |
54 | descriptors are checked in each set; | |
55 | i.e. the descriptors from 0 through | |
0f4ff25c | 56 | .IR nfds -1 |
71f64171 DS |
57 | in the descriptor sets are examined. |
58 | On return, | |
59 | .I select | |
60 | replaces the given descriptor sets | |
3dc1a400 MK |
61 | with subsets consisting of those descriptors that are ready |
62 | for the requested operation. | |
71f64171 | 63 | The total number of ready descriptors in all the sets is returned in |
0f4ff25c KM |
64 | .IR nfound . |
65 | .PP | |
3dc1a400 MK |
66 | The descriptor sets are stored as bit fields in arrays of integers. |
67 | The following macros are provided for manipulating such descriptor sets: | |
71f64171 DS |
68 | .I "FD_ZERO(&fdset)" |
69 | initializes a descriptor set | |
70 | .I fdset | |
71 | to the null set. | |
72 | .I "FD_SET(fd, &fdset)" | |
73 | includes a particular descriptor | |
74 | .I fd | |
75 | in | |
76 | .IR fdset . | |
77 | .I "FD_CLR(fd, &fdset)" | |
78 | removes | |
79 | .I fd | |
80 | from | |
81 | .IR fdset . | |
82 | .I "FD_ISSET(fd, &fdset)" | |
83 | is nonzero if | |
84 | .I fd | |
85 | is a member of | |
86 | .IR fdset , | |
87 | zero otherwise. | |
88 | The behavior of these macros is undefined if | |
89 | a descriptor value is less than zero or greater than or equal to | |
90 | .IR FD_SETSIZE , | |
91 | which is normally at least equal | |
92 | to the maximum number of descriptors supported by the system. | |
93 | .PP | |
0f4ff25c KM |
94 | If |
95 | .I timeout | |
96 | is a non-zero pointer, it specifies a maximum interval to wait for the | |
97 | selection to complete. If | |
98 | .I timeout | |
99 | is a zero pointer, the select blocks indefinitely. To affect a poll, the | |
100 | .I timeout | |
3dc1a400 | 101 | argument should be non-zero, pointing to a zero-valued timeval structure. |
0f4ff25c KM |
102 | .PP |
103 | Any of | |
104 | .IR readfds , | |
105 | .IR writefds , | |
106 | and | |
a4c6a717 | 107 | .I exceptfds |
71f64171 | 108 | may be given as zero pointers if no descriptors are of interest. |
0f4ff25c KM |
109 | .SH "RETURN VALUE |
110 | .I Select | |
71f64171 DS |
111 | returns the number of ready descriptors that are contained in |
112 | the descriptor sets, | |
0f4ff25c KM |
113 | or \-1 if an error occurred. |
114 | If the time limit expires then | |
115 | .I select | |
116 | returns 0. | |
3dc1a400 MK |
117 | If |
118 | .I select | |
119 | returns with an error, | |
120 | including one due to an interrupted call, | |
121 | the descriptor sets will be unmodified. | |
0f4ff25c KM |
122 | .SH "ERRORS |
123 | An error return from \fIselect\fP indicates: | |
124 | .TP 15 | |
125 | [EBADF] | |
71f64171 | 126 | One of the descriptor sets specified an invalid descriptor. |
0f4ff25c KM |
127 | .TP 15 |
128 | [EINTR] | |
da051635 SS |
129 | A signal was delivered before the time limit expired and |
130 | before any of the selected events occurred. | |
131 | .TP 15 | |
132 | [EINVAL] | |
71f64171 | 133 | The specified time limit is invalid. One of its components is |
da051635 | 134 | negative or too large. |
0f4ff25c | 135 | .SH SEE ALSO |
a4c6a717 | 136 | accept(2), connect(2), read(2), write(2), recv(2), send(2), getdtablesize(2) |
0f4ff25c | 137 | .SH BUGS |
3dc1a400 MK |
138 | Although the provision of |
139 | .IR getdtablesize (2) | |
140 | was intended to allow user programs to be written independent | |
141 | of the kernel limit on the number of open files, the dimension | |
142 | of a sufficiently large bit field for select remains a problem. | |
143 | The default size FD_SETSIZE (currently 256) is somewhat larger than | |
144 | the current kernel limit to the number of open files. | |
a5c56ebf | 145 | However, in order to accommodate programs which might potentially |
3dc1a400 MK |
146 | use a larger number of open files with select, it is possible |
147 | to increase this size within a program by providing | |
148 | a larger definition of FD_SETSIZE before the inclusion of <sys/types.h>. | |
149 | .PP | |
150 | .I Select | |
151 | should probably return the time remaining from the original timeout, | |
152 | if any, by modifying the time value in place. | |
153 | This may be implemented in future versions of the system. | |
154 | Thus, it is unwise to assume that the timeout value will be unmodified | |
155 | by the | |
156 | .I select | |
157 | call. |