Version 1.0release-1.0

5 files changed, 55 insertions, 28 deletions

diff --git a/NEWS b/NEWS
index e69de29..4546558 100644
--- a/NEWS
+++ b/NEWS
@@ -0,0 +1,19 @@
+Vmod-binlog NEWS -- history of user-visible changes. 2013-10-19
+Copyright (C) 2013 Sergey Poznyakoff
+See the end of file for copying conditions.
+
+Please send Vmod-binlog bug reports to <gray@gnu.org>
+
+Version 1.0, 2013-10-19
+
+Initial release.
+
+
+Local variables:
+mode: outline
+paragraph-separate: "[	]*$"
+eval: (add-hook 'write-file-hooks 'time-stamp)
+time-stamp-start: "changes. "
+time-stamp-format: "%:y-%02m-%02d"
+time-stamp-end: "\n"
+end:
diff --git a/doc/binlogcat.1 b/doc/binlogcat.1
index 886d842..5d49bfb 100644
--- a/doc/binlogcat.1
+++ b/doc/binlogcat.1
@@ -10,13 +10,13 @@
 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\" GNU General Public License for more details.
 .\"
 .\" 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 17, 2013" "BINLOGCAT" "User Reference"
+.TH BINLOGCAT 1 "October 19, 2013" "BINLOGCAT" "User Reference"
 .SH NAME
 binlogcat \- print binary log files in human-readable form
 .SH SYNOPSIS
 \fBbinlogcat\fR [\fB\-dhnVv\fR] [\fB\-t\fR \fIFORMAT\fR] [\fIFILE\fR...]
 .SH DESCRIPTION
 The
@@ -32,15 +32,15 @@ Valid command line options are:
 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.
+Print information about each file before dumping it.
 .TP
-.BI \-t FORMAT
+.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.
diff --git a/doc/binlogsel.1 b/doc/binlogsel.1
index eb7bc3a..8c6dfd2 100644
--- a/doc/binlogsel.1
+++ b/doc/binlogsel.1
@@ -10,29 +10,31 @@
 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\" GNU General Public License for more details.
 .\"
 .\" 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 18, 2013" "BINLOGSEL" "User Reference"
+.TH BINLOGSEL 1 "October 19, 2013" "BINLOGSEL" "User Reference"
 .SH NAME
 binlogsel \- select records from binary logs
 .SH SYNOPSIS
-\fBbinlogsel\fR [\fB\-dnv\fR] [\fB\-D\fR \fIDIR\fR]\
+\fBbinlogsel\fR [\fB\-dnv\fR] [\fB\-D\fR \fIDIR\fR] [\fB\-i \fIN\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]
 .SH DESCRIPTION
 .B Binlosel
-selects from the binary logs the records that fall within the given
-time interval.  The interval is specified using the
+scans binary logs created by
+.BR vmod\-binlog (3)
+module and selects from them the records that were created within the given
+time intervals.  A time interval is specified using the
 .BI \-F " FROMTIME"
 and
 .BI \-T " TOTIME"
 options.  If both options are used, only records falling within the
 interval \fIFROMTIME\fR..\fITOTIME\fR will be returned.  If
 .B \-F
@@ -43,13 +45,13 @@ is omitted, \fITOTIME\fR is set to the current time.  If
 is used, but
 .B \-F
 is omitted, the starting time is set to the time of the earliest
 available log file.  Finally, if neither of options is used, all
 records will be output.  In this case, the operation is equivalent
 to that of the
-.B binlogcat
+.BR binlogcat (1)
 command.
 .PP
 The argument to either option is a mostly free format human readable
 date string such as "Sun, 29 Feb 2004 16:21:42 -0800" or "2004-02-29
 16:21:42"  or even "2 days ago".  It may contain items indicating
 calendar date, time of day, time zone, day of week, relative  time,
@@ -59,21 +61,21 @@ section
 .B Date input formats
 in
 .BR "GNU Coreutils manual" .
 If the
 .B info
 program and coreutils documentation are properly installed at your site, use
-the following command:
+the following command to view it:
 .PP
 .EX
 .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
+preceded by the \fB\-I\fR option, which introduces the tag to identify
+the records pertaining to that interval.  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
@@ -81,45 +83,46 @@ 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.
+define directory indexing level.  See
+.BR vmod\-binlog (3),
+for a description of the underlying directory structure.
 .PP
 If files are listed in the command line, the
 .BR \-D ,
 .BR \-i ,
 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
+which 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:
+initialization function can be supplied in the same option (note quoting):
+.PP
 .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
+option, which adds \fIDIR\fR to its end, 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.
@@ -183,12 +186,15 @@ Symbols exported from a loadable module must begin with
 module without suffix (\fB.so\fR, \fB.la\fR, etc.).  In the discussion
 below, the symbols
 .B binlogsel
 looks for are listed without this prefix.  Thus, for example, if the
 module name is \fBstats.so\fR, the name of the module initialization
 function must be \fBstats_LTX_init\fR.
+.PP
+.B Binlogsel
+expects modules to export the following functions:
 .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:
diff --git a/doc/vmod-binlog.3 b/doc/vmod-binlog.3
index 7578615..f5f978d 100644
--- a/doc/vmod-binlog.3
+++ b/doc/vmod-binlog.3
@@ -10,13 +10,13 @@
 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\" GNU General Public License for more details.
 .\"
 .\" 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 18, 2013" "VMOD-BINLOG" "User Reference"
+.TH VMOD-BINLOG 1 "October 19, 2013" "VMOD-BINLOG" "User Reference"
 .SH NAME
 vmod\-binlog \- binary log file support for Varnish Cache.
 .SH SYNOPSIS
 .B import binlog;
 
 .BI "VOID binlog.init(STRING " dir ", STRING " format ", STRING " param ");"
@@ -75,22 +75,23 @@ $dir/2013/09/22/20130922T000000.log
 .PP
 Binary logs can be viewed using the
 .BR binlogcat (3)
 and
 .BR binlogsel (3)
 utilities.
-.PP
+.SH FUNCTIONS
 Binary log support is initialized by a call to
 .B binlog.init
 function (normally it is done in
 .BR vcl_init ).
 .PP
 The
 .B dir
 argument specifies the top-level storage directory.  The
-.B format argument defines the format of logfile entries.  It is
+.B format
+argument defines the format of logfile entries.  It is
 a simplified form of Perl
 .B pack()
 template.  See the
 .B FORMAT
 section below for a detailed description.  Finally,
 .B param
@@ -101,13 +102,13 @@ The following parameters are defined:
 .TP
 \fBdebug\fR=\fINUMBER\fR
 Set debugging level.
 .TP
 \fBpattern\fR=\fISTRING\fR
 Sets pattern to use for log file names, instead of the default.
-Argument can contain
+The argument can contain
 .BR strftime (3)
 conversion specifiers.  The default is
 
 .EX
 %Y%m%dT%H%M%S.log
 .EE
@@ -116,29 +117,28 @@ conversion specifiers.  The default is
 Sets directory indexing scheme to use.  Allowed values are \fB0\fR,
 \fB1\fR, and \fB2\fR.  See the description of indexing schemes above.
 .TP
 \fBsize\fR=\fISIZE\fR
 Sets maximum size of a single binary log.  Any records not fitting
 into \fISIZE\fR will be discarded.  \fISIZE\fR can be followed by
-one of the usual size suffixes: \fBK\R, \fBM\fR, \fBG\fR (or their
+one of the usual size suffixes: \fBK\fR, \fBM\fR, \fBG\fR (or their
 lower-case equivalents), standing for kilobytes, megabytes and
 gigabytes, correspondingly.
 
 Logs are mapped into memory, so
-the \fISIZE\fR is limited by the amount of memory that can be mapped.
-See
+the \fISIZE\fR is limited.  See
 .BR mmap (2),
 for the details.
 
 The default value is 1G.
 .TP
 \fBinterval\fR=\fINUMBER\fR
 Sets log rotation interval, in seconds.  The default is 86400.
 .TP
 \fBumask\fR=\fIONUM\fR
-Sets umask for creating new log files.  Argument is an octal value.
+Sets umask for creating new log files (a three-digit octal value).
 The default is \fB077\fR.
 .TP
 \fBroundts\fR=\fIBOOL\fR
 If set to \fB1\fR, timestamps used for generating log file names will
 be rounded to the nearest rotation interval.  E.g., if the log file
 was created at 01:05:18 on September 22, 2013 and \fBroundts=1\fR is
@@ -177,15 +177,17 @@ can be used to construct the log entry from the HTTP headers:
 binlog.start();
 binlog.pack(http.X-Id);
 binlog.pack(http.req.url);
 binlog.commit();
 .EE
 .SH FORMAT
-Data format specification consists of a series of template letters
+Data format specification consists of a series of conversion
+specifiers, optionally separated by any amount of whitespace.
+A conversion specifier consists of a template letter
 optionally followed by numeric repeat count (which may be enclosed in
-square brackets).
+square brackets).  
 .PP
 The valid template letters are:
 .TP
 .BI Z [N]
 A null-terminated (ASCIZ) string of at most N-1 characters, will be
 null padded.  This letter must be followed by repeat count.
diff --git a/src/binlogsel.c b/src/binlogsel.c
index 10630e6..547b4ec 100644
--- a/src/binlogsel.c
+++ b/src/binlogsel.c
@@ -826,13 +826,13 @@ main(int argc, char **argv)
 	int tmask = 0;
 	time_t start, stop;
 	char *p;
 	
 	setprogname(argv[0]);
 	add_load_path(BINLOGSEL_MODDIR, LP_APPEND);
-	while ((c = getopt(argc, argv, "D:dF:hi:I:L:m:p:P:T:t:nV")) != EOF)
+	while ((c = getopt(argc, argv, "D:dF:hi:I:L:m:p:P:T:t:nVv")) != EOF)
 		switch (c) {
 		case 'D':
 			directory = optarg;
 			break;
 		case 'd':
 			timediff_option = 1;