summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2009-12-09 15:43:46 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2009-12-09 15:43:46 (GMT)
commit0711072135b526c33086175f5e5a82a201b207ac (patch) (side-by-side diff)
treed9604bfa37143c9a83590a8ae7e089e0a69fc800
parentaecebd653ebb3751d2680a80bd49bcd1ed00ba62 (diff)
downloadwydawca-0711072135b526c33086175f5e5a82a201b207ac.tar.gz
wydawca-0711072135b526c33086175f5e5a82a201b207ac.tar.bz2
Improve docs + bugfix.
* doc/Makefile.am (check-options): Fix sed expression. * doc/wydawca.texi: Update. * src/job.c (job_start): Don't fork if single_process is set.
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/wydawca.texi277
-rw-r--r--src/job.c1
3 files changed, 173 insertions, 107 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index e37b083..32f3c9d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -58,7 +58,7 @@ check-format: check-tabs check-sentence-spacing
check-options:
@check-docs.sh options \
'/OPTIONS_BEGIN/,/OPTIONS_END/s/OPTION( *\([^,][^,]*\),.*/\1/pg' \
- '/@c option --/{s///;s/^\(help\|version\|usage\)//;p}' \
+ '/@opindex *\(help\|version\|usage\),/d;s/@opindex *\([^ @,]\{2,\}\).*/\1/p' \
$(top_srcdir)/src/cmdline.opt -- \
$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir) -E - \
$(info_TEXINFOS)
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 82b8403..a136fd6 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -113,10 +113,8 @@ Access Methods
SQL Access Methods
-* gpg-key-sql::
* project-owner-sql::
-* user-data-sql::
-* verify-user-sql::
+* project-uploader-sql::
Mail Notification
@@ -372,7 +370,7 @@ reports them on its error output and exits with a non-zero status.
other inconsistencies and to exit with status 0 if no errors were
detected, and withs status 1 otherwise.
-@opindex -E, introduced
+@sopindex{E, introduced}
@xopindex{no-preprocessor, introduced}
Before parsing, configuration file is preprocessed using
@command{m4} (@pxref{Preprocessor}). To see the preprocessed
@@ -748,21 +746,48 @@ diagnostic. An initial set of macro definitions is supplied by the
@file{@var{$prefix}/share/wydawca/@var{version}/include} directory (where
@var{version} means the version of Wydawca package).
-The default @file{pp-setup} file renames all @command{m4} built-in
+ The default @file{pp-setup} file renames all @command{m4} built-in
macro names so they all start with the prefix @samp{m4_}. This
is similar to GNU m4 @option{--prefix-builtin} options, but has an
advantage that it works with non-GNU @command{m4} implementations as
-well.
+well.
+
+ Additional control over the preprocessor is provided via the
+following command line options:
+
+@table @option
+@xopindex{define, introduced}
+@sopindex{D, introduced}
+@item --define=@var{name}[=@var{value}]
+@itemx -D@var{name}[=@var{value}]
+ Define the preprocessor symbol @var{name} as having @var{value}, or
+empty.
+
+@xopindex{include-directory, introduced}
+@sopindex{I, introduced}
+@item --include-directory=@var{dir}
+@itemx -I@var{dir}
+ Add @var{dir} to the list of directories searched for preprocessor
+include files.
+
+@xopindex{no-preprocessor, defined}
+@item --no-preprocessor
+ Disable preprocessor.
+
+@xopindex{preprocessor, defined}
+@item --preprocessor=@var{command}
+Use @var{command} instead of the default preprocessor.
+@end table
@node syslog
@section Syslog Configuration Directives
@cindex syslog, configuration
-@kwindex syslog
Unless told otherwise, @command{wydawca} uses @code{syslog} to print
its diagnostic messages. By default, the program uses the
@samp{local1} facility. The @code{syslog} statement allows to change that:
+@deffn {Config} syslog @{ ... @}
@smallexample
syslog @{
facility local1;
@@ -770,6 +795,8 @@ syslog @{
print-priority yes;
@}
@end smallexample
+@end deffn
+
@deffn {Config: syslog} facility @var{name}
@kwindex authpriv@r{, syslog facility}
@@ -816,10 +843,9 @@ databases simultaneously, the only restriction being that they must be
@command{MySQL} databases (this restriction will be removed in future
releases).
-@kwindex sql
- A database is defined using @code{sql} block statement. It has the
-following syntax:
+ A database is defined using @code{sql} block statement:
+@deffn {Config} sql @var{id} @{ ... @}
@smallexample
@group
sql @var{id} @{
@@ -827,6 +853,7 @@ sql @var{id} @{
database @var{dbname};
user @var{username};
password @var{string};
+ ssl-ca @var{string};
@}
@end group
@end smallexample
@@ -835,6 +862,7 @@ sql @var{id} @{
database. It is used by another configuration statements (e.g. by
access methods, see the next section) to refer to this
database.
+@end deffn
@deffn {Config: sql} host @var{hostname}[:@var{port-or-socket}]
Set the hostname or @acronym{IP} address of the host running the
@@ -857,6 +885,11 @@ Sets the database user name.
Sets the password for accessing the database.
@end deffn
+@deffn {Config: sql} ssl-ca @var{file}
+Sets the pathname to the certificate authority file, if you
+wish to use a secure connection to the server via SSL.
+@end deffn
+
@noindent
An example @code{sql} statement follows:
@@ -875,14 +908,15 @@ sql default @{
@section Access Methods
@cindex Access method
@cindex @acronym{PGP} key
-@UNREVISED
+
An @dfn{access method} defines the ways to retrieve user information
-needed to verify the submission. This information can be, for example,
-the user's @acronym{PGP} key or his permissions on a project.
+necessary to verify the submission. This information can be, for
+example, the user's @acronym{PGP} key or his permissions on a project.
Access methods are defined in configuration file using the
following syntax:
+@deffn {Config} access-method
@smallexample
access-method @var{method-name} @{
type @var{type};
@@ -890,6 +924,7 @@ access-method @var{method-name} @{
params (@var{param1},@var{param2},...);
@}
@end smallexample
+@end deffn
Access method statements can appear either in the global scope of
the configuration file, or inside a @code{spool} statement
@@ -897,15 +932,10 @@ the configuration file, or inside a @code{spool} statement
pairs in the configuration file, and ones inside a @code{directory}
statement override them for that particular directory pair.
-There are four access methods, identified by the value of
+There are two access methods, identified by the value of
@var{method-name} tag:
@table @asis
-@kwindex gpg-key
-@item gpg-key
-Retrieve the public @acronym{PGP} key of a user. This method must
-return exactly one string.
-
@kwindex project-owner
@item project-owner
Retrieve email addresses and real names of administrators (or
@@ -913,17 +943,10 @@ return exactly one string.
consisting of two columns: an email address and a user name, in this
order.
-@kwindex user-data
-@item user-data
- Return email address and real name of a user. This method must
-return one tuple, consisting of two columns: an email address and a user
-name, in this order.
-
-@kwindex verify-user
-@item verify-user
- Verify if a user is allowed to make uploads for a certain project. This
-method must return the system name of the user if he is allowed to
-make uploads.
+@kwindex project-uploader
+@item project-uploader
+ Return system user names, real names, emails and GPG keys of
+the users that are allowed to make uploads for the project.
@end table
The sub-statements of @code{access-method} are:
@@ -956,13 +979,6 @@ subject to meta-variable interpretation (@pxref{meta-interpretation}). The
following meta-variables are defined:
@table @code
-@kwindex u
-@kwindex user
-@item u
-@itemx user
-@itemx user:name
- The system name of the user that submitted the triplet.
-
@kwindex p
@kwindex project
@item p
@@ -989,6 +1005,14 @@ Spool destination directory (@pxref{spool, destination}).
@item source-dir
Spool source directory (@pxref{spool, source}).
+
+@kwindex u
+@kwindex user
+@item u
+@itemx user
+@itemx user:name
+ The system name of the user that submitted the triplet. This is
+defined only in @samp{project-owner} access method.
@end table
@end deffn
@@ -1005,7 +1029,7 @@ Supplies additional parameters for the method.
@node sql type
@subsection SQL Access Methods
@cindex sql access type
-Access methods having the type @samp{sql} retrieve information from an
+Access methods of @samp{sql} type retrieve information from an
@acronym{SQL} database (as of version @value{VERSION}, only
@samp{MySQL} databases are supported).
@@ -1013,36 +1037,20 @@ The @code{query} statement supplies the @acronym{SQL} query to
execute. Normally, it should be a @code{SELECT} query.
The @code{params} statement must supply a single parameter --
-an identifier of one of the preceding @code{sql} blocks (@pxref{sql}),
+the identifier of one of the preceding @code{sql} blocks (@pxref{sql}),
which determines database name and user credentials needed to access it.
@cindex Savane
- The following sub-nodes contain sample definitions of all four
+ The following sub-nodes contain sample definitions for the
access methods using the @code{sql} type. They are based
on the database structure used in
@uref{http://gna.org/projects/savane, @command{Savane} system}.
@menu
-* gpg-key-sql::
* project-owner-sql::
-* user-data-sql::
-* verify-user-sql::
+* project-uploader-sql::
@end menu
-@node gpg-key-sql
-@subsubsection Gpg-key: an SQL Implementation
-@cindex gpg-key
- Retrieve the public @acronym{PGP} key of a user. This method must
-return exactly one string.
-
-@smallexample
-access-method gpg-key @{
- type sql;
- params (default);
- query "SELECT gpg_key FROM user WHERE user_name='$@{user@}'";
-@}
-@end smallexample
-
@node project-owner-sql
@subsubsection Project-owner: an SQL Implementation
@cindex project-owner
@@ -1063,36 +1071,21 @@ access-method project-owner @{
@}
@end smallexample
-@node user-data-sql
-@subsubsection User-data-sql: an SQL Implementation
-@cindex user-data
- Return email address and real name of a user. This method must
-return one tuple, consisting of two columns: an email address and a user
-name, in this order.
-
-@smallexample
-access-method user-data @{
- type sql;
- params (default);
- query "SELECT email, realname FROM user WHERE user_name='$@{user@}'";
-@}
-@end smallexample
-
-@node verify-user-sql
-@subsubsection Verify-user-sql: an SQL Implementation
-@cindex verify-user-sql
+@node project-uploader-sql
+@subsubsection Project-uploader: an SQL Implementation
+@cindex project-uploader-sql
+@UNREVISED
@smallexample
-access-method verify-user @{
+access-method project-owner @{
type sql;
params (default);
- query "SELECT user.user_name "
- "FROM user,user_group, groups "
+ query "SELECT user.email, user.realname "
+ "FROM user,user_group,groups "
"WHERE user_group.user_id=user.user_id "
"AND user_group.group_id=groups.group_id "
"AND user_group.admin_flags = 'A' "
- "AND groups.unix_group_name='$@{project@}' "
- "AND user.user_name='$@{user@}'";
+ "AND groups.unix_group_name = '$@{project@}'";
@}
@end smallexample
@@ -1128,7 +1121,7 @@ appear either in the global scope, in which case it affects all
spools, or within a @code{spool} block (@pxref{spool}),
where it affects only the given spool.
-@kwindex archive
+@deffn {Config} archive @var{type}
@smallexample
archive @var{type} @{
name @var{file-or-dir};
@@ -1151,6 +1144,7 @@ archive @var{type} @{
@item directory
Store file in a separate directory.
@end table
+@end deffn
@deffn {Config: archive} name @var{file-or-dir}
Specify the name of the tar archive (if type @samp{tar} is used) or
@@ -1174,9 +1168,11 @@ using GNU tar @option{--occurrence} option (@pxref{multiple, Multiple
Files with the Same Name, Multiple Files with the Same Name, tar,
@acronym{GNU} tar: an archiver tool}).
+@deffn {Config} tar-program @var{name}
By default, @code{wydawca} will search for @command{tar} binary in
your search path. If you wish to use a particular binary, you may
specify its full file name using @code{tar-program} statement.
+@end deffn
The @samp{directory} archivation type means that archive copies will
be stored in a directory specified by the @code{name} statement.
@@ -1270,7 +1266,6 @@ archive-signatures no;
@node spool
@section Distribution Spool
@cindex distribution spool
-@kwindex spool
@cindex defining source and distribution directories
@cindex distribution directory, defining
@cindex source directory, defining
@@ -1286,6 +1281,7 @@ global settings.
Distribution spool is defined in the configuration file by the
@code{spool} block statement:
+@deffn {Config} spool @var{tag}
@smallexample
spool @var{tag} @{
url @var{url};
@@ -1293,15 +1289,16 @@ spool @var{tag} @{
source @var{dir};
destination @var{dir};
file-sweep-time @var{interval};
- access-method @dots{}
- archive @dots{}
- notify-event @dots{}
+ access-method @{ @dots{} @}
+ archive @{ @dots{} @}
+ notify-event @{ @dots{} @}
@}
@end smallexample
The @var{tag} argument defines a unique identifier for this spool. It
will be used in log messages, timers (@FIXME-pxref{timers}) and in
meta-variable interpretation (@pxref{meta-interpretation}).
+@end deffn
@deffn {Config: spool} url @var{string}
Defines download @acronym{URL}, associated with this spool. Its value
@@ -1333,13 +1330,25 @@ are useful mainly for diagnostic purposes.
@end table
@end deffn
- The @code{source} and @code{destination} statements are mandatory.
+The following statements, if present, override the corresponding global
+definitions for this spool.
+
+@deffn {Config: spool} archive @{ @dots{} @}
+Configure spool-specific archivation. @xref{archivation}, for its
+description.
+@end deffn
- A @code{spool} block may also contain an @code{archive} statement
-(@pxref{archivation}), access method definitions (@pxref{access
-methods}) and notification statements (@pxref{notification}). Any of
-these statements, if present, override corresponding global definition
-for this spool.
+@deffn {Config: spool} access-method @var{tag} @{ @dots{} @}
+Configure spool-specific access-method. @xref{access
+methods}, for a detailed discussion of this statement.
+@end deffn
+
+@deffn {Config: spool} notify-event @{ @dots{} @}
+Configure spool-specific event notification. @xref{notification},
+for a detailed discussion of this statement.
+@end deffn
+
+ The @code{source} and @code{destination} statements are mandatory.
For example, the following definition says that valid uploads to
@file{/home/ftp/incoming/ftp} should be transferred to @file{/home/ftp/gnu}:
@@ -1467,7 +1476,7 @@ A symlink is created.
A symlink is removed.
@end table
-@kwindex statistics
+@deffn {Config} statistics @var{list}
The amount of information included in the statistics summary is
configured using the @code{statistics} statement. This statement takes
a list of arguments, each one being one of the keywords, described
@@ -1504,6 +1513,7 @@ warnings one would set:
@smallexample
statistics (all, errors, warnings);
@end smallexample
+@end deffn
@node notification
@section Mail Notification
@@ -1519,7 +1529,7 @@ previous section.
The sender email address for these notifications is set using the
@code{from-address} statement.
-@deffn {Configuration} from-address @var{address}
+@deffn {Config} from-address @var{address}
Set sender address for outgoing mails. E.g.:
@smallexample
@@ -1533,7 +1543,7 @@ constructed from the name of the user @command{wydawca} runs as
(@FIXME-pxref{user privs}) and the full domain name of the machine it
runs at.
-@deffn {Configuration} admin-address @var{email}
+@deffn {Config} admin-address @var{email}
Sets the admin email address or addresses. The statistics
notifications and any notifications configured to be sent to admins
will be forwarded to this address. The @var{email} argument is either
@@ -1571,7 +1581,7 @@ To send messages, @command{wydawca} uses a special logical entity
called a @dfn{mailer}. It is set in the configuration file using
@code{mailer} keyword.
-@deffn {Configuration} mailer @var{url}
+@deffn {Config} mailer @var{url}
Set mailer @acronym{URL}.
@end deffn
@@ -1679,7 +1689,7 @@ The message text may be specified either in place within the
configuration directive it belongs to (@FIXME-pxref{notification}), or
defined by @code{define-message} statement.
-@deffn {Configuration} define-message @var{name} @var{text};
+@deffn {Config} define-message @var{name} @var{text};
Define message @var{name} to be @var{text}. This message can be
referred to from other configuration statements by @code{@@@var{name}}
notation.
@@ -1712,10 +1722,11 @@ EOT;
@node statreports
@subsection Statistic Reports
-@kwindex mail-statistics
@UNREVISED
-Sending statistic reports to the system administrator is configured by
-@code{mail-statistics} statement.
+
+@deffn {Config} mail-statistics @{ ... @}
+The @code{mail-statistics} statement configures the statistic reports
+sent to the system administrator.
@smallexample
mail-statistics @{
@@ -1723,6 +1734,7 @@ mail-statistics @{
statistics @var{item-list};
@}
@end smallexample
+@end deffn
@deffn {Config: mail-statistics} message @var{text-or-id}
Define the message text. The argument is either the message text
@@ -1825,7 +1837,7 @@ concerned: the system administrator, project administrators, or
the user that initiated the upload. These notifications are configured
using the @code{notify-event} statement:
-@kwindex notify-event
+@deffn {Config} notify-event @{ ... @}
@smallexample
notify-event @{
event @var{ev-id};
@@ -1833,6 +1845,7 @@ notify-event @{
message @var{text-or-id};
@}
@end smallexample
+@end deffn
@deffn {Config: notify-event} event @var{ev-id}
Send notification when the event @var{ev-id} occurs. The following
@@ -2292,12 +2305,21 @@ Increase debugging level by 1.
@xref{debug, The @option{--debug} option}.
-@opsummary{stderr}
-@item --stderr
-@itemx -e
-Log to the standard error.
+@opsummary{define}
+@item --define=@var{name}[=@var{value}]
+@itemx -D@var{name}[=@var{value}]
+ Define the preprocessor symbol @var{name} as having @var{value}, or
+empty. @xref{Preprocessor}.
-@xref{stderr, The @option{--syslog} option}.
+@opsummary{dump-grammar-trace}
+@item --dump-grammar-trace
+Dump configuration grammar traces. This is useful for debugging
+@command{wydawca} configuration file parser.
+
+@opsummary{dump-lex-trace}
+@item --dump-lex-trace
+Dump lexical analyzer traces. This is useful for debugging
+@command{wydawca} configuration file parser.
@opsummary{stderr}
@item --dry-run
@@ -2307,12 +2329,28 @@ implies @option{--debug --stderr}.
@xref{dry-run, The dry-run mode}.
+@opsummary{stderr}
+@item --stderr
+@itemx -e
+Log to the standard error.
+
+@xref{stderr, The @option{--syslog} option}.
+
+@opsummary{force}
+@item --force
+Force start-up, even if if the pid file already exists.
+
+@opsummary{foreground}
+@item --foreground
+Remain in the foreground. This is mostly for debugging
+@command{wydawca}.
+
@opsummary{include-directory}
@item --include-directory=@var{dir}
@itemx -I @var{dir}
Add @var{dir} to include search path.
-@xref{Pragmatic Comments, #include}.
+@xref{Pragmatic Comments, #include}. @xref{Preprocessor}.
@opsummary{lint}
@item --lint
@@ -2322,6 +2360,33 @@ exit with code 0, if the syntax is OK, and with code 1 otherwise.
@xref{lint, The @option{--lint} option}.
+@opsummary{no-preprocessor}
+@item --no-preprocessor
+Disable preprocessor. @pxref{Preprocessor}.
+
+@opsummary{preprocessor}
+@item --preprocessor=@var{command}
+Use @var{command} instead of the default preprocessor. @pxref{Preprocessor}.
+
+@opsummary{single-process}
+@item --single-process
+Serialize job invocations by not forking subprocesses for each job.
+@emph{Do not use this option in production environment}.
+
+@opsummary{source}
+@item --source=@var{name}
+@itemx -s@var{name}
+Process only the spool with the given source name. This option
+may be given multiple times, to select several spools by their
+source names.
+
+@opsummary{spool}
+@item --spool=@var{tag}
+@itemx -S@var{tag}
+Process only spool with the given tag. This option
+may be given multiple times, to select several spools by their
+tag names.
+
@opsummary{help}
@item --help
@itemx -h
diff --git a/src/job.c b/src/job.c
index baf4cec..b9ac620 100644
--- a/src/job.c
+++ b/src/job.c
@@ -117,6 +117,7 @@ job_start (struct job *job)
else
job->state = STATE_FINISHED;
wakeup = 1;
+ return 0;
}
pid = fork ();

Return to:

Send suggestions and report system problems to the System administrator.