3928 `tail -f ...` doesn't notice file truncation

3929 `man tail` doesn't mentioned "-F" option
3930 'tail -F ...' not resetting the offset of file rotation properly
3968 want FILE_TRUNC event for PORT_SOURCE_FILE
Reviewed by: Gordon Ross <gordon.ross@nexenta.com>
Approved by: Dan McDonald <danmcd@nexenta.com>

2 files changed, 36 insertions, 21 deletions

diff --git a/usr/src/man/man1/tail.1 b/usr/src/man/man1/tail.1
index aca819269e..b96e6400dd 100644
--- a/usr/src/man/man1/tail.1
+++ b/usr/src/man/man1/tail.1
@@ -23,12 +23,12 @@ tail \- deliver the last part of a file
 
 .LP
 .nf
-\fB/usr/bin/tail\fR [\(+- \fInumber\fR [lbcf]] [\fIfile\fR]
+\fB/usr/bin/tail\fR [\(+- \fInumber\fR [lbcfF]] [\fIfile\fR]
 .fi
 
 .LP
 .nf
-\fB/usr/bin/tail\fR [\fB-lbcf\fR] [\fIfile\fR]
+\fB/usr/bin/tail\fR [\fB-lbcfF\fR] [\fIfile\fR]
 .fi
 
 .LP
@@ -92,11 +92,24 @@ Units of bytes.
 \fB\fB-f\fR \fR
 .ad
 .RS 7n
-Follow. If the input-file is not a pipe, the program does not terminate after
-the line of the input-file has been copied, but enters an endless loop, wherein
-it sleeps for a second and then attempts to read and copy further records from
-the input-file. Thus it can be used to monitor the growth of a file that is
-being written by some other process.
+Follow. If the input-file is not a pipe, \fBtail\fR does not terminate after
+the last line of the input-file has been copied, but enters an endless loop,
+wherein it watches the file for modifications and attempts to read and copy
+further records from the input-file. Thus it can be used to monitor the growth
+of a file that is being written by some other process. If the watched file is
+truncated \fBtail\fR will begin reading records from the start of the file.
+.RE
+
+.sp
+.ne 2
+.na
+\fB\fB-F\fR \fR
+.ad
+.RS 7n
+Follow named file. Operates as with \fB-f\fR, except that if the file is moved
+(e.g. if a watched log file is rotated) \fBtail\fR will close the original file
+and begin reading records from the start of the file with the specified name
+if and when that file is recreated.
 .RE
 
 .sp
diff --git a/usr/src/man/man3c/port_associate.3c b/usr/src/man/man3c/port_associate.3c
index d876b5c9d7..f6e66b0d65 100644
--- a/usr/src/man/man3c/port_associate.3c
+++ b/usr/src/man/man3c/port_associate.3c
@@ -73,21 +73,21 @@ the port.
 .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 */
@@ -104,11 +104,13 @@ 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