[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