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