From 8a4ba77068e5d7f6eab2cc1c1c10f31dcbccf7a6 Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Mon, 12 Oct 2009 23:41:21 +0300 Subject: Fix make distcheck and check-docs. * doc/Makefile.am: Fix `check-*' goals. * doc/pies.texi: Update and rearrange material. Document new configuration. * lib/Makefile.am (libpies_a_SOURCES): Remove nls.c * src/Makefile.am (EXTRA_DIST): Remove pies.rc, add pp-setup. (INCLUDES): Add $(top_builddir)/gnu * src/pies.c: Minor changes. * src/progman.c: Minor changes. * README-hacking: New file. --- doc/Makefile.am | 53 +---- doc/pies.texi | 715 ++++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 607 insertions(+), 161 deletions(-) (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 502c46e..d7d69d1 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -37,65 +37,33 @@ check-format: false; \ fi -check-pragmas: - @check-docs.sh pragmas \ - '/} option_cache\[\] = {/,/^}/s/[ \t]*{ *"\(.*\)".*/\1/pg' \ - 's/@deffnx* {pragma option} *\([^@, ]*\) .*/\1/p' \ - $(top_srcdir)/mfd/main.c -- \ - $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ - $(info_TEXINFOS) - check-options: @check-docs.sh options \ '/argp_option options\[\] = /,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ 's/@opindex *\([^@,]*\).*/\1/p' \ - $(top_srcdir)/mfd/main.c -- \ + $(top_srcdir)/src/pies.c -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ $(info_TEXINFOS) check-config: @check-docs.sh 'configuration statements' \ - '/mf_cfg_param\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ - 's/@deffn {Pies Conf} *\([^@,]*\).*/\1/p' \ - $(top_srcdir)/mfd/main.c -- \ + '/pies_keywords\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ + 's/@deffn {Config} *\([^@,]*\).*/\1/p' \ + $(top_srcdir)/src/pies.c -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ $(info_TEXINFOS) check-sub-config: - @list=`sed -n '/mf_cfg_param\[\] *= *{/,/^}/{s/[ \t]*{ *"\([^,"]*\)", *mu_cfg_section *,.*/\1/pg}' $(top_srcdir)/mfd/main.c`; \ - for ident in $$list; do \ + sed -n '/pies_keywords\[\] *= *{/,/^}/{p}' ../src/pies.c|tr '\n{' ' \n'|sed -n '/grecs_type_section/s/"\([^"]*\)".*grecs_type_section,[^,]*,[^,]*,[^,]*,[^,]*, *\(.*\) *}.*/\1 \2/p' | \ + while read ident kw; do \ check-docs.sh "$$ident configuration statements" \ - "/$${ident}_section_param"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ - "s/@deffn {$${ident}}"' *\([^@,]*\).*/\1/p' \ - $(top_srcdir)/mfd/main.c -- \ + "/$$kw"'\[\] *= *{/,/^}/s/[ \t]*{ *"\([^,"]*\)".*/\1/pg' \ + "s/@deffn {Config: *$${ident}}"' *\([^@,]*\).*/\1/p' \ + $(top_srcdir)/src/pies.c $(top_srcdir)/src/acl.c -- \ $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ $(info_TEXINFOS); \ done -check-builtins: - @check-docs.sh builtins \ - '/MF_DEFUN/{s/[ \t]*MF_DEFUN *(\([a-zA-Z_][a-zA-Z0-9_]*\),.*/\1/p;s/[ \t]*MF_DEFUN_VARARGS\(_NO_PROM\)\? *(\([a-zA-Z_][a-zA-Z0-9_]*\),.*/\2/p;s/[ \t]*MF_DEFUN_CTYPE *(\([a-zA-Z_][a-zA-Z0-9_]*\))/\1/p}'\ - 's/@deftypefnx\{0,1\} {Built-in Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \ - $(top_srcdir)/mfd/bi_*.m4 -- \ - $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ - $(info_TEXINFOS) - -check-mflib: - @check-docs.sh "library functions" \ - '/^[ \t]*func[ \t][ \t]*__/b;/^[ \t]*func/s/[ \t]*func[ \t][ \t]*\(.[^ \t(]*\).*/\1/p' \ - 's/@deftypefn {Library Function} *[^ ][^ ]* *\([^ ]*\).*/\1/p' \ - $(top_srcdir)/mflib/*.mf -- \ - $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ - $(info_TEXINFOS) - -check-exceptions: - @check-docs.sh exceptions \ - '/typedef enum mf_exception_code {/,/^};/s/[ \t]*mfe_\(.*\),.*/e_\1/p;/typedef enum mf_status_code {/,/^};/s/[ \t]*mf_\(.*\),.*/\1/p' \ - 's/@cindex \([^,][^,]*\), exception type/\1/p' \ - $(top_srcdir)/mfd/pies.h -- \ - $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \ - $(info_TEXINFOS) - check-refs: @for file in $(info_TEXINFOS) $(pies_TEXINFOS); \ do \ @@ -147,9 +115,8 @@ check-unrevised: rm $@-t; \ fi -all-check-docs: check-format check-options check-pragmas \ +all-check-docs: check-format check-options \ check-config check-sub-config \ - check-builtins check-mflib check-exceptions \ check-refs check-fixmes check-writeme check-unrevised check-docs: diff --git a/doc/pies.texi b/doc/pies.texi index cc35b5d..22c0f83 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -78,27 +78,25 @@ documents @command{pies} Version @value{VERSION}. @menu * Intro:: * Pies Configuration File:: -* Component Statement:: -* include-meta1:: -* Global Configuration:: * Pies Debugging:: * Configuration Example:: * Command Line Usage:: * Pies Invocation:: +* Reporting Bugs:: Appendices * Copying This Manual:: The GNU Free Documentation License. * Concept Index:: Index of Concepts. -@c @detailmenu -@c @end detailmenu +@detailmenu +@end detailmenu @end menu @node Intro @chapter Introduction -@cindex component, pies +@cindex component The name @command{pies} (pronounced @samp{p-yes}) stands for @samp{Program Invocation and Execution Supervisor}. This utility starts and controls execution of external programs, called @@ -110,9 +108,9 @@ terminates, @command{pies} restarts it. Its configuration allows to specify actions other than simple restart, depending on the exit code of the component. -@cindex prerequisite, pies -@cindex dependency, pies -@cindex dependents, pies +@cindex prerequisite +@cindex dependency +@cindex dependents @anchor{component prerequisite} A component @samp{A} may depend on another components, say @samp{B} and @samp{C}, i.e. require them to be running at the moment of its @@ -131,7 +129,7 @@ redirected to a file or to an arbitrary @command{syslog} channel. @anchor{init-style} @cindex init-style components - These way of operation applies to so-called @dfn{init-style} + This way of operation applies to the @dfn{init-style} components, called so because of the similarity with the @command{init} process manager. @command{Pies} is also able to handle components that receive input on their @samp{stdin} and send reply to @@ -180,40 +178,304 @@ stopping component dependencies, the same ordering is preserved. This order is reversed for files included by @code{include-meta1} statement (@pxref{include-meta1}). +@node Pies Configuration File +@chapter Pies Configuration File +@cindex configuration file +@flindex pies.conf +@xopindex{config-file, introduced} + @command{Pies} reads its settings and component definitions from the +@dfn{configuration file} @file{pies.conf}, located in the @dfn{system +configuration directory} (in most cases @file{/etc} or +@file{/usr/local/etc}, depending on how the package was compiled). +An alternative location may be specified using @option{--config-file} +(@option{-c} command line option. + + If any errors are encountered in the configuration file, the program +reports them on the standard error and exits with a non-zero status. + +@xopindex{lint, introduced} + To test the configuration file without actually starting the server, the +@option{--lint} (@option{-t}) command line option is provided. It causes +@command{pies} to check its configuration file and exit with status 0 +if no errors were detected, and with status 1 otherwise. + +@opindex -E, introduced + Before parsing, configuration file is preprocessed using +@command{m4} (@pxref{Preprocessor}). To see the preprocessed +configuration without actually parsing it, use @option{-E} command +line option. + +@xopindex{config-help, introduced} + The rest of this section describes the configuration file syntax in +detail. You can receive a concise summary of all configuration +directives any time by running @command{pies --config-help}. + @menu +* Syntax:: Configuration file syntax. +* Component Statement:: +* ACL:: Access Control Lists +* include-meta1:: +* Global Configuration:: @end menu -@node Pies Configuration File -@chapter Pies Configuration File - @command{Pies} reads its configuration from the main Mailutils -configuration file. @xref{configuration, Mailutils Configuration -File,, mailutils, GNU Mailutils Manual}, for a description of GNU -Mailutils configuration system. It is recommended to use -@code{include @var{directory}} statement (@pxref{Include, Include -Statement,, mailutils, GNU Mailutils Manual}), and to place -@command{pies} configuration in file @file{@var{directory}/pies}. -@xref{MeTA1,,, mailfromd, Mailfromd Manual}, for an example. - -The following standard Mailutils configuration statements are understood: - -@multitable @columnfractions 0.3 0.6 -@headitem Statement @tab Reference -@item debug @tab @xref{Debug Statement, Mailutils Debug Statement,, -mailutils, GNU Mailutils Manual}. -@item logging @tab @xref{Logging Statement, Mailutils Logging,, -mailutils, GNU Mailutils Manual}. -@item include @tab @xref{Include, Include Statements,, -mailutils, GNU Mailutils Manual}. -@item mailer @tab @xref{Mailer, Mailer Statement,, -mailutils, GNU Mailutils Manual}. -@item acl @tab @xref{ACL Statement, ACL Statement,, -mailutils, GNU Mailutils Manual}. +@node Syntax +@section Configuration File Syntax + The configuration file consists of statements and comments. + + There are three classes of lexical tokens: keywords, values, and +separators. Blanks, tabs, newlines and comments, collectively called +@dfn{white space} are ignored except as they serve to separate +tokens. Some white space is required to separate otherwise adjacent +keywords and values. + +@menu +* Comments:: +* Statements:: +* Preprocessor:: Using preprocessor to improve the configuration. +@end menu + +@node Comments +@subsection Comments +@cindex Comments in a configuration file +@cindex single-line comments + @dfn{Comments} may appear anywhere where white space may appear in the +configuration file. There are two kinds of comments: +single-line and multi-line comments. @dfn{Single-line} comments start +with @samp{#} or @samp{//} and continue to the end of the line: + +@smallexample +# This is a comment +// This too is a comment +@end smallexample + +@cindex multi-line comments + @dfn{Multi-line} or @dfn{C-style} comments start with the two +characters @samp{/*} (slash, star) and continue until the first +occurrence of @samp{*/} (star, slash). + + Multi-line comments cannot be nested. + +@node Statements +@subsection Statements +@cindex statements, configuration file +@cindex configuration file statements +@cindex statement, simple +@cindex simple statements + A @dfn{simple statement} consists of a keyword and value +separated by any amount of whitespace. Simple statement is terminated +with a semicolon (@samp{;}), unless it contains a @dfn{here-document} +(see below), in which case semicolon is optional. + + Examples of simple statements: + +@smallexample +pidfile /var/run/pies.pid; +source-info yes; +debug 10; +@end smallexample + + A @dfn{keyword} begins with a letter and may contain letters, +decimal digits, underscores (@samp{_}) and dashes (@samp{-}). +Examples of keywords are: @samp{group}, @samp{control-file}. + + A @dfn{value} can be one of the following: + +@table @asis +@item number + A number is a sequence of decimal digits. + +@item boolean +@cindex boolean value + A boolean value is one of the following: @samp{yes}, @samp{true}, +@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no}, +@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}. + +@item unquoted string +@cindex string, unquoted + An unquoted string may contain letters, digits, and any of the +following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/}, +@samp{:}. + +@item quoted string +@cindex quoted string +@cindex string, quoted +@cindex escape sequence + A quoted string is any sequence of characters enclosed in +double-quotes (@samp{"}). A backslash appearing within a quoted +string introduces an @dfn{escape sequence}, which is replaced +with a single character according to the following rules: + +@float Table, backslash-interpretation +@caption{Backslash escapes} +@multitable @columnfractions 0.30 .5 +@item Sequence @tab Replaced with +@item \a @tab Audible bell character (@acronym{ASCII} 7) +@item \b @tab Backspace character (@acronym{ASCII} 8) +@item \f @tab Form-feed character (@acronym{ASCII} 12) +@item \n @tab Newline character (@acronym{ASCII} 10) +@item \r @tab Carriage return character (@acronym{ASCII} 13) +@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9) +@item \\ @tab A single backslash (@samp{\}) +@item \" @tab A double-quote. @end multitable +@end float + + In addition, the sequence @samp{\@var{newline}} is removed from +the string. This allows to split long strings over several +physical lines, e.g.: + +@smallexample +@group +"a long string may be\ + split over several lines" +@end group +@end smallexample + + If the character following a backslash is not one of those specified +above, the backslash is ignored and a warning is issued. + + Two or more adjacent quoted strings are concatenated, which gives +another way to split long strings over several lines to improve +readability. The following fragment produces the same result as the +example above: + +@smallexample +@group +"a long string may be" +" split over several lines" +@end group +@end smallexample + +@anchor{here-document} +@item Here-document +@cindex here-document + @dfn{Here-document} is a special construct that allows to introduce +strings of text containing embedded newlines. + + The @code{<<@var{word}} construct instructs the parser to read all +the following lines up to the line containing only @var{word}, with +possible trailing blanks. Any lines thus read are concatenated +together into a single string. For example: + +@smallexample +@group +<