Print this page
6107 port_notify_t prefix mispelt in port_associate(3C)
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/port_associate.3c.man.txt
+++ new/usr/src/man/man3c/port_associate.3c.man.txt
1 1 PORT_ASSOCIATE(3C) Standard C Library Functions PORT_ASSOCIATE(3C)
2 2
3 3
4 4
5 5 NAME
6 6 port_associate, port_dissociate - associate or dissociate the object
7 7 with the port
8 8
9 9 SYNOPSIS
10 10 #include <port.h>
11 11
12 12 int port_associate(int port, int source, uintptr_t object,
13 13 int events, void *user);
14 14
15 15
16 16 int port_dissociate(int port, int source, uintptr_t object);
17 17
18 18
19 19 DESCRIPTION
20 20 The port_associate() function associates specific events of a given
21 21 object with a port. Only objects associated with a particular port are
22 22 able to generate events that can be retrieved using port_get(3C) or
23 23 port_getn(3C). The delivery event has its portev_user member set to the
24 24 value specified in the user parameter. If the specified object is
25 25 already associated with the specified port, the port_associate()
26 26 function serves to update the events and user arguments of the
27 27 association. The port_dissociate() function removes the association of
28 28 an object with a port.
29 29
30 30
|
↓ open down ↓ |
30 lines elided |
↑ open up ↑ |
31 31 The objects that can be associated with a port by way of the
32 32 port_associate() function are objects of type PORT_SOURCE_FD and
33 33 PORT_SOURCE_FILE. Objects of other types have type-specific association
34 34 mechanisms. A port_notify_t structure, defined in <port.h>, is used to
35 35 specify the event port and an application-defined cookie to associate
36 36 with these event sources. See port_create(3C) and signal.h(3HEAD).
37 37
38 38
39 39 The port_notify_t structure contains the following members:
40 40
41 - int portntfy_port; /* bind request(s) to port */
42 - void *portntfy_user; /* user defined cookie */
41 + int portnfy_port; /* bind request(s) to port */
42 + void *portnfy_user; /* user defined cookie */
43 43
44 44
45 45
46 46 Objects of type PORT_SOURCE_FD are file descriptors. The event types
47 47 for PORT_SOURCE_FD objects are described in poll(2). At most one event
48 48 notification will be generated per associated file descriptor. For
49 49 example, if a file descriptor is associated with a port for the
50 50 POLLRDNORM event and data is available on the file descriptor at the
51 51 time the port_associate() function is called, an event is immediately
52 52 sent to the port. If data is not yet available, one event is sent to
53 53 the port when data first becomes available.
54 54
55 55
56 56 When an event for a PORT_SOURCE_FD object is retrieved, the object no
57 57 longer has an association with the port. The event can be processed
58 58 without the possibility that another thread can retrieve a subsequent
59 59 event for the same object. After processing of the file descriptor is
60 60 completed, the port_associate() function can be called to reassociate
61 61 the object with the port.
62 62
63 63
64 64 Objects of type PORT_SOURCE_FILE are pointer to the structure file_obj
65 65 defined in <sys/port.h>. This event source provides event notification
66 66 when the specified file/directory is accessed, modified, truncated or
67 67 when its status changes. The path name of the file/directory to be
68 68 watched is passed in the struct file_obj along with the access,
69 69 modification, and change time stamps acquired from a stat(2) call. If
70 70 the file name is a symbolic link, it is followed by default. The
71 71 FILE_NOFOLLOW needs to be passed in along with the specified events if
72 72 the symbolic link itself needs to be watched and lstat() needs to be
73 73 used to get the file status of the symbolic link file.
74 74
75 75
76 76 The struct file_obj contains the following elements:
77 77
78 78 timestruc_t fo_atime; /* Access time from stat() */
79 79 timestruc_t fo_mtime; /* Modification time from stat() */
80 80 timestruc_t fo_ctime; /* Change time from stat() */
81 81 char *fo_name; /* Pointer to a null terminated path name */
82 82
83 83
84 84
85 85 At the time the port_associate() function is called, the time stamps
86 86 passed in the structure file_obj are compared with the file or
87 87 directory's current time stamps and, if there has been a change, an
88 88 event is immediately sent to the port. If not, an event will be sent
89 89 when such a change occurs.
90 90
91 91
92 92 The event types that can be specified at port_associate() time for
93 93 PORT_SOURCE_FILE are FILE_ACCESS, FILE_MODIFIED, FILE_ATTRIB, and
94 94 FILE_TRUNC. The first three of these correspond to the three time
95 95 stamps: an fo_atime change results in the FILE_ACCESS event, an
96 96 fo_mtime change results in the FILE_MODIFIED event, and an fo_ctime
97 97 change results in the FILE_ATTRIB event. If the operation that induced
98 98 the time stamp update also truncated the file, FILE_TRUNC will be set
99 99 in the resulting event.
100 100
101 101
102 102 The following exception events are delivered when they occur. These
103 103 event types cannot be filtered.
104 104
105 105 FILE_DELETE /* Monitored file/directory was deleted */
106 106 FILE_RENAME_TO /* Monitored file/directory was renamed */
107 107 FILE_RENAME_FROM /* Monitored file/directory was renamed */
108 108 UNMOUNTED /* Monitored file system got unmounted */
109 109 MOUNTEDOVER /* Monitored file/directory was mounted over */
110 110
111 111
112 112
113 113 At most one event notification will be generated per associated
114 114 file_obj. When the event for the associated file_obj is retrieved, the
115 115 object is no longer associated with the port. The event can be
116 116 processed without the possibility that another thread can retrieve a
117 117 subsequent event for the same object. The port_associate() can be
118 118 called to reassociate the file_obj object with the port.
119 119
120 120
121 121 The association is also removed if the port gets closed or when
122 122 port_dissociate() is called.
123 123
124 124
125 125 The parent and child processes are allowed to retrieve events from file
126 126 descriptors shared after a call to fork(2). The process performing the
127 127 first association with a port (parent or child process) is designated
128 128 as the owner of the association. Only the owner of an association is
129 129 allowed to dissociate the file descriptor from a port. The association
130 130 is removed if the owner of the association closes the port .
131 131
132 132
133 133 On NFS file systems, events from only the client side (local)
134 134 access/modifications to files or directories will be delivered.
135 135
136 136 RETURN VALUES
137 137 Upon succesful completion, 0 is returned. Otherwise, -1 is returned and
138 138 errno is set to indicate the error.
139 139
140 140 ERRORS
141 141 The port_associate() and port_dissociate() functions will fail if:
142 142
143 143 EBADF
144 144 The port identifier is not valid.
145 145
146 146
147 147 EBADFD
148 148 The source argument is of type PORT_SOURCE_FD and the object
149 149 argument is not a valid file descriptor.
150 150
151 151
152 152 EINVAL
153 153 The source argument is not valid.
154 154
155 155
156 156
157 157 The port_associate() function will fail if:
158 158
159 159 EACCES
160 160 The source argument is PORT_SOURCE_FILE and, Search
161 161 permission is denied on a component of path prefix or the
162 162 file exists and the permissions, corresponding to the events
163 163 argument, are denied.
164 164
165 165
166 166 EAGAIN
167 167 The maximum number of objects associated with the port was
168 168 exceeded. The maximum allowable number of events or
169 169 association of objects per port is the minimum value of the
170 170 process.max-port-events resource control at the time
171 171 port_create(3C) was used to create the port. See setrctl(2)
172 172 and rctladm(1M) for information on using resource controls.
173 173
174 174 The number of objects associated with a port is composed of
175 175 all supported resource types. Some of the source types do
176 176 not explicitly use the port_associate() function.
177 177
178 178
179 179 ENOENT
180 180 The source argument is PORT_SOURCE_FILE and the file does
181 181 not exist or the path prefix does not exist or the path
182 182 points to an empty string.
183 183
184 184
185 185 ENOMEM
186 186 The physical memory limits of the system have been exceeded.
187 187
188 188
189 189 ENOTSUP
190 190 The source argument is PORT_SOURCE_FILE and the file system
191 191 on which the specified file resides, does not support
192 192 watching for file events notifications.
193 193
194 194
195 195
196 196 The port_dissociate() function will fail if:
197 197
198 198 EACCES
199 199 The process is not the owner of the association.
200 200
201 201
202 202 ENOENT
203 203 The specified object is not associated with the port.
204 204
205 205
206 206 EXAMPLES
207 207 Example 1 Retrieve data from a pipe file descriptor.
208 208
209 209
210 210 The following example retrieves data from a pipe file descriptor.
211 211
212 212
213 213 #include <port.h>
214 214
215 215 int port;
216 216 int fd;
217 217 int error;
218 218 int index;
219 219 void *mypointer;
220 220 port_event_t pev;
221 221 struct timespec_t timeout;
222 222 char rbuf[STRSIZE];
223 223 int fds[MAXINDEX];
224 224
225 225 /* create a port */
226 226 port = port_create();
227 227
228 228 for (index = 0; index < MAXINDEX; index++) {
229 229 error = mkfifo(name[index], S_IRWXU | S_IRWXG | S_IRWXO);
230 230 if (error)
231 231 /* handle error code */
232 232 fds[index] = open(name[index], O_RDWR);
233 233
234 234 /* associate pipe file descriptor with the port */
235 235 error = port_associate(port, PORT_SOURCE_FD, fds[index],
236 236 POLLIN, mypointer);
237 237 }
238 238 ...
239 239 timeout.tv_sec = 1; /* user defined */
240 240 timeout.tv_nsec = 0;
241 241
242 242 /* loop to retrieve data from the list of pipe file descriptors */
243 243 for (...) {
244 244 /* retrieve a single event */
245 245 error = port_get(port, &pev, &timeout);
246 246 if (error) {
247 247 /* handle error code */
248 248 }
249 249 fd = pev.portev_object;
250 250 if (read(fd, rbuf, STRSIZE)) {
251 251 /* handle error code */
252 252 }
253 253 if (fd-still-accepting-data) {
254 254 /*
255 255 * re-associate the file descriptor with the port.
256 256 * The re-association is required for the
257 257 * re-activation of the data detection.
258 258 * Internals events and user arguments are set to the
259 259 * new (or the same) values delivered here.
260 260 */
261 261 error = port_associate(port, PORT_SOURCE_FD, fd, POLLIN,
262 262 pev.portev_user);
263 263 } else {
264 264 /*
265 265 * If file descriptor is no longer required,
266 266 * - it can remain disabled but still associated with
267 267 * the port, or
268 268 * - it can be dissociated from the port.
269 269 */
270 270 }
271 271
272 272
273 273 Example 2 Bind AIO transaction to a specific port.
274 274
275 275
276 276 The following example binds the AIO transaction to a specific port.
277 277
278 278
279 279 #include <port.h>
280 280
281 281 int port;
282 282 port_notify_t pn;
283 283 aiocb_t aiocb;
284 284 aiocb_t *aiocbp;
285 285 void *mypointer;
286 286 int error;
287 287 int my_errno;
288 288 int my_status;
289 289 struct timespec_t timeout;
290 290 port_event_t pev;
291 291
292 292 port = port_create();
293 293 ...
294 294 /* fill AIO specific part */
295 295 aiocb.aio_fildes = fd;
296 296 aiocb.aio_nbytes = BUFSIZE;
297 297 aiocb.aio_buf = bufp;
298 298 aiocb.aio_offset = 0;
299 299
300 300 /* port specific part */
301 301 pn.portnfy_port = port;
302 302 pn.portnfy_user = mypointer;
303 303 aiocb.aio_sigevent.sigev_notify = SIGEV_PORT;
304 304 aiocb.aio_sigevent.sigev_value.sival_ptr = &pn
305 305
306 306 /*
307 307 * The aio_read() function binds internally the asynchronous I/O
308 308 * transaction with the port delivered in port_notify_t.
309 309 */
310 310 error = aio_read(&aiocb);
311 311
312 312 timeout.tv_sec = 1; /* user defined */
313 313 timeout.tv_nsec = 0;
314 314
315 315 /* retrieve a single event */
316 316 error = port_get(port, &pev, &timeout);
317 317 if (error) {
318 318 /* handle error code */
319 319 }
320 320
321 321 /*
322 322 * pev.portev_object contains a pointer to the aiocb structure
323 323 * delivered in port_notify_t (see aio_read()).
324 324 */
325 325 aiocbp = pev.portev_object;
326 326
327 327 /* check error code and return value in
328 328 my_errno = aio_error(aiocbp);
329 329 ...
330 330 my_status = aio_return(aiocbp);
331 331 ...
332 332
333 333
334 334 ATTRIBUTES
335 335 See attributes(5) for descriptions of the following attributes:
336 336
337 337
338 338
339 339
340 340 +--------------------+-----------------+
341 341 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
342 342 +--------------------+-----------------+
343 343 |Architecture | all |
344 344 +--------------------+-----------------+
345 345 |Interface Stability | Committed |
|
↓ open down ↓ |
293 lines elided |
↑ open up ↑ |
346 346 +--------------------+-----------------+
347 347 |MT-Level | Safe |
348 348 +--------------------+-----------------+
349 349
350 350 SEE ALSO
351 351 rctladm(1M), poll(2), setrctl(2), port_alert(3C), port_create(3C),
352 352 port_get(3C), port_send(3C), signal.h(3HEAD), attributes(5)
353 353
354 354
355 355
356 - November 9, 2007 PORT_ASSOCIATE(3C)
356 + August 8, 2015 PORT_ASSOCIATE(3C)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX