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