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