.\" $Id: since.man,v 1.21 2012/07/06 20:30:08 ksb Exp $
.\" by KS Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/since.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/since.1*
.TH SINCE 1 LOCAL
.SH NAME
since - display new lines from a text file
.SH SYNOPSIS
.ds PN "since
\fB\*(PN\fP [\fB\-L\fP | \fB\-R\fP\~\fIlines\fP | \fB\-S\fP | \fB\-Z\fP] [\fB-c\fP\~\fIsep\fP] [\fB\-dn\fP] [\fB\-F\fP\~\fIdb\fP] \fItargets\fP
.br
\fB\*(PN\fP \fB\-h\fP
.br
\fB\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
\fISince\fP keeps a position in each \fItarget\fP file ever presented
to the program, which is recorded in \fIdb\fP.  Each new execution of
the program recovers the last position visited in the file, seeks to
that location and copies new (appended) lines from that point to the
present end of \fItarget\fP file.
.P
The new end-of-file is recorded in the \fIdb\fP file for the
next execution of \fB\*(PN\fP's benefit.
.P
When the file changes inode or device, or gets smaller \fB\*(PN\fP
assumes all the lines are new, so it starts at the first line again.

.P
If the \fItarget\fP is a directory \fB\*(PN\fP outputs a list of
the files in that directory that have changed (with regard to \fIst_ctime\fP)
since that directory was last viewed.  See \fBstat\fP(2).

.SH OPTIONS
If the program is called as \fB\*(PN\fP then no options are forced.

.TP
\fB\-c\fP \fIsep\fP
Appends the character \fIsep\fP to each node name from each directory
\fB\*(PN\fP processes.  Specify as '\e000' to emulate \-print0 output.

.TP
\fB\-d\fP
Delete the record for each of the \fItargets\fP from the
\fIdb\fP after the operation.

.TP
\fB\-F\fP \fIdb\fP
The path to the time stamp meta file.  The default is the basename of
the program in the present user's home directory, prefixed with a dot (\fB.\fP).

.TP
\fB\-h\fP
Print a brief help message.

.TP
\fB\-L\fP
List the status of each of the \fItargets\fP from the \fIdb\fP.
This includes a comparison to the present file (if it exists)
the first column is either "no", "yes", or "new" for files which
have no additional data, some additional data, or are not listed
in the present \fIdb\fP.  Nonexistant files produce and error on
\fBstderr\fP.

.TP
\fB\-n\fP
Don't update target's length in the meta file.  In this case
\fB\*(PN\fP outputs starting from the same point in the \fItarget\fP
next time.

.TP
\fB\-R\fP \fIlines\fP
The number of lines to replay before previous position.  Some filters
require some context to get started.
When there are fewer than \fIlines\fP lines in the file
\fB\*(PN\fP outputs enough blank lines to number
the first new line as number \fIlines\fP+1.
This options is silently ignored when the target is a directory.

.TP
\fB\-S\fP
Set the current position for \fItargets\fP to the present end of file
before any lines are processed (aka. skip to the end).

.TP
\fB\-V\fP
Show version information.  Also the default \fIdb\fP name.

.TP
\fB\-Z\fP
Replay each of the \fItargets\fP from the start (skip to zero).

.SH EXAMPLES
.TP
.nf
\fB\*(PN\fP \fB\-V\fP
.fi
Output the version of \fB\*(PN\fP and the default time-stamp path.
.TP
.nf
\fB\*(PN\fP /etc/motd
.fi
Display any new lines in \fB/etc/motd\fP.
.TP
.nf
\fB\*(PN\fP \-Zn /etc/motd
.fi
A synonym for \fBcat /etc/motd\fP.
.TP
\fB\*(PN\fP \-L /etc/motd
Compare the status of \fB/etc/motd\fP to the default \fIdb\fP.
.TP
.nf
\fB\*(PN\fP \-Ld /etc/motd >/dev/null
.fi
Remove the entry for \fB/etc/motd\fP from the \fIdb\fP file.
The redirection to \fB/dev/null\fP and the use of \fB\-L\fP
are the cheapest way to discard any output.
.TP
.nf
\fBxapply\fP 'echo Start "%1"; \*(PN %1' *.log
.fi
With multiple \fItargets\fP specified it is very hard to tell where one
ends and the next begins: in this example we use \fBxapply\fP to
provide a "Start" line for each file.
.TP
.nf
xclate \-T"\*(PN %x" \-m xapply \fB\*(PN\fP *.log
.fi
Much the same effect with a little more \fBxclate\fP wrapper magic.
.TP
.nf
\*(PN </var/tmp
.fi
Report the new files from the directory \fB/var/tmp\fP.  Yes the redirection
is \fBnot\fP a typing error.

.SH BUGS
.P
Linux volume managers have a penchant for picking different device numbers
for their volumes on reboot or remount.  This breaks \fB\*(PN\fP's
database key for entries and replays the whole file.  Either the
author(s) of LVM2 are missing the point of a device number, or I am.

.P
Files which are removed from the filesystem leave lines
in the \fB\*(PN\fP \fIdb\fP file, which may cause strange behavior
when a new file with the same device/inode/name combination is
created.  Applications should us a private \fIdb\fP file to
avoid this issue, and truncate it at some obvious point in
the application flow.

.P
The \fB\-S\fP option can race with a very active file
to produce some unexpected output.  Redirect \fB\*(PN\fP's
standard out to \fB/dev/null\fP to avoid confusion.

.P
The format of the \fIdb\fP file is not documented and should never be
assumed to be stable from version to version of \fB\*(PN\fP.  It might
be a good idea to remove any \fIdb\fP files after a major upgrade
(i.e. the integer part of the version number changes).

.P
The \fIdb\fP format may not work between NFS clients and servers (or
peer NFS clients) due to major device mappings being different.
The major device on the server will be a disk,
while each client might pick a different virtual one for the
same mapped filesystem.

.P
When \fB\*(PN\fP processes a \fItarget\fP directory via
an open file descriptor on
\fIstdin\fP and the specified \fIdb\fP file's pathname is
relative to the current working
directory the entry is read from the \fItarget\fP rather than the
original cwd, as \fB\*(PN\fP has to \fIfchdir(2)\fP to the target to
get a valid \fIopendir\fP handle on it.
(This happens in filesystem islands; which makes this more of
a feature than you'd think.)
.\" The feature alluded to above is that the "wrong" since-db file goes away
.\" with the island.  That hides any evidence, and the entry that would
.\" have been in the since-db would be irrelevant in that case (because
.\" the island is now gone). -- ksb
Use a full pathname for the \fIdb\fP file path to avoid this bug.

.SH AUTHOR
KS Braunsdorf
.br
NonPlayer Character Guild
.br
ksb swirl spam dot npcguild.org minus spam.
.sp
Pete Fritchman
.br
petef with no-Spam databits.net

.SH "SEE ALSO"
.hlm 0
sh(1), cat(1), tail(1), xapply(1l), Tee(1l), glob(1l), fchdir(2)