binlogsel: add loadable module support

* Makefile.am (SUBDIRS): Add libltdl
* configure.ac: Configure ltdl
* src/Makefile.am (binlogsel_LDADD): Add LIBLTDL.
(binlogsel_CPPFLAGS): New variable.
* src/binlogcat.c (catlog): Bugfix.
* src/binlogsel.c: Allow for multiple intervals. Support loadable
modules.
* doc/binlogcat.1: Update.
* doc/binlogsel.1: Update.
* doc/vmod-binlog.3: Update.

3 files changed, 127 insertions, 25 deletions

diff --git a/doc/binlogcat.1 b/doc/binlogcat.1
index 5707860..886d842 100644
--- a/doc/binlogcat.1
+++ b/doc/binlogcat.1
@@ -13,7 +13,7 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with vmod-binlog.  If not, see <http://www.gnu.org/licenses/>.
-.TH BINLOGCAT 1 "October 16, 2013" "BINLOGCAT" "User Reference"
+.TH BINLOGCAT 1 "October 17, 2013" "BINLOGCAT" "User Reference"
 .SH NAME
 binlogcat \- print binary log files in human-readable form
 .SH SYNOPSIS
@@ -22,7 +22,7 @@ binlogcat \- print binary log files in human-readable form
 The
 .B binlogcat
 utility displays on standard output binary log files created by
-.BR vmod-binlog (3).
+.BR vmod\-binlog (3).
 If no \fIFILE\fR is given on the command line, the utility will read
 the binary data from its standard input.
 .PP
@@ -48,7 +48,7 @@ Print a short help summary.
 .BR \-V
 Show program version and exit.
 .SH "SEE ALSO"
-.BR vmod-binlog (3),
+.BR vmod\-binlog (3),
 .BR binlogsel (1),
 .BR vcl (7),
 .BR varnishd (1).
diff --git a/doc/binlogsel.1 b/doc/binlogsel.1
index cebb98c..ec7bd24 100644
--- a/doc/binlogsel.1
+++ b/doc/binlogsel.1
@@ -13,13 +13,16 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with vmod-binlog.  If not, see <http://www.gnu.org/licenses/>.
-.TH BINLOGSEL 1 "October 16, 2013" "BINLOGSEL" "User Reference"
+.TH BINLOGSEL 1 "October 17, 2013" "BINLOGSEL" "User Reference"
 .SH NAME
 binlogsel \- select records from binary logs
 .SH SYNOPSIS
-\fBbinlogsel\fR [\fB\-dnv\fR] [\fB\-t\fR \fIFORMAT\fR] [\fB\-F\fR
-\fITIME\fR] [\fB\-T\fR \fITIME\fR] [\fB\-p\fR \fIPATTERN\fR]\
- [\fB\-D\fR \fIDIR\fR]
+\fBbinlogsel\fR [\fB\-dnv\fR] [\fB\-D\fR \fIDIR\fR]\
+ [\fB\-p\fR \fIPATTERN\fR]\ [\fB\-t\fR \fIFORMAT\fR]
+          [\fB\-I\fR \fITAG\fR] [\fB\-F\fR \fITIME\fR] [\fB\-T\fR \fITIME\fR]\
+ 
+          [\fB\-L\fR \fIDIR\fR] [\fB\-P\fR \fIDIR\fR]\
+ [\fB\-m\fR '\fIMODULE\fR[ \fIARGS\fR]']
           [\fIFILE\fR...]
 
 \fBbinlogsel\fR [\fB\-hV\fR]
@@ -65,6 +68,20 @@ the following command:
 .B info coreutils 'Date input formats'
 .EE
 .PP
+Several time intervals can be specified, provided that each of them is
+preceded by the \fB\-I\fR option, which introduces the tag to mark
+records falling within the time interval that follows it.  This tag is
+output before each record.  For example:
+.PP
+.EX
+binlogsel -I 1h -F '1 hour ago' -I 2d -F '2 days ago' 
+.EE
+.PP
+This command selects two intervals: records added within the last hour,
+which will be prefixed on the output with the string \fB1h\fR, and
+records added within the last 2 days, which are prefixed by the string
+\fB2d\fR.
+.PP
 The log files are searched in the directory specified with the
 \fB\-D\fR command line option.  The \fB\-i\fR option can be used to
 define directory indexing level.
@@ -75,47 +92,132 @@ If files are listed in the command line, the
 and
 .B \-p
 options are ignored.
+.PP
+The default action of
+.B binlogsel
+is to print matching records on the standard output.  This can be
+changed by the use of loadable modules.  A module is a dynamic library
+that is loaded at program startup and provides functions for handling
+records in a specific way.
+.PP
+The module to be loaded is supplied with the \fB\-m\fR option.  For
+example, the option \fB-m modname\fR instructs
+.B binlogsel
+to load library \fBmodname.so\fR.  Additional arguments for the module
+initialization function can be supplied in the same option:
+.EX
+.B binlogsel -m 'modname -n arg'
+.EE
+.PP
+(note quoting).
+.PP
+The module to be loaded is searched in the library path, which
+consists initially of the single directory
+\fI$prefix\fR\fB/lib/vmod\-binlog\fR.  This path can be modified using
+the
+.BI \-L " DIR"
+option, which adds \fIDIR\fR to its and, or by the
+.BI \-P " DIR"
+option, which inserts its argument immediately before the default
+library directory.
+.PP
+See the section \fBLOADABLE MODULES\fR for the discussion of how to
+write loadable modules.
 .SH OPTIONS
 .TP
 .BI \-D " DIR"
 Set base log directory.
 .TP
-.BI \-i " N"
-Set directory indexing level.  Valid values for \fIN\fR are \fB0\fR,
-\fB1\fR and \fB2\fR.
+.B \-d
+Print timestamps relative to first record in the file.
 .TP
 .BI \-F " TIME"
 Select records newer than \fITIME\fR.  See the section
 \fBDESCRIPTION\fR for a discussion of valid time formats.
 .TP
-.BI \-T " TIME"
-Select records older than \fITIME\fR.
+.BI \-I " TAG"
+Defines the tag for the \fB\-F\fR and \fB\-T\fR options that
+immediately follow it.
+.TP
+.BI \-i " N"
+Set directory indexing level.  Valid values for \fIN\fR are \fB0\fR,
+\fB1\fR and \fB2\fR.
+.TP
+.BR \-h
+Print a short help summary and exit.
+.TP
+.BI \-L " DIR"
+Add \fIDIR\fR to the end of the library search path.
+.TP
+\fB\-m\fR \fB'\fR\fIMODULE\fR[ \fIARGS\fR]\fB'\fR
+Load \fIMODULE\fR.
+.TP
+.B \-n
+Precede each record by its number in the file (0-based).
+.TP
+.BI \-P " DIR"
+Insert \fIDIR\fR into the library search path immediately before the
+default library directory.
 .TP
 .BI \-p " PATTERN"
 Set pattern for log file names.  \fIPATTERN\fR must be a valid
 .BR strftime (3)
 format string.
-.B \-d
-Print timestamps relative to first record in the file.
 .TP
-.B \-n
-Precede each record by its number in the file (0-based).
-.TP
-.B \-v
-Print information about each file before dumpng it.
+.BI \-T " TIME"
+Select records older than \fITIME\fR.
 .TP
 .BI \-t " FORMAT"
 Format timestamps according to \fIFORMAT\fR (see
 .BR strftime (3)).
 Default is \fB%c\fR.
 .TP
-.BR \-h
-Print a short help summary.
-.TP
 .BR \-V
 Show program version and exit.
+.TP
+.B \-v
+Print information about each file before dumping it.
+.SH LOADABLE MODULES
+.TP
+.BI "void init(char *" param ", void (*" addfn ")(const char *, const char *, const char *));"
+.B [OPTIONAL]
+Initializes the module.  The first argument points to the arguments
+supplied to the module in the command line.  The \fBaddfn\fR function
+can be used to add new time intervals.  Its usage is:
+
+.EX
+.BI "void addfn(const char *" tag ", const char *" start ", const char *" end ")"
+.EE
+
+where \fItag\fR is the interval tag, and \fIstart\fR and \fIend\fR
+supply interval start and end times, correspondingly.
+.TP
+.BI "void done(" void ");"
+.B [OPTIONAL]
+Called immediately before
+.B binlogsel
+terminates.
+.TP
+.BI "int open(const char *" file ", size_t " recsize ", const char *" format ");"
+.B [OPTIONAL]
+This function is called immediately after opening the new log file.
+The name of the file is given by the \fIfile\fR argument.  The
+\fIrecsize\fR argument gives the record size, and \fIformat\fR points
+to the data format specification.
+
+The function must return 0 to indicate success and non-null value on errors.
+.TP
+.BI "void close(" void ");"
+.B [OPTIONAL]
+Called before closing the log file.
+.TP
+.BI "void record(const char *" tag ", time_t " ts ", void * " data ");"
+.B [MANDATORY]
+This function processes the record pointed to by \fIdata\fR.  The
+\fItag\fR argument points to the interval tag (can be \fBNULL\fR).
+Timestamp of the record is given by the \fIts\fR argument.
 .SH "SEE ALSO"
-.BR vmod-binlog (3),
+.BR vmod\-binlog (3),
 .BR binlogcat (1),
 .BR vcl (7),
 .BR varnishd (1).
diff --git a/doc/vmod-binlog.3 b/doc/vmod-binlog.3
index f6eb94f..2d6dfdb 100644
--- a/doc/vmod-binlog.3
+++ b/doc/vmod-binlog.3
@@ -13,9 +13,9 @@
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with vmod-binlog.  If not, see <http://www.gnu.org/licenses/>.
-.TH VMOD-BINLOG 1 "October 16, 2013" "VMOD-BINLOG" "User Reference"
+.TH VMOD-BINLOG 1 "October 17, 2013" "VMOD-BINLOG" "User Reference"
 .SH NAME
-vmod-binlog \- binary log file support for Varnish Cache.
+vmod\-binlog \- binary log file support for Varnish Cache.
 .SH SYNOPSIS
 .B import binlog;