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

@@ -1,11 +1,12 @@
 '\" te
 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
+.\" Copyright (c) 2013, Joyent, Inc. All Rights Reserved.
 .\" 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.
 .\" 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.
 .\" 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]
-.TH PORT_ASSOCIATE 3C "Nov 9, 2007"
+.TH PORT_ASSOCIATE 3C "Jan 18, 2013"
 .SH NAME
 port_associate, port_dissociate \- associate or dissociate the object with the
 port
 .SH SYNOPSIS
 .LP

@@ -71,25 +72,25 @@
 the port.
 .sp
 .LP
 Objects of type \fBPORT_SOURCE_FILE\fR are pointer to the structure
 \fBfile_obj\fR defined in \fB<sys/port.h>\fR. This event source provides event
-notification when the specified file/directory is accessed or modified or when
-its status changes. The path name of the file/directory to be watched is passed
-in the \fBstruct file_obj\fR along with the \fBaccess\fR, \fBmodification\fR,
-and \fBchange\fR time stamps acquired from a \fBstat\fR(2) call. If the file
-name is a symbolic links, it is followed by default. The \fBFILE_NOFOLLOW\fR
-needs to be passed in along with the specified events if the symbolic link
-itself needs to be watched and \fBlstat()\fR needs to be used to get the file
-status of the symbolic link file.
+notification when the specified file/directory is accessed, modified,
+truncated or when its status changes. The path name of the file/directory to
+be watched is passed in the \fBstruct file_obj\fR along with the \fBaccess\fR,
+\fBmodification\fR, and \fBchange\fR time stamps acquired from a \fBstat\fR(2)
+call. If the file name is a symbolic link, it is followed by default. The
+\fBFILE_NOFOLLOW\fR needs to be passed in along with the specified events if
+the symbolic link itself needs to be watched and \fBlstat()\fR needs to be
+used to get the file status of the symbolic link file.
 .sp
 .LP
 The \fBstruct file_obj\fR contains the following elements:
 .sp
 .in +2
 .nf
-timestruc_t     fo_atime;  /* Access time got from stat() */
+timestruc_t     fo_atime;  /* Access time from stat() */
 timestruc_t     fo_mtime;  /* Modification time from stat() */
 timestruc_t     fo_ctime;  /* Change time from stat() */
 char            *fo_name;  /* Pointer to a null terminated path name */
 .fi
 .in -2

@@ -102,15 +103,17 @@
 immediately sent to the port. If not, an event will be sent when such a change
 occurs.
 .sp
 .LP
 The event types that can be specified at \fBport_associate()\fR time for
-\fBPORT_SOURCE_FILE\fR are \fBFILE_ACCESS\fR, \fBFILE_MODIFIED\fR, and
-\fBFILE_ATTRIB\fR, corresponding to the three time stamps. An \fBfo_atime\fR
-change results in the \fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results
-in the \fBFILE_MODIFIED\fR event, and an \fBfo_time\fR change results in the
-\fBFILE_ATTRIB\fR event.
+\fBPORT_SOURCE_FILE\fR are \fBFILE_ACCESS\fR, \fBFILE_MODIFIED\fR,
+\fBFILE_ATTRIB\fR, and \fbFILE_TRUNC\fR. The first three of these correspond
+to the three time stamps: an \fBfo_atime\fR change results in the
+\fBFILE_ACCESS\fR event, an \fBfo_mtime\fR change results in the
+\fBFILE_MODIFIED\fR event, and an \fBfo_ctime\fR change results in the
+\fBFILE_ATTRIB\fR event. If the operation that induced the time stamp update
+also truncated the file, \fBFILE_TRUNC\fR will be set in the resulting event.
 .sp
 .LP
 The following exception events are delivered when they occur. These event types
 cannot be filtered.
 .sp