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