[master] 9e62b49 Document the varnish API options in a single place, using preprocessor tables.
Martin Blix Grydeland
martin at varnish-cache.org
Thu Jun 13 12:41:24 CEST 2013
commit 9e62b49947fc9d8e9ab2e72bdff8ba02b526125e
Author: Martin Blix Grydeland <martin at varnish-software.com>
Date: Fri May 24 15:03:52 2013 +0200
Document the varnish API options in a single place, using preprocessor
tables.
Enhance the usage() output of varnishlog using the new tables.
Add API utility header to extract data from the option headers.
diff --git a/bin/varnishlog/Makefile.am b/bin/varnishlog/Makefile.am
index 77e04a8..500d941 100644
--- a/bin/varnishlog/Makefile.am
+++ b/bin/varnishlog/Makefile.am
@@ -8,6 +8,7 @@ dist_man_MANS = varnishlog.1
varnishlog_SOURCES = \
varnishlog.c \
+ varnishlog_options.h \
vut.c \
vut.h \
$(top_builddir)/lib/libvarnish/vas.c \
diff --git a/bin/varnishlog/varnishlog.c b/bin/varnishlog/varnishlog.c
index a3199f7..13075fd 100644
--- a/bin/varnishlog/varnishlog.c
+++ b/bin/varnishlog/varnishlog.c
@@ -49,10 +49,20 @@
#include "vtim.h"
#include "vut.h"
+#define VOPT_OPTSTRING
+#define VOPT_SYNOPSIS
+#define VOPT_USAGE
+#define VOPT_INC "varnishlog_options.h"
+#include "vapi/voptget.h"
+
static void
usage(void)
{
- fprintf(stderr, "usage: varnishlog ...\n");
+ const char **opt;
+ fprintf(stderr, "Usage: varnishlog <options> [query expression]\n\n");
+ fprintf(stderr, "Options:\n");
+ for (opt = vopt_usage; *opt != NULL; opt += 2)
+ fprintf(stderr, " %-25s %s\n", *opt, *(opt + 1));
exit(1);
}
@@ -63,7 +73,7 @@ main(int argc, char * const *argv)
VUT_Init();
- while ((opt = getopt(argc, argv, "adg:n:r:uvw:")) != -1) {
+ while ((opt = getopt(argc, argv, vopt_optstring)) != -1) {
switch (opt) {
default:
if (!VUT_Arg(opt, optarg))
diff --git a/bin/varnishlog/varnishlog_options.h b/bin/varnishlog/varnishlog_options.h
new file mode 100644
index 0000000..801ca38
--- /dev/null
+++ b/bin/varnishlog/varnishlog_options.h
@@ -0,0 +1,42 @@
+/*-
+ * Copyright (c) 2006 Verdens Gang AS
+ * Copyright (c) 2006-2013 Varnish Software AS
+ * All rights reserved.
+ *
+ * Author: Martin Blix Grydeland <martin at varnish-software.com>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+#include "vapi/vapi_options.h"
+
+VSL_OPT_a
+VSL_OPT_d
+VSL_OPT_g
+VSL_OPT_i
+VSM_OPT_n
+VSM_OPT_N
+VSL_OPT_r
+VSL_OPT_u
+VSL_OPT_v
+VSL_OPT_w
+VSL_OPT_x
diff --git a/include/Makefile.am b/include/Makefile.am
index 3f33a3e..1ad0935 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -31,6 +31,8 @@ nobase_pkginclude_HEADERS = \
vapi/vsc_int.h \
vapi/vsl.h \
vapi/vsl_int.h \
+ vapi/voptget.h \
+ vapi/vapi_options.h \
vcli.h
# Private headers
diff --git a/include/vapi/vapi_options.h b/include/vapi/vapi_options.h
new file mode 100644
index 0000000..6051308
--- /dev/null
+++ b/include/vapi/vapi_options.h
@@ -0,0 +1,107 @@
+/*-
+ * Copyright (c) 2006 Verdens Gang AS
+ * Copyright (c) 2006-2013 Varnish Software AS
+ * All rights reserved.
+ *
+ * Author: Martin Blix Grydeland <martin at varnish-software.com>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+/* VSM options */
+
+#define VSM_OPT_n \
+ VOPT("n:", "[-n name]", "Varnish instance name", \
+ "Specify the name of the varnishd instance to get logs" \
+ " from. If -n is not specified, the host name is used." \
+ )
+
+#define VSM_OPT_N \
+ VOPT("N:", "[-N filename]", "VSM filename", \
+ "Specify the filename of a stale VSM instance. When using" \
+ " this option the abandonment checking is disabled." \
+ )
+
+/* VSL options */
+
+#define VSL_OPT_a \
+ VOPT("a", "[-a]", "Append binary file output", \
+ "When writing binary output to a file, append to it rather" \
+ " than overwrite it." \
+ )
+
+#define VSL_OPT_d \
+ VOPT("d", "[-d]", "Process old log entries on startup", \
+ "Start processing log records at the head of the log" \
+ " instead of the tail." \
+ )
+
+#define VSL_OPT_g \
+ VOPT("g:", "[-g {session|request|vxid|raw}]", "Grouping mode", \
+ "The grouping of the log records. The default is to group" \
+ " by request." \
+ )
+
+#define VSL_OPT_i \
+ VOPT("i:", "[-i tag]", "Include tag", \
+ "Output only this tag. Multiple -i options may be given." \
+ "\n" \
+ "If an -i option is the first of any -ix options, all tags" \
+ " are disabled before -ix processing." \
+ )
+
+#define VSL_OPT_r \
+ VOPT("r:", "[-r filename]", "Binary file input", \
+ "Read log in binary file format from this file." \
+ )
+
+#define VSL_OPT_u \
+ VOPT("u", "[-u]", "Binary file output unbuffered", \
+ "Unbuffered binary file output mode." \
+ )
+
+#define VSL_OPT_v \
+ VOPT("v", "[-v]", "Verbose record printing", \
+ "Use verbose output on record set printing, giving the" \
+ " VXID on every log line. Without this option, the VXID" \
+ " will only be given on the header of that transaction." \
+ )
+
+#define VSL_OPT_w \
+ VOPT("w:", "[-w filename]", "Binary output filename", \
+ "Write log entries to this file instead of displaying" \
+ " them. The file will be overwritten unless the -a option" \
+ " was specified. If the application receives a SIGHUP" \
+ " while writing to a file, it will reopen the file" \
+ " allowing the old one to be rotated away.\n" \
+ "\n" \
+ "XXX: Log rotation not yet implemented" \
+ )
+
+#define VSL_OPT_x \
+ VOPT("x:", "[-x tag]", "Exclude tag", \
+ "Exclude log records of this tag. Multiple -x options" \
+ " may be given.\n" \
+ "\n" \
+ "If an -x option is the first of any -ix options, all tags" \
+ " are enabled for output before -ix processing." \
+ )
diff --git a/include/vapi/voptget.h b/include/vapi/voptget.h
new file mode 100644
index 0000000..443d316
--- /dev/null
+++ b/include/vapi/voptget.h
@@ -0,0 +1,81 @@
+/*-
+ * Copyright (c) 2006 Verdens Gang AS
+ * Copyright (c) 2006-2013 Varnish Software AS
+ * All rights reserved.
+ *
+ * Author: Martin Blix Grydeland <martin at varnish-software.com>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+ * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ */
+
+/*
+ * Legend: VOPT(o,s,r,d,l) where
+ * o: Option string part
+ * s: Synopsis
+ * d: Description
+ * l: Long description
+ */
+
+#ifdef VOPT_OPTSTRING
+#define VOPT(o,s,d,l) o
+const char vopt_optstring[] =
+#include VOPT_INC
+ ;
+#undef VOPT
+#endif
+
+#ifdef VOPT_SYNOPSIS
+#define VOPT(o,s,d,l) " " s
+const char vopt_synopsis[] =
+#include VOPT_INC
+ ;
+#undef VOPT
+#endif
+
+#ifdef VOPT_USAGE
+#define VOPT(o,s,d,l) s, d,
+const char *vopt_usage[] = {
+#include VOPT_INC
+ NULL, NULL,
+};
+#undef VOPT
+#endif
+
+#ifndef VOPTGET_H
+#define VOPTGET_H
+
+struct vopt_full {
+ const char *option;
+ const char *synopsis;
+ const char *desc;
+ const char *ldesc;
+};
+
+#endif
+
+#ifdef VOPT_FULL
+#define VOPT(o,s,d,l) { o,s,d,l },
+const struct vopt_full vopt_full[] = {
+#include VOPT_INC
+};
+#undef VOPT
+#endif
More information about the varnish-commit
mailing list