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