Print this page
3484 enhance and document tail follow support
Reviewed by: Joshua M. Clulow <jmc@joyent.com>

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man3c/port_associate.3c
          +++ new/usr/src/man/man3c/port_associate.3c
   1    1  '\" te
   2    2  .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
        3 +.\" Copyright (c) 2013, Joyent, Inc. All Rights Reserved.
   3    4  .\" 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    5  .\" 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    6  .\" 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 +.TH PORT_ASSOCIATE 3C "Jan 18, 2013"
   7    8  .SH NAME
   8    9  port_associate, port_dissociate \- associate or dissociate the object with the
   9   10  port
  10   11  .SH SYNOPSIS
  11   12  .LP
  12   13  .nf
  13   14  #include <port.h>
  14   15  
  15   16  \fBint\fR \fBport_associate\fR(\fBint\fR \fIport\fR, \fBint\fR \fIsource\fR, \fBuintptr_t\fR \fIobject\fR,
  16   17       \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR);
↓ open down ↓ 49 lines elided ↑ open up ↑
  66   67  When an event for a \fBPORT_SOURCE_FD\fR object is retrieved, the object no
  67   68  longer has an association with the port.  The event can be processed without
  68   69  the possibility that another thread can retrieve a subsequent event for the
  69   70  same object.  After processing of the file descriptor is completed, the
  70   71  \fBport_associate()\fR function can be called to reassociate the object with
  71   72  the port.
  72   73  .sp
  73   74  .LP
  74   75  Objects of type \fBPORT_SOURCE_FILE\fR are pointer to the structure
  75   76  \fBfile_obj\fR defined in \fB<sys/port.h>\fR. This event source provides event
  76      -notification when the specified file/directory is accessed or modified or when
  77      -its status changes. The path name of the file/directory to be watched is passed
  78      -in the \fBstruct file_obj\fR along with the \fBaccess\fR, \fBmodification\fR,
  79      -and \fBchange\fR time stamps acquired from a \fBstat\fR(2) call. If the file
  80      -name is a symbolic links, it is followed by default. The \fBFILE_NOFOLLOW\fR
  81      -needs to be passed in along with the specified events if the symbolic link
  82      -itself needs to be watched and \fBlstat()\fR needs to be used to get the file
  83      -status of the symbolic link file.
       77 +notification when the specified file/directory is accessed, modified,
       78 +truncated or when its status changes. The path name of the file/directory to
       79 +be watched is passed in the \fBstruct file_obj\fR along with the \fBaccess\fR,
       80 +\fBmodification\fR, and \fBchange\fR time stamps acquired from a \fBstat\fR(2)
       81 +call. If the file name is a symbolic link, it is followed by default. The
       82 +\fBFILE_NOFOLLOW\fR needs to be passed in along with the specified events if
       83 +the symbolic link itself needs to be watched and \fBlstat()\fR needs to be
       84 +used to get the file status of the symbolic link file.
  84   85  .sp
  85   86  .LP
  86   87  The \fBstruct file_obj\fR contains the following elements:
  87   88  .sp
  88   89  .in +2
  89   90  .nf
  90      -timestruc_t     fo_atime;  /* Access time got from stat() */
       91 +timestruc_t     fo_atime;  /* Access time from stat() */
  91   92  timestruc_t     fo_mtime;  /* Modification time from stat() */
  92   93  timestruc_t     fo_ctime;  /* Change time from stat() */
  93   94  char            *fo_name;  /* Pointer to a null terminated path name */
  94   95  .fi
  95   96  .in -2
  96   97  
  97   98  .sp
  98   99  .LP
  99  100  At the time the \fBport_associate()\fR function is called, the time stamps
 100  101  passed in the structure \fBfile_obj\fR are compared with the file or
 101  102  directory's current time stamps and, if there has been a change, an event is
 102  103  immediately sent to the port. If not, an event will be sent when such a change
 103  104  occurs.
 104  105  .sp
 105  106  .LP
 106  107  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, and
 108      -\fBFILE_ATTRIB\fR, corresponding to the three time stamps. An \fBfo_atime\fR
 109      -change results in the \fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results
 110      -in the \fBFILE_MODIFIED\fR event, and an \fBfo_time\fR change results in the
 111      -\fBFILE_ATTRIB\fR event.
      108 +\fBPORT_SOURCE_FILE\fR are \fBFILE_ACCESS\fR, \fBFILE_MODIFIED\fR,
      109 +\fBFILE_ATTRIB\fR, and \fbFILE_TRUNC\fR. The first three of these correspond
      110 +to the three time stamps: an \fBfo_atime\fR change results in the
      111 +\fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results in the
      112 +\fBFILE_MODIFIED\fR event, and an \fBfo_ctime\fR change results in the
      113 +\fBFILE_ATTRIB\fR event. If the operation that induced the time stamp update
      114 +also truncated the file, \fBFILE_TRUNC\fR will be set in the resulting event.
 112  115  .sp
 113  116  .LP
 114  117  The following exception events are delivered when they occur. These event types
 115  118  cannot be filtered.
 116  119  .sp
 117  120  .in +2
 118  121  .nf
 119  122  FILE_DELETE       /* Monitored file/directory was deleted */
 120  123  FILE_RENAME_TO    /* Monitored file/directory was renamed */
 121  124  FILE_RENAME_FROM  /* Monitored file/directory was renamed */
↓ open down ↓ 310 lines elided ↑ open up ↑
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX