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
+++ new/usr/src/man/man3c/port_associate.3c
1 1 '\" te
2 2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 -.TH PORT_ASSOCIATE 3C "Nov 9, 2007"
6 +.TH PORT_ASSOCIATE 3C "Aug 8, 2015"
7 7 .SH NAME
8 8 port_associate, port_dissociate \- associate or dissociate the object with the
9 9 port
10 10 .SH SYNOPSIS
11 11 .LP
12 12 .nf
13 13 #include <port.h>
14 14
15 15 \fBint\fR \fBport_associate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR,
16 16 \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR);
17 17 .fi
18 18
19 19 .LP
20 20 .nf
21 21 \fBint\fR \fBport_dissociate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR);
22 22 .fi
23 23
24 24 .SH DESCRIPTION
25 -.sp
26 25 .LP
27 26 The \fBport_associate()\fR function associates specific \fIevents\fR of a given
28 27 \fIobject\fR with a \fIport\fR. Only objects associated with a particular port
29 28 are able to generate events that can be retrieved using \fBport_get\fR(3C) or
30 29 \fBport_getn\fR(3C). The delivery event has its \fBportev_user\fR member set to
31 30 the value specified in the \fIuser\fR parameter. If the specified object is
32 31 already associated with the specified port, the \fBport_associate()\fR function
33 32 serves to update the \fIevents\fR and \fIuser\fR arguments of the association.
34 33 The \fBport_dissociate()\fR function removes the association of an object with
35 34 a port.
36 35 .sp
37 36 .LP
38 37 The objects that can be associated with a port by way of the
39 38 \fBport_associate()\fR function are objects of type \fBPORT_SOURCE_FD\fR and
|
↓ open down ↓ |
4 lines elided |
↑ open up ↑ |
40 39 \fBPORT_SOURCE_FILE\fR. Objects of other types have type-specific association
41 40 mechanisms. A \fBport_notify_t\fR structure, defined in \fB<port.h>\fR, is used
42 41 to specify the event port and an application-defined cookie to associate with
43 42 these event sources. See \fBport_create\fR(3C) and \fBsignal.h\fR(3HEAD).
44 43 .sp
45 44 .LP
46 45 The \fBport_notify_t\fR structure contains the following members:
47 46 .sp
48 47 .in +2
49 48 .nf
50 -int portntfy_port; /* bind request(s) to port */
51 -void *portntfy_user; /* user defined cookie */
49 +int portnfy_port; /* bind request(s) to port */
50 +void *portnfy_user; /* user defined cookie */
52 51 .fi
53 52 .in -2
54 53
55 54 .sp
56 55 .LP
57 56 Objects of type \fBPORT_SOURCE_FD\fR are file descriptors. The event types for
58 57 \fBPORT_SOURCE_FD\fR objects are described in \fBpoll\fR(2). At most one event
59 58 notification will be generated per associated file descriptor. For example, if
60 59 a file descriptor is associated with a port for the \fBPOLLRDNORM\fR event and
61 60 data is available on the file descriptor at the time the \fBport_associate()\fR
62 61 function is called, an event is immediately sent to the port. If data is not
63 62 yet available, one event is sent to the port when data first becomes available.
64 63 .sp
65 64 .LP
66 65 When an event for a \fBPORT_SOURCE_FD\fR object is retrieved, the object no
67 66 longer has an association with the port. The event can be processed without
68 67 the possibility that another thread can retrieve a subsequent event for the
69 68 same object. After processing of the file descriptor is completed, the
70 69 \fBport_associate()\fR function can be called to reassociate the object with
71 70 the port.
72 71 .sp
73 72 .LP
74 73 Objects of type \fBPORT_SOURCE_FILE\fR are pointer to the structure
75 74 \fBfile_obj\fR defined in \fB<sys/port.h>\fR. This event source provides event
76 75 notification when the specified file/directory is accessed, modified,
77 76 truncated or when its status changes. The path name of the file/directory to
78 77 be watched is passed in the \fBstruct file_obj\fR along with the \fBaccess\fR,
79 78 \fBmodification\fR, and \fBchange\fR time stamps acquired from a \fBstat\fR(2)
80 79 call. If the file name is a symbolic link, it is followed by default. The
81 80 \fBFILE_NOFOLLOW\fR needs to be passed in along with the specified events if
82 81 the symbolic link itself needs to be watched and \fBlstat()\fR needs to be
83 82 used to get the file status of the symbolic link file.
84 83 .sp
85 84 .LP
86 85 The \fBstruct file_obj\fR contains the following elements:
87 86 .sp
88 87 .in +2
89 88 .nf
90 89 timestruc_t fo_atime; /* Access time from stat() */
91 90 timestruc_t fo_mtime; /* Modification time from stat() */
92 91 timestruc_t fo_ctime; /* Change time from stat() */
93 92 char *fo_name; /* Pointer to a null terminated path name */
94 93 .fi
95 94 .in -2
96 95
97 96 .sp
98 97 .LP
99 98 At the time the \fBport_associate()\fR function is called, the time stamps
100 99 passed in the structure \fBfile_obj\fR are compared with the file or
101 100 directory's current time stamps and, if there has been a change, an event is
102 101 immediately sent to the port. If not, an event will be sent when such a change
103 102 occurs.
104 103 .sp
105 104 .LP
106 105 The event types that can be specified at \fBport_associate()\fR time for
107 106 \fBPORT_SOURCE_FILE\fR are \fBFILE_ACCESS\fR, \fBFILE_MODIFIED\fR,
108 107 \fBFILE_ATTRIB\fR, and \fbFILE_TRUNC\fR. The first three of these correspond
109 108 to the three time stamps: an \fBfo_atime\fR change results in the
110 109 \fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results in the
111 110 \fBFILE_MODIFIED\fR event, and an \fBfo_ctime\fR change results in the
112 111 \fBFILE_ATTRIB\fR event. If the operation that induced the time stamp update
113 112 also truncated the file, \fBFILE_TRUNC\fR will be set in the resulting event.
114 113 .sp
115 114 .LP
116 115 The following exception events are delivered when they occur. These event types
117 116 cannot be filtered.
118 117 .sp
119 118 .in +2
120 119 .nf
121 120 FILE_DELETE /* Monitored file/directory was deleted */
122 121 FILE_RENAME_TO /* Monitored file/directory was renamed */
123 122 FILE_RENAME_FROM /* Monitored file/directory was renamed */
124 123 UNMOUNTED /* Monitored file system got unmounted */
125 124 MOUNTEDOVER /* Monitored file/directory was mounted over */
126 125 .fi
127 126 .in -2
128 127
129 128 .sp
130 129 .LP
131 130 At most one event notification will be generated per associated \fBfile_obj\fR.
132 131 When the event for the associated \fBfile_obj\fR is retrieved, the object is no
133 132 longer associated with the port. The event can be processed without the
134 133 possibility that another thread can retrieve a subsequent event for the same
135 134 object. The \fBport_associate()\fR can be called to reassociate the
136 135 \fBfile_obj\fR object with the port.
137 136 .sp
138 137 .LP
139 138 The association is also removed if the port gets closed or when
140 139 \fBport_dissociate()\fR is called.
141 140 .sp
142 141 .LP
143 142 The parent and child processes are allowed to retrieve events from file
|
↓ open down ↓ |
82 lines elided |
↑ open up ↑ |
144 143 descriptors shared after a call to \fBfork\fR(2). The process performing the
145 144 first association with a port (parent or child process) is designated as the
146 145 owner of the association. Only the owner of an association is allowed to
147 146 dissociate the file descriptor from a port. The association is removed if the
148 147 owner of the association closes the port .
149 148 .sp
150 149 .LP
151 150 On NFS file systems, events from only the client side (local)
152 151 access/modifications to files or directories will be delivered.
153 152 .SH RETURN VALUES
154 -.sp
155 153 .LP
156 154 Upon succesful completion, 0 is returned. Otherwise, \(mi1 is returned and
157 155 \fBerrno\fR is set to indicate the error.
158 156 .SH ERRORS
159 -.sp
160 157 .LP
161 158 The \fBport_associate()\fR and \fBport_dissociate()\fR functions will fail if:
162 159 .sp
163 160 .ne 2
164 161 .na
165 162 \fB\fBEBADF\fR\fR
166 163 .ad
167 164 .RS 10n
168 165 The \fIport\fR identifier is not valid.
169 166 .RE
170 167
171 168 .sp
172 169 .ne 2
173 170 .na
174 171 \fB\fBEBADFD\fR\fR
175 172 .ad
176 173 .RS 10n
177 174 The \fIsource\fR argument is of type \fBPORT_SOURCE_FD\fR and the object
178 175 argument is not a valid file descriptor.
179 176 .RE
180 177
181 178 .sp
182 179 .ne 2
183 180 .na
184 181 \fB\fBEINVAL\fR\fR
185 182 .ad
186 183 .RS 10n
187 184 The \fIsource\fR argument is not valid.
188 185 .RE
189 186
190 187 .sp
191 188 .LP
192 189 The \fBport_associate()\fR function will fail if:
193 190 .sp
194 191 .ne 2
195 192 .na
196 193 \fB\fBEACCES\fR\fR
197 194 .ad
198 195 .RS 11n
199 196 The source argument is \fBPORT_SOURCE_FILE\fR and, Search permission is denied
200 197 on a component of path prefix or the file exists and the permissions,
201 198 corresponding to the events argument, are denied.
202 199 .RE
203 200
204 201 .sp
205 202 .ne 2
206 203 .na
207 204 \fB\fBEAGAIN\fR\fR
208 205 .ad
209 206 .RS 11n
210 207 The maximum number of objects associated with the port was exceeded. The
211 208 maximum allowable number of events or association of objects per port is the
212 209 minimum value of the \fBprocess.max-port-events\fR resource control at the time
213 210 \fBport_create\fR(3C) was used to create the port. See \fBsetrctl\fR(2) and
214 211 \fBrctladm\fR(1M) for information on using resource controls.
215 212 .sp
216 213 The number of objects associated with a port is composed of all supported
217 214 resource types. Some of the source types do not explicitly use the
218 215 \fBport_associate()\fR function.
219 216 .RE
220 217
221 218 .sp
222 219 .ne 2
223 220 .na
224 221 \fB\fBENOENT\fR\fR
225 222 .ad
226 223 .RS 11n
227 224 The source argument is \fBPORT_SOURCE_FILE\fR and the file does not exist or
228 225 the path prefix does not exist or the path points to an empty string.
229 226 .RE
230 227
231 228 .sp
232 229 .ne 2
233 230 .na
234 231 \fB\fBENOMEM\fR\fR
235 232 .ad
236 233 .RS 11n
237 234 The physical memory limits of the system have been exceeded.
238 235 .RE
239 236
240 237 .sp
241 238 .ne 2
242 239 .na
243 240 \fB\fBENOTSUP\fR\fR
244 241 .ad
245 242 .RS 11n
246 243 The source argument is \fBPORT_SOURCE_FILE\fR and the file system on which the
247 244 specified file resides, does not support watching for file events
248 245 notifications.
249 246 .RE
250 247
251 248 .sp
252 249 .LP
253 250 The \fBport_dissociate()\fR function will fail if:
254 251 .sp
255 252 .ne 2
256 253 .na
257 254 \fB\fBEACCES\fR\fR
258 255 .ad
259 256 .RS 10n
260 257 The process is not the owner of the association.
261 258 .RE
262 259
263 260 .sp
264 261 .ne 2
265 262 .na
266 263 \fB\fBENOENT\fR\fR
267 264 .ad
268 265 .RS 10n
269 266 The specified object is not associated with the port.
270 267 .RE
271 268
272 269 .SH EXAMPLES
273 270 .LP
274 271 \fBExample 1 \fRRetrieve data from a pipe file descriptor.
275 272 .sp
276 273 .LP
277 274 The following example retrieves data from a pipe file descriptor.
278 275
279 276 .sp
280 277 .in +2
281 278 .nf
282 279 #include <port.h>
283 280
284 281 int port;
285 282 int fd;
286 283 int error;
287 284 int index;
288 285 void *mypointer;
289 286 port_event_t pev;
290 287 struct timespec_t timeout;
291 288 char rbuf[STRSIZE];
292 289 int fds[MAXINDEX];
293 290
294 291 /* create a port */
295 292 port = port_create();
296 293
297 294 for (index = 0; index < MAXINDEX; index++) {
298 295 error = mkfifo(name[index], S_IRWXU | S_IRWXG | S_IRWXO);
299 296 if (error)
300 297 /* handle error code */
301 298 fds[index] = open(name[index], O_RDWR);
302 299
303 300 /* associate pipe file descriptor with the port */
304 301 error = port_associate(port, PORT_SOURCE_FD, fds[index],
305 302 POLLIN, mypointer);
306 303 }
307 304 \&...
308 305 timeout.tv_sec = 1; /* user defined */
309 306 timeout.tv_nsec = 0;
310 307
311 308 /* loop to retrieve data from the list of pipe file descriptors */
312 309 for (...) {
313 310 /* retrieve a single event */
314 311 error = port_get(port, &pev, &timeout);
315 312 if (error) {
316 313 /* handle error code */
317 314 }
318 315 fd = pev.portev_object;
319 316 if (read(fd, rbuf, STRSIZE)) {
320 317 /* handle error code */
321 318 }
322 319 if (fd-still-accepting-data) {
323 320 /*
324 321 * re-associate the file descriptor with the port.
325 322 * The re-association is required for the
326 323 * re-activation of the data detection.
327 324 * Internals events and user arguments are set to the
328 325 * new (or the same) values delivered here.
329 326 */
330 327 error = port_associate(port, PORT_SOURCE_FD, fd, POLLIN,
331 328 pev.portev_user);
332 329 } else {
333 330 /*
334 331 * If file descriptor is no longer required,
335 332 * - it can remain disabled but still associated with
336 333 * the port, or
337 334 * - it can be dissociated from the port.
338 335 */
339 336 }
340 337 .fi
341 338 .in -2
342 339
343 340 .LP
344 341 \fBExample 2 \fRBind AIO transaction to a specific port.
345 342 .sp
346 343 .LP
347 344 The following example binds the AIO transaction to a specific port.
348 345
349 346 .sp
350 347 .in +2
351 348 .nf
352 349 #include <port.h>
353 350
354 351 int port;
355 352 port_notify_t pn;
356 353 aiocb_t aiocb;
357 354 aiocb_t *aiocbp;
358 355 void *mypointer;
359 356 int error;
360 357 int my_errno;
361 358 int my_status;
362 359 struct timespec_t timeout;
363 360 port_event_t pev;
364 361
365 362 port = port_create();
366 363 \&...
367 364 /* fill AIO specific part */
368 365 aiocb.aio_fildes = fd;
369 366 aiocb.aio_nbytes = BUFSIZE;
370 367 aiocb.aio_buf = bufp;
371 368 aiocb.aio_offset = 0;
372 369
373 370 /* port specific part */
374 371 pn.portnfy_port = port;
375 372 pn.portnfy_user = mypointer;
376 373 aiocb.aio_sigevent.sigev_notify = SIGEV_PORT;
377 374 aiocb.aio_sigevent.sigev_value.sival_ptr = &pn
378 375
379 376 /*
380 377 * The aio_read() function binds internally the asynchronous I/O
381 378 * transaction with the port delivered in port_notify_t.
382 379 */
383 380 error = aio_read(&aiocb);
384 381
385 382 timeout.tv_sec = 1; /* user defined */
386 383 timeout.tv_nsec = 0;
387 384
388 385 /* retrieve a single event */
389 386 error = port_get(port, &pev, &timeout);
390 387 if (error) {
391 388 /* handle error code */
392 389 }
393 390
394 391 /*
395 392 * pev.portev_object contains a pointer to the aiocb structure
396 393 * delivered in port_notify_t (see aio_read()).
397 394 */
398 395 aiocbp = pev.portev_object;
|
↓ open down ↓ |
229 lines elided |
↑ open up ↑ |
399 396
400 397 /* check error code and return value in
401 398 my_errno = aio_error(aiocbp);
402 399 \&...
403 400 my_status = aio_return(aiocbp);
404 401 \&...
405 402 .fi
406 403 .in -2
407 404
408 405 .SH ATTRIBUTES
409 -.sp
410 406 .LP
411 407 See \fBattributes\fR(5) for descriptions of the following attributes:
412 408 .sp
413 409
414 410 .sp
415 411 .TS
416 412 box;
417 413 c | c
418 414 l | l .
419 415 ATTRIBUTE TYPE ATTRIBUTE VALUE
420 416 _
421 417 Architecture all
422 418 _
423 419 Interface Stability Committed
424 420 _
425 421 MT-Level Safe
426 422 .TE
427 423
428 424 .SH SEE ALSO
429 -.sp
430 425 .LP
431 426 \fBrctladm\fR(1M), \fBpoll\fR(2), \fBsetrctl\fR(2), \fBport_alert\fR(3C),
432 427 \fBport_create\fR(3C), \fBport_get\fR(3C), \fBport_send\fR(3C),
433 428 \fBsignal.h\fR(3HEAD), \fBattributes\fR(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX