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.
  72 .sp
  73 .LP
  74 Objects of type \fBPORT_SOURCE_FILE\fR are pointer to the structure
  75 \fBfile_obj\fR defined in \fB<sys/port.h>\fR. This event source provides event
  76 notification when the specified file/directory is accessed, modified,
  77 truncated or when its status changes. The path name of the file/directory to
  78 be watched is passed in the \fBstruct file_obj\fR along with the \fBaccess\fR,
  79 \fBmodification\fR, and \fBchange\fR time stamps acquired from a \fBstat\fR(2)
  80 call. If the file name is a symbolic link, it is followed by default. The
  81 \fBFILE_NOFOLLOW\fR needs to be passed in along with the specified events if
  82 the symbolic link itself needs to be watched and \fBlstat()\fR needs to be
  83 used to get the file status of the symbolic link file.
  84 .sp
  85 .LP
  86 The \fBstruct file_obj\fR contains the following elements:
  87 .sp
  88 .in +2
  89 .nf
  90 timestruc_t     fo_atime;  /* Access time from stat() */
  91 timestruc_t     fo_mtime;  /* Modification time from stat() */
  92 timestruc_t     fo_ctime;  /* Change time from stat() */
  93 char            *fo_name;  /* Pointer to a null terminated path name */
  94 .fi
  95 .in -2
  96 
  97 .sp
  98 .LP
  99 At the time the \fBport_associate()\fR function is called, the time stamps
 100 passed in the structure \fBfile_obj\fR are compared with the file or
 101 directory's current time stamps and, if there has been a change, an event is
 102 immediately sent to the port. If not, an event will be sent when such a change
 103 occurs.
 104 .sp
 105 .LP
 106 The event types that can be specified at \fBport_associate()\fR time for
 107 \fBPORT_SOURCE_FILE\fR are \fBFILE_ACCESS\fR, \fBFILE_MODIFIED\fR,
 108 \fBFILE_ATTRIB\fR, and \fbFILE_TRUNC\fR. The first three of these correspond
 109 to the three time stamps: an \fBfo_atime\fR change results in the
 110 \fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results in the
 111 \fBFILE_MODIFIED\fR event, and an \fBfo_ctime\fR change results in the
 112 \fBFILE_ATTRIB\fR event. If the operation that induced the time stamp update
 113 also truncated the file, \fBFILE_TRUNC\fR will be set in the resulting event.
 114 .sp
 115 .LP
 116 The following exception events are delivered when they occur. These event types
 117 cannot be filtered.
 118 .sp
 119 .in +2
 120 .nf
 121 FILE_DELETE       /* Monitored file/directory was deleted */
 122 FILE_RENAME_TO    /* Monitored file/directory was renamed */
 123 FILE_RENAME_FROM  /* Monitored file/directory was renamed */
 124 UNMOUNTED         /* Monitored file system got unmounted */
 125 MOUNTEDOVER       /* Monitored file/directory was mounted over */
 126 .fi
 127 .in -2
 128 
 129 .sp
 130 .LP
 131 At most one event notification will be generated per associated \fBfile_obj\fR.
 132 When the event for the associated \fBfile_obj\fR is retrieved, the object is no
 133 longer associated with the port. The event can be processed without the
 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
 180 
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fBEINVAL\fR\fR
 185 .ad
 186 .RS 10n
 187 The \fIsource\fR argument is not valid.
 188 .RE
 189 
 190 .sp
 191 .LP
 192 The \fBport_associate()\fR function will fail if:
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBEACCES\fR\fR
 197 .ad
 198 .RS 11n
 199 The source argument is \fBPORT_SOURCE_FILE\fR and, Search permission is denied
 200 on a component of path prefix or the file exists and the permissions,
 201 corresponding to the events argument, are denied.
 202 .RE
 203 
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBEAGAIN\fR\fR
 208 .ad
 209 .RS 11n
 210 The maximum number of objects associated with the port was exceeded. The
 211 maximum allowable number of events or association of objects per port is the
 212 minimum value of the \fBprocess.max-port-events\fR resource control at the time
 213 \fBport_create\fR(3C) was used to create the port. See \fBsetrctl\fR(2) and
 214 \fBrctladm\fR(1M) for information on using resource controls.
 215 .sp
 216 The number of objects associated with a port is composed of all supported
 217 resource types. Some of the source types do not explicitly use the
 218 \fBport_associate()\fR function.
 219 .RE
 220 
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBENOENT\fR\fR
 225 .ad
 226 .RS 11n
 227 The source argument is \fBPORT_SOURCE_FILE\fR and the file does not exist or
 228 the path prefix does not exist or the path points to an empty string.
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fBENOMEM\fR\fR
 235 .ad
 236 .RS 11n
 237 The physical memory limits of the system have been exceeded.
 238 .RE
 239 
 240 .sp
 241 .ne 2
 242 .na
 243 \fB\fBENOTSUP\fR\fR
 244 .ad
 245 .RS 11n
 246 The source argument is \fBPORT_SOURCE_FILE\fR and the file system on which the
 247 specified file resides, does not support watching for file events
 248 notifications.
 249 .RE
 250 
 251 .sp
 252 .LP
 253 The \fBport_dissociate()\fR function will fail if:
 254 .sp
 255 .ne 2
 256 .na
 257 \fB\fBEACCES\fR\fR
 258 .ad
 259 .RS 10n
 260 The process is not the owner of the association.
 261 .RE
 262 
 263 .sp
 264 .ne 2
 265 .na
 266 \fB\fBENOENT\fR\fR
 267 .ad
 268 .RS 10n
 269 The specified object is not associated with the port.
 270 .RE
 271 
 272 .SH EXAMPLES
 273 .LP
 274 \fBExample 1 \fRRetrieve data from a pipe file descriptor.
 275 .sp
 276 .LP
 277 The following example retrieves data from a pipe file descriptor.
 278 
 279 .sp
 280 .in +2
 281 .nf
 282 #include <port.h>
 283 
 284 int               port;
 285 int               fd;
 286 int               error;
 287 int               index;
 288 void              *mypointer;
 289 port_event_t      pev;
 290 struct timespec_t timeout;
 291 char              rbuf[STRSIZE];
 292 int               fds[MAXINDEX];
 293 
 294 /* create a port */
 295 port = port_create();
 296 
 297 for (index = 0; index < MAXINDEX; index++) {
 298     error = mkfifo(name[index], S_IRWXU | S_IRWXG | S_IRWXO);
 299     if (error)
 300             /* handle error code */
 301     fds[index] = open(name[index], O_RDWR);
 302 
 303     /* associate pipe file descriptor with the port */
 304     error = port_associate(port, PORT_SOURCE_FD, fds[index],
 305         POLLIN, mypointer);
 306 }
 307 \&...
 308 timeout.tv_sec = 1;     /* user defined */
 309 timeout.tv_nsec = 0;
 310 
 311 /* loop to retrieve data from the list of pipe file descriptors */
 312 for (...) {
 313     /* retrieve a single event */
 314     error = port_get(port, &pev, &timeout);
 315     if (error) {
 316             /* handle error code */
 317     }
 318     fd = pev.portev_object;
 319     if (read(fd, rbuf, STRSIZE)) {
 320             /* handle error code */
 321     }
 322     if (fd-still-accepting-data) {
 323             /*
 324              * re-associate the file descriptor with the port.
 325              * The re-association is required for the
 326              * re-activation of the data detection.
 327              * Internals events and user arguments are set to the
 328              * new (or the same) values delivered here.
 329              */
 330             error = port_associate(port, PORT_SOURCE_FD, fd, POLLIN,
 331                 pev.portev_user);
 332     } else {
 333             /*
 334              * If file descriptor is no longer required,
 335              * - it can remain disabled but still associated with
 336              *   the port, or
 337              * - it can be dissociated from the port.
 338              */
 339         }
 340 .fi
 341 .in -2
 342 
 343 .LP
 344 \fBExample 2 \fRBind AIO transaction to a specific port.
 345 .sp
 346 .LP
 347 The following example binds the AIO transaction to a specific port.
 348 
 349 .sp
 350 .in +2
 351 .nf
 352 #include <port.h>
 353 
 354 int             port;
 355 port_notify_t   pn;
 356 aiocb_t         aiocb;
 357 aiocb_t         *aiocbp;
 358 void            *mypointer;
 359 int             error;
 360 int             my_errno;
 361 int             my_status;
 362 struct timespec_t timeout;
 363 port_event_t    pev;
 364 
 365 port = port_create();
 366 \&...
 367 /* fill AIO specific part */
 368 aiocb.aio_fildes = fd;
 369 aiocb.aio_nbytes = BUFSIZE;
 370 aiocb.aio_buf = bufp;
 371 aiocb.aio_offset = 0;
 372 
 373 /* port specific part */
 374 pn.portnfy_port = port;
 375 pn.portnfy_user = mypointer;
 376 aiocb.aio_sigevent.sigev_notify = SIGEV_PORT;
 377 aiocb.aio_sigevent.sigev_value.sival_ptr = &pn
 378 
 379 /*
 380  * The aio_read() function binds internally the asynchronous I/O
 381  * transaction with the port delivered in port_notify_t.
 382  */
 383 error = aio_read(&aiocb);
 384 
 385 timeout.tv_sec = 1;     /* user defined */
 386 timeout.tv_nsec = 0;
 387 
 388 /* retrieve a single event */
 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)