diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-10-17 22:27:16 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2013-10-17 22:27:16 +0300 |
commit | 803128db75e3efea8cd7be29732a7b4315205d13 (patch) | |
tree | 713699a3724f905ca3dd740c386c9ffdb75e94a7 /doc | |
parent | aad0ead6ae1bb56953642eac584d9a5f1dc6d72e (diff) | |
download | vmod-binlog-803128db75e3efea8cd7be29732a7b4315205d13.tar.gz vmod-binlog-803128db75e3efea8cd7be29732a7b4315205d13.tar.bz2 |
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.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/binlogcat.1 | 6 | ||||
-rw-r--r-- | doc/binlogsel.1 | 142 | ||||
-rw-r--r-- | doc/vmod-binlog.3 | 4 |
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; |