1port_associate(3C)       Standard C Library Functions       port_associate(3C)
2
3
4

NAME

6       port_associate,  port_dissociate  -  associate or dissociate the object
7       with the port
8

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

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() 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
30
31       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
38
39       The port_notify_t structure contains the following members:
40
41         int       portntfy_port;  /* bind request(s) to port */
42         void      *portntfy_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 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
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 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
75
76       The struct file_obj contains the following elements:
77
78         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
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 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
91
92       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
98
99       The following exception events are delivered  when  they  occur.  These
100       event types cannot be filtered.
101
102         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
108
109
110       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
117
118       The association is also  removed  if  the  port  gets  closed  or  when
119       port_dissociate() is called.
120
121
122       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
129
130       On  NFS  file  systems,  events  from  only  the  client  side  (local)
131       access/modifications to files or directories will be delivered.
132

RETURN VALUES

134       Upon succesful completion, 0 is returned. Otherwise, −1 is returned and
135       errno is set to indicate the error.
136

ERRORS

138       The port_associate() and port_dissociate() functions will fail if:
139
140       EBADF     The port identifier is not valid.
141
142
143       EBADFD    The source argument is of type PORT_SOURCE_FD and the  object
144                 argument is not a valid file descriptor.
145
146
147       EINVAL    The source argument is not valid.
148
149
150
151       The port_associate() function will fail if:
152
153       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
158
159       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
166                  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
170
171       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
175
176       ENOMEM     The physical memory limits of the system have been exceeded.
177
178
179       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
183
184
185       The port_dissociate() function will fail if:
186
187       EACCES    The process is not the owner of the association.
188
189
190       ENOENT    The specified object is not associated with the port.
191
192

EXAMPLES

194       Example 1 Retrieve data from a pipe file descriptor.
195
196
197       The following example retrieves data from a pipe file descriptor.
198
199
200         #include <port.h>
201
202         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
212         /* create a port */
213         port = port_create();
214
215         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
221             /* 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
229         /* 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
259
260       Example 2 Bind AIO transaction to a specific port.
261
262
263       The following example binds the AIO transaction to a specific port.
264
265
266         #include <port.h>
267
268         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
279         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
287         /* 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
293         /*
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
299         timeout.tv_sec = 1;     /* user defined */
300         timeout.tv_nsec = 0;
301
302         /* retrieve a single event */
303         error = port_get(port, &pev, &timeout);
304         if (error) {
305                 /* handle error code */
306         }
307
308         /*
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
314         /* check error code and return value in
315         my_errno = aio_error(aiocbp);
316         ...
317         my_status = aio_return(aiocbp);
318         ...
319
320

ATTRIBUTES

322       See attributes(5) for descriptions of the following attributes:
323
324
325
326
327       ┌─────────────────────────────┬─────────────────────────────┐
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

SEE ALSO

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)
342
343
344
345SunOS 5.11                        9 Nov 2007                port_associate(3C)
Impressum