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.
134 possibility that another thread can retrieve a subsequent event for the same
135 object. The \fBport_associate()\fR can be called to reassociate the
136 \fBfile_obj\fR object with the port.
137 .sp
138 .LP
139 The association is also removed if the port gets closed or when
140 \fBport_dissociate()\fR is called.
141 .sp
142 .LP
143 The parent and child processes are allowed to retrieve events from file
144 descriptors shared after a call to \fBfork\fR(2). The process performing the
145 first association with a port (parent or child process) is designated as the
146 owner of the association. Only the owner of an association is allowed to
147 dissociate the file descriptor from a port. The association is removed if the
148 owner of the association closes the port .
149 .sp
150 .LP
151 On NFS file systems, events from only the client side (local)
152 access/modifications to files or directories will be delivered.
153 .SH RETURN VALUES
154 .sp
155 .LP
156 Upon succesful completion, 0 is returned. Otherwise, \(mi1 is returned and
157 \fBerrno\fR is set to indicate the error.
158 .SH ERRORS
159 .sp
160 .LP
161 The \fBport_associate()\fR and \fBport_dissociate()\fR functions will fail if:
162 .sp
163 .ne 2
164 .na
165 \fB\fBEBADF\fR\fR
166 .ad
167 .RS 10n
168 The \fIport\fR identifier is not valid.
169 .RE
170
171 .sp
172 .ne 2
173 .na
174 \fB\fBEBADFD\fR\fR
175 .ad
176 .RS 10n
177 The \fIsource\fR argument is of type \fBPORT_SOURCE_FD\fR and the object
178 argument is not a valid file descriptor.
179 .RE
389 error = port_get(port, &pev, &timeout);
390 if (error) {
391 /* handle error code */
392 }
393
394 /*
395 * pev.portev_object contains a pointer to the aiocb structure
396 * delivered in port_notify_t (see aio_read()).
397 */
398 aiocbp = pev.portev_object;
399
400 /* check error code and return value in
401 my_errno = aio_error(aiocbp);
402 \&...
403 my_status = aio_return(aiocbp);
404 \&...
405 .fi
406 .in -2
407
408 .SH ATTRIBUTES
409 .sp
410 .LP
411 See \fBattributes\fR(5) for descriptions of the following attributes:
412 .sp
413
414 .sp
415 .TS
416 box;
417 c | c
418 l | l .
419 ATTRIBUTE TYPE ATTRIBUTE VALUE
420 _
421 Architecture all
422 _
423 Interface Stability Committed
424 _
425 MT-Level Safe
426 .TE
427
428 .SH SEE ALSO
429 .sp
430 .LP
431 \fBrctladm\fR(1M), \fBpoll\fR(2), \fBsetrctl\fR(2), \fBport_alert\fR(3C),
432 \fBport_create\fR(3C), \fBport_get\fR(3C), \fBport_send\fR(3C),
433 \fBsignal.h\fR(3HEAD), \fBattributes\fR(5)
|
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.
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
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)
|