1 PORT_ASSOCIATE(3C) Standard C Library Functions PORT_ASSOCIATE(3C)
2
3
4
5 NAME
6 port_associate, port_dissociate - associate or dissociate the object
7 with the port
8
9 SYNOPSIS
10 #include <port.h>
11
12 int port_associate(int port, int source, uintptr_t object,
13 int events, void *user);
14
15
16 int port_dissociate(int port, int source, uintptr_t object);
17
18
19 DESCRIPTION
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()
26 function serves to update the events and user arguments of the
27 association. The port_dissociate() function removes the association of
28 an object with a port.
29
30
31 The objects that can be associated with a port by way of the
32 port_associate() 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
38
39 The port_notify_t structure contains the following members:
40
41 int portnfy_port; /* bind request(s) to port */
42 void *portnfy_user; /* user defined cookie */
43
44
45
46 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
50 POLLRDNORM event and data is available on the file descriptor at the
51 time the port_associate() function is called, an event is immediately
52 sent to the port. If data is not yet available, one event is sent to
53 the port when data first becomes available.
54
55
56 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
63
64 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, modified, truncated or
67 when its status changes. The path name of the file/directory to be
68 watched is passed in the struct file_obj along with the access,
69 modification, and change time stamps acquired from a stat(2) call. If
70 the file name is a symbolic link, it is followed by default. The
71 FILE_NOFOLLOW needs to be passed in along with the specified events if
72 the symbolic link itself needs to be watched and lstat() needs to be
73 used to get the file status of the symbolic link file.
74
75
76 The struct file_obj contains the following elements:
77
78 timestruc_t fo_atime; /* Access time 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
83
84
85 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
87 directory's current time stamps and, if there has been a change, an
88 event is immediately sent to the port. If not, an event will be sent
89 when such a change occurs.
90
91
92 The event types that can be specified at port_associate() time for
93 PORT_SOURCE_FILE are FILE_ACCESS, FILE_MODIFIED, FILE_ATTRIB, and
94 FILE_TRUNC. The first three of these correspond to the three time
95 stamps: an fo_atime change results in the FILE_ACCESS event, an
96 fo_mtime change results in the FILE_MODIFIED event, and an fo_ctime
97 change results in the FILE_ATTRIB event. If the operation that induced
98 the time stamp update also truncated the file, FILE_TRUNC will be set
99 in the resulting event.
100
101
102 The following exception events are delivered when they occur. These
103 event types cannot be filtered.
104
105 FILE_DELETE /* Monitored file/directory was deleted */
106 FILE_RENAME_TO /* Monitored file/directory was renamed */
107 FILE_RENAME_FROM /* Monitored file/directory was renamed */
108 UNMOUNTED /* Monitored file system got unmounted */
109 MOUNTEDOVER /* Monitored file/directory was mounted over */
110
111
112
113 At most one event notification will be generated per associated
114 file_obj. When the event for the associated file_obj is retrieved, the
115 object is no longer associated with the port. The event can be
116 processed without the possibility that another thread can retrieve a
117 subsequent event for the same object. The port_associate() can be
118 called to reassociate the file_obj object with the port.
119
120
121 The association is also removed if the port gets closed or when
122 port_dissociate() is called.
123
124
125 The parent and child processes are allowed to retrieve events from file
126 descriptors shared after a call to fork(2). The process performing the
127 first association with a port (parent or child process) is designated
128 as the owner of the association. Only the owner of an association is
129 allowed to dissociate the file descriptor from a port. The association
130 is removed if the owner of the association closes the port .
131
132
133 On NFS file systems, events from only the client side (local)
134 access/modifications to files or directories will be delivered.
135
136 RETURN VALUES
137 Upon succesful completion, 0 is returned. Otherwise, -1 is returned and
138 errno is set to indicate the error.
139
140 ERRORS
141 The port_associate() and port_dissociate() functions will fail if:
142
143 EBADF
144 The port identifier is not valid.
145
146
147 EBADFD
148 The source argument is of type PORT_SOURCE_FD and the object
149 argument is not a valid file descriptor.
150
151
152 EINVAL
153 The source argument is not valid.
154
155
156
157 The port_associate() function will fail if:
158
159 EACCES
160 The source argument is PORT_SOURCE_FILE and, Search
161 permission is denied on a component of path prefix or the
162 file exists and the permissions, corresponding to the events
163 argument, are denied.
164
165
166 EAGAIN
167 The maximum number of objects associated with the port was
168 exceeded. The maximum allowable number of events or
169 association of objects per port is the minimum value of the
170 process.max-port-events resource control at the time
171 port_create(3C) was used to create the port. See setrctl(2)
172 and rctladm(1M) for information on using resource controls.
173
174 The number of objects associated with a port is composed of
175 all supported resource types. Some of the source types do
176 not explicitly use the port_associate() function.
177
178
179 ENOENT
180 The source argument is PORT_SOURCE_FILE and the file does
181 not exist or the path prefix does not exist or the path
182 points to an empty string.
183
184
185 ENOMEM
186 The physical memory limits of the system have been exceeded.
187
188
189 ENOTSUP
190 The source argument is PORT_SOURCE_FILE and the file system
191 on which the specified file resides, does not support
192 watching for file events notifications.
193
194
195
196 The port_dissociate() function will fail if:
197
198 EACCES
199 The process is not the owner of the association.
200
201
202 ENOENT
203 The specified object is not associated with the port.
204
205
206 EXAMPLES
207 Example 1 Retrieve data from a pipe file descriptor.
208
209
210 The following example retrieves data from a pipe file descriptor.
211
212
213 #include <port.h>
214
215 int port;
216 int fd;
217 int error;
218 int index;
219 void *mypointer;
220 port_event_t pev;
221 struct timespec_t timeout;
222 char rbuf[STRSIZE];
223 int fds[MAXINDEX];
224
225 /* create a port */
226 port = port_create();
227
228 for (index = 0; index < MAXINDEX; index++) {
229 error = mkfifo(name[index], S_IRWXU | S_IRWXG | S_IRWXO);
230 if (error)
231 /* handle error code */
232 fds[index] = open(name[index], O_RDWR);
233
234 /* associate pipe file descriptor with the port */
235 error = port_associate(port, PORT_SOURCE_FD, fds[index],
236 POLLIN, mypointer);
237 }
238 ...
239 timeout.tv_sec = 1; /* user defined */
240 timeout.tv_nsec = 0;
241
242 /* loop to retrieve data from the list of pipe file descriptors */
243 for (...) {
244 /* retrieve a single event */
245 error = port_get(port, &pev, &timeout);
246 if (error) {
247 /* handle error code */
248 }
249 fd = pev.portev_object;
250 if (read(fd, rbuf, STRSIZE)) {
251 /* handle error code */
252 }
253 if (fd-still-accepting-data) {
254 /*
255 * re-associate the file descriptor with the port.
256 * The re-association is required for the
257 * re-activation of the data detection.
258 * Internals events and user arguments are set to the
259 * new (or the same) values delivered here.
260 */
261 error = port_associate(port, PORT_SOURCE_FD, fd, POLLIN,
262 pev.portev_user);
263 } else {
264 /*
265 * If file descriptor is no longer required,
266 * - it can remain disabled but still associated with
267 * the port, or
268 * - it can be dissociated from the port.
269 */
270 }
271
272
273 Example 2 Bind AIO transaction to a specific port.
274
275
276 The following example binds the AIO transaction to a specific port.
277
278
279 #include <port.h>
280
281 int port;
282 port_notify_t pn;
283 aiocb_t aiocb;
284 aiocb_t *aiocbp;
285 void *mypointer;
286 int error;
287 int my_errno;
288 int my_status;
289 struct timespec_t timeout;
290 port_event_t pev;
291
292 port = port_create();
293 ...
294 /* fill AIO specific part */
295 aiocb.aio_fildes = fd;
296 aiocb.aio_nbytes = BUFSIZE;
297 aiocb.aio_buf = bufp;
298 aiocb.aio_offset = 0;
299
300 /* port specific part */
301 pn.portnfy_port = port;
302 pn.portnfy_user = mypointer;
303 aiocb.aio_sigevent.sigev_notify = SIGEV_PORT;
304 aiocb.aio_sigevent.sigev_value.sival_ptr = &pn
305
306 /*
307 * The aio_read() function binds internally the asynchronous I/O
308 * transaction with the port delivered in port_notify_t.
309 */
310 error = aio_read(&aiocb);
311
312 timeout.tv_sec = 1; /* user defined */
313 timeout.tv_nsec = 0;
314
315 /* retrieve a single event */
316 error = port_get(port, &pev, &timeout);
317 if (error) {
318 /* handle error code */
319 }
320
321 /*
322 * pev.portev_object contains a pointer to the aiocb structure
323 * delivered in port_notify_t (see aio_read()).
324 */
325 aiocbp = pev.portev_object;
326
327 /* check error code and return value in
328 my_errno = aio_error(aiocbp);
329 ...
330 my_status = aio_return(aiocbp);
331 ...
332
333
334 ATTRIBUTES
335 See attributes(5) for descriptions of the following attributes:
336
337
338
339
340 +--------------------+-----------------+
341 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
342 +--------------------+-----------------+
343 |Architecture | all |
344 +--------------------+-----------------+
345 |Interface Stability | Committed |
346 +--------------------+-----------------+
347 |MT-Level | Safe |
348 +--------------------+-----------------+
349
350 SEE ALSO
351 rctladm(1M), poll(2), setrctl(2), port_alert(3C), port_create(3C),
352 port_get(3C), port_send(3C), signal.h(3HEAD), attributes(5)
353
354
355
356 August 8, 2015 PORT_ASSOCIATE(3C)