1port_associate(3C) Standard C Library Functions port_associate(3C)
2
6 port_associate, port_dissociate - associate or dissociate the object
7 with the port
8
10 #include <port.h>
11 int port_associate(int port, int source, uintptr_t object,
13 int events, void *user);
14 int port_dissociate(int port, int source, uintptr_t object);
17
20 The port_associate() function associates specific events of a given
21 object with a port. Only objects associated with a particular port are
22 able to generate events that can be retrieved using port_get(3C) or
23 port_getn(3C). The delivery event has its portev_user member set to the
24 value specified in the user parameter. If the specified object is
25 already associated with the specified port, the port_associate() func‐
26 tion serves to update the events and user arguments of the association.
27 The port_dissociate() function removes the association of an object
28 with a port.
29 The objects that can be associated with a port by way of the port_asso‐
32 ciate() function are objects of type PORT_SOURCE_FD and
33 PORT_SOURCE_FILE. Objects of other types have type-specific association
34 mechanisms. A port_notify_t structure, defined in <port.h>, is used to
35 specify the event port and an application-defined cookie to associate
36 with these event sources. See port_create(3C) and signal.h(3HEAD).
37 The port_notify_t structure contains the following members:
40 int portntfy_port; /* bind request(s) to port */
42 void *portntfy_user; /* user defined cookie */
43 Objects of type PORT_SOURCE_FD are file descriptors. The event types
47 for PORT_SOURCE_FD objects are described in poll(2). At most one event
48 notification will be generated per associated file descriptor. For
49 example, if a file descriptor is associated with a port for the POLLRD‐
50 NORM event and data is available on the file descriptor at the time the
51 port_associate() function is called, an event is immediately sent to
52 the port. If data is not yet available, one event is sent to the port
53 when data first becomes available.
54 When an event for a PORT_SOURCE_FD object is retrieved, the object no
57 longer has an association with the port. The event can be processed
58 without the possibility that another thread can retrieve a subsequent
59 event for the same object. After processing of the file descriptor is
60 completed, the port_associate() function can be called to reassociate
61 the object with the port.
62 Objects of type PORT_SOURCE_FILE are pointer to the structure file_obj
65 defined in <sys/port.h>. This event source provides event notification
66 when the specified file/directory is accessed or modified or when its
67 status changes. The path name of the file/directory to be watched is
68 passed in the struct file_obj along with the access, modification, and
69 change time stamps acquired from a stat(2) call. If the file name is a
70 symbolic links, it is followed by default. The FILE_NOFOLLOW needs to
71 be passed in along with the specified events if the symbolic link
72 itself needs to be watched and lstat() needs to be used to get the file
73 status of the symbolic link file.
74 The struct file_obj contains the following elements:
77 timestruc_t fo_atime; /* Access time got from stat() */
79 timestruc_t fo_mtime; /* Modification time from stat() */
80 timestruc_t fo_ctime; /* Change time from stat() */
81 char *fo_name; /* Pointer to a null terminated path name */
82 At the time the port_associate() function is called, the time stamps
86 passed in the structure file_obj are compared with the file or direc‐
87 tory's current time stamps and, if there has been a change, an event is
88 immediately sent to the port. If not, an event will be sent when such a
89 change occurs.
90 The event types that can be specified at port_associate() time for
93 PORT_SOURCE_FILE are FILE_ACCESS, FILE_MODIFIED, and FILE_ATTRIB, cor‐
94 responding to the three time stamps. An fo_atime change results in the
95 FILE_ACCESS event, an fo_mtime change results in the FILE_MODIFIED
96 event, and an fo_time change results in the FILE_ATTRIB event.
97 The following exception events are delivered when they occur. These
100 event types cannot be filtered.
101 FILE_DELETE /* Monitored file/directory was deleted */
103 FILE_RENAME_TO /* Monitored file/directory was renamed */
104 FILE_RENAME_FROM /* Monitored file/directory was renamed */
105 UNMOUNTED /* Monitored file system got unmounted */
106 MOUNTEDOVER /* Monitored file/directory was mounted over */
107 At most one event notification will be generated per associated
111 file_obj. When the event for the associated file_obj is retrieved, the
112 object is no longer associated with the port. The event can be pro‐
113 cessed without the possibility that another thread can retrieve a sub‐
114 sequent event for the same object. The port_associate() can be called
115 to reassociate the file_obj object with the port.
116 The association is also removed if the port gets closed or when
119 port_dissociate() is called.
120 The parent and child processes are allowed to retrieve events from file
123 descriptors shared after a call to fork(2). The process performing the
124 first association with a port (parent or child process) is designated
125 as the owner of the association. Only the owner of an association is
126 allowed to dissociate the file descriptor from a port. The association
127 is removed if the owner of the association closes the port .
128 On NFS file systems, events from only the client side (local)
131 access/modifications to files or directories will be delivered.
132
134 Upon succesful completion, 0 is returned. Otherwise, −1 is returned and
135 errno is set to indicate the error.
136
138 The port_associate() and port_dissociate() functions will fail if:
139 EBADF The port identifier is not valid.
141 EBADFD The source argument is of type PORT_SOURCE_FD and the object
144 argument is not a valid file descriptor.
145 EINVAL The source argument is not valid.
148 The port_associate() function will fail if:
152 EACCES The source argument is PORT_SOURCE_FILE and, Search permis‐
154 sion is denied on a component of path prefix or the file
155 exists and the permissions, corresponding to the events
156 argument, are denied.
157 EAGAIN The maximum number of objects associated with the port was
160 exceeded. The maximum allowable number of events or associa‐
161 tion of objects per port is the minimum value of the
162 process.max-port-events resource control at the time
163 port_create(3C) was used to create the port. See setrctl(2)
164 and rctladm(1M) for information on using resource controls.
165 The number of objects associated with a port is composed of
167 all supported resource types. Some of the source types do
168 not explicitly use the port_associate() function.
169 ENOENT The source argument is PORT_SOURCE_FILE and the file does
172 not exist or the path prefix does not exist or the path
173 points to an empty string.
174 ENOMEM The physical memory limits of the system have been exceeded.
177 ENOTSUP The source argument is PORT_SOURCE_FILE and the file system
180 on which the specified file resides, does not support watch‐
181 ing for file events notifications.
182 The port_dissociate() function will fail if:
186 EACCES The process is not the owner of the association.
188 ENOENT The specified object is not associated with the port.
191
194 Example 1 Retrieve data from a pipe file descriptor.
195 The following example retrieves data from a pipe file descriptor.
198 #include <port.h>
201 int port;
203 int fd;
204 int error;
205 int index;
206 void *mypointer;
207 port_event_t pev;
208 struct timespec_t timeout;
209 char rbuf[STRSIZE];
210 int fds[MAXINDEX];
211 /* create a port */
213 port = port_create();
214 for (index = 0; index < MAXINDEX; index++) {
216 error = mkfifo(name[index], S_IRWXU | S_IRWXG | S_IRWXO);
217 if (error)
218 /* handle error code */
219 fds[index] = open(name[index], O_RDWR);
220 /* associate pipe file descriptor with the port */
222 error = port_associate(port, PORT_SOURCE_FD, fds[index],
223 POLLIN, mypointer);
224 }
225 ...
226 timeout.tv_sec = 1; /* user defined */
227 timeout.tv_nsec = 0;
228 /* loop to retrieve data from the list of pipe file descriptors */
230 for (...) {
231 /* retrieve a single event */
232 error = port_get(port, &pev, &timeout);
233 if (error) {
234 /* handle error code */
235 }
236 fd = pev.portev_object;
237 if (read(fd, rbuf, STRSIZE)) {
238 /* handle error code */
239 }
240 if (fd-still-accepting-data) {
241 /*
242 * re-associate the file descriptor with the port.
243 * The re-association is required for the
244 * re-activation of the data detection.
245 * Internals events and user arguments are set to the
246 * new (or the same) values delivered here.
247 */
248 error = port_associate(port, PORT_SOURCE_FD, fd, POLLIN,
249 pev.portev_user);
250 } else {
251 /*
252 * If file descriptor is no longer required,
253 * - it can remain disabled but still associated with
254 * the port, or
255 * - it can be dissociated from the port.
256 */
257 }
258 Example 2 Bind AIO transaction to a specific port.
261 The following example binds the AIO transaction to a specific port.
264 #include <port.h>
267 int port;
269 port_notify_t pn;
270 aiocb_t aiocb;
271 aiocb_t *aiocbp;
272 void *mypointer;
273 int error;
274 int my_errno;
275 int my_status;
276 struct timespec_t timeout;
277 port_event_t pev;
278 port = port_create();
280 ...
281 /* fill AIO specific part */
282 aiocb.aio_fildes = fd;
283 aiocb.aio_nbytes = BUFSIZE;
284 aiocb.aio_buf = bufp;
285 aiocb.aio_offset = 0;
286 /* port specific part */
288 pn.portnfy_port = port;
289 pn.portnfy_user = mypointer;
290 aiocb.aio_sigevent.sigev_notify = SIGEV_PORT;
291 aiocb.aio_sigevent.sigev_value.sival_ptr = &pn
292 /*
294 * The aio_read() function binds internally the asynchronous I/O
295 * transaction with the port delivered in port_notify_t.
296 */
297 error = aio_read(&aiocb);
298 timeout.tv_sec = 1; /* user defined */
300 timeout.tv_nsec = 0;
301 /* retrieve a single event */
303 error = port_get(port, &pev, &timeout);
304 if (error) {
305 /* handle error code */
306 }
307 /*
309 * pev.portev_object contains a pointer to the aiocb structure
310 * delivered in port_notify_t (see aio_read()).
311 */
312 aiocbp = pev.portev_object;
313 /* check error code and return value in
315 my_errno = aio_error(aiocbp);
316 ...
317 my_status = aio_return(aiocbp);
318 ...
319
322 See attributes(5) for descriptions of the following attributes:
323 ┌─────────────────────────────┬─────────────────────────────┐
328 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
329 ├─────────────────────────────┼─────────────────────────────┤
330 │Architecture │all │
331 ├─────────────────────────────┼─────────────────────────────┤
332 │Availability │SUNWcsr, SUNWhea │
333 ├─────────────────────────────┼─────────────────────────────┤
334 │Interface Stability │Committed │
335 ├─────────────────────────────┼─────────────────────────────┤
336 │MT-Level │Safe │
337 └─────────────────────────────┴─────────────────────────────┘
338
340 rctladm(1M), poll(2), setrctl(2), port_alert(3C), port_create(3C),
341 port_get(3C), port_send(3C), signal.h(3HEAD), attributes(5)
342SunOS 5.11 9 Nov 2007 port_associate(3C)