1port_get(3C) Standard C Library Functions port_get(3C)
2
6 port_get, port_getn - retrieve event information from a port
7
9 #include <port.h>
10 int port_get(int port, port_event_t *pe,
12 const timespec_t *timeout);
13 int port_getn(int port, port_event_t list[], uint_t max,
16 uint_t *nget, const timespec_t *timeout);
17
20 The port_get() and port_getn() functions retrieve events from a port.
21 The port_get() function retrieves at most a single event. The
22 port_getn() function can retrieve multiple events.
23 The pe argument points to an uninitialized port_event_t structure that
26 is filled in by the system when the port_get() function returns suc‐
27 cessfully.
28 The port_event_t structure contains the following members:
31 int portev_events; /* detected events */
33 ushort_t portev_source; /* event source */
34 uintptr_t portev_object; /* specific to event source */
35 void *portev_user; /* user defined cookie */
36 The portev_events and portev_object members are specific to the event
40 source. The portev_events denotes the delivered events. The
41 portev_object refers to the associated object (see port_create(3C)).
42 The portev_source member specifies the source of the event. The
43 portev_user member is a user-specified value.
44 If the timeout pointer is NULL, the port_get() function blocks until an
47 event is available. To poll for an event without waiting, timeout
48 should point to a zeroed timespec. A non-zeroed timespec specifies the
49 desired time to wait for events. The port_get() function returns before
50 the timeout elapses if an event is available, a signal occurs, a port
51 is closed by another thread, or the port is in or enters alert mode.
52 See port_alert(3C) for details on alert mode.
53 The port_getn() function can retrieve multiple events from a port. The
56 list argument is an array of uninitialized port_event_t structures that
57 is filled in by the system when the port_getn() function returns suc‐
58 cesfully. The nget argument points to the desired number of events to
59 be retrieved. The max parameter specifies the maximum number of events
60 that can be returned in list[]. If max is 0, the value pointed to by
61 nget is set to the number of events available on the port. The
62 port_getn() function returns immediately but no events are retrieved.
63 The port_getn() function block until the desired number of events are
66 available, the timeout elapses, a signal occurs, a port is closed by
67 another thread, or the port is in or enters alert mode.
68 On return, the value pointed to by nget is updated to the actual number
71 of events retrieved in list.
72 Threads calling the port_get() function might starve threads waiting in
75 the port_getn() function for more than one event. Similarly, threads
76 calling the port_getn() function for n events might starve threads
77 waiting in the port_getn() function for more than n events.
78 The port_get() and the port_getn() functions ignore non-shareable
81 events (see port_create(3C)) generated by other processes.
82
84 Upon succesful completion, 0 is returned. Otherwise, -1 is returned and
85 errno is set to indicate the error.
86
88 The port_get() and port_getn() functions will fail if:
89 EBADF The port identifier is not valid.
91 EBADFD The port argument is not an event port file descriptor.
94 EFAULT Event or event list can not be delivered (list[] pointer
97 and/or user space reserved to accomodate the list of events
98 is not reasonable), or the timeout argument is not reason‐
99 able.
100 EINTR A signal was caught during the execution of the function.
103 EINVAL The timeout element tv_sec is < 0 or the timeout element
106 tv_nsec is < 0 or > 1000000000.
107 ETIME The time interval expired before the expected number of
110 events have been posted to the port.
111 The port_getn() function will fail if:
115 EINVAL The list[] argument is NULL, the nget argument is NULL, or
117 the content of nget is > max and max is > 0.
118 EFAULT The timeout argument is not reasonable.
121 ETIME The time interval expired before the expected number of
124 events have been posted to the port (original value in nget),
125 or nget is updated with the number of returned port_event_t
126 structures in list[].
127
130 Example 1 Send a user event (PORT_SOURCE_USER) to a port and retrieve
131 it with port_get().
132 The following example sends a user event (PORT_SOURCE_USER) to a port
135 and retrieves it with port_get(). The portev_user and portev_events
136 members of the port_event_t structure are the same as the corresponding
137 user and events arguments of the port_send(3C) function.
138 #include <port.h>
141 int myport;
143 port_event_t pe;
144 struct timespec timeout;
145 int ret;
146 void *user;
147 uintptr_t object;
148 myport = port_create();
150 if (myport < 0) {
151 /* port creation failed ... */
152 ...
153 return(...);
154 }
155 ...
156 events = 0x01; /* own event definition(s) */
157 object = <myobject>;
158 user = <my_own_value>;
159 ret = port_send(myport, events, user);
160 if (ret == -1) {
161 /* error detected ... */
162 ...
163 close(myport);
164 return (...);
165 }
166 /*
168 * The following code could also be executed in another thread or
169 * process.
170 */
171 timeout.tv_sec = 1; /* user defined */
172 timeout.tv_nsec = 0;
173 ret = port_get(myport, &pe, &timeout);
174 if (ret == -1) {
175 /*
176 * error detected :
177 * - EINTR or ETIME : log error code and try again ...
178 * - Other kind of errors : may have to close the port ...
179 */
180 return(...);
181 }
182 /*
184 * After port_get() returns successfully, the port_event_t
185 * structure will be filled with:
186 * pe.portev_source = PORT_SOURCE_USER
187 * pe.portev_events = 0x01
188 * pe.portev_object = <myobject>
189 * pe.portev_user = <my_own_value>
190 */
191 ...
192 close(myport);
193
196 See attributes(5) for descriptions of the following attributes:
197 ┌─────────────────────────────┬─────────────────────────────┐
202 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
203 ├─────────────────────────────┼─────────────────────────────┤
204 │Architecture │all │
205 ├─────────────────────────────┼─────────────────────────────┤
206 │Availability │SUNWcsr, SUNWhea │
207 ├─────────────────────────────┼─────────────────────────────┤
208 │Interface Stability │Evolving │
209 ├─────────────────────────────┼─────────────────────────────┤
210 │MT-Level │Safe │
211 └─────────────────────────────┴─────────────────────────────┘
212
214 port_alert(3C), port_associate(3C), port_create(3C), port_send(3C),
215 attributes(5)
216SunOS 5.11 31 Jan 2007 port_get(3C)