summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2010-06-19 15:18:58 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2010-06-19 15:18:58 (GMT)
commit3b49db92dc4a67f72a4d641f3ac9492f4a44578c (patch) (side-by-side diff)
tree8701771e3e5f3631b03b85e1a62f98f71ef6973d
parentb4ff3aa84bd151a4a575c10b141be425ecc9b867 (diff)
downloadsmap-3b49db92dc4a67f72a4d641f3ac9492f4a44578c.tar.gz
smap-3b49db92dc4a67f72a4d641f3ac9492f4a44578c.tar.bz2
Bugfixes
* doc/macros.texi: New file. * doc/Makefile.am (smap_TEXINFOS): Add macros.texi * doc/Config: Override $image hanlder. * doc/ex-meta1.texi: Add indexing commands. * doc/gendocs_template: Fix copy-paste errors. * doc/smap.texi: Add indexing commands. * configure.ac, NEWS: Version 0.0.94
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--NEWS4
-rw-r--r--configure.ac2
-rw-r--r--doc/Config36
-rw-r--r--doc/Makefile.am7
-rw-r--r--doc/ex-meta1.texi1
-rwxr-xr-xdoc/gendocs_template4
-rw-r--r--doc/macros.texi13
-rw-r--r--doc/smap.texi140
8 files changed, 196 insertions, 11 deletions
diff --git a/NEWS b/NEWS
index 77af17a..fb1e6aa 100644
--- a/NEWS
+++ b/NEWS
@@ -1,11 +1,11 @@
-Smap NEWS -- history of user-visible changes. 2010-06-18
+Smap NEWS -- history of user-visible changes. 2010-06-19
Copyright (C) 2006, 2007, 2008, 2009, 2010 Sergey Poznyakoff
See the end of file for copying conditions.
Please send Smap bug reports to <gray+smap@gnu.org.ua>
-Version 0.0.93 (Git)
+Version 0.0.94 (Git)
* First release
diff --git a/configure.ac b/configure.ac
index 7ccd286..5848e32 100644
--- a/configure.ac
+++ b/configure.ac
@@ -17,7 +17,7 @@
AC_PREREQ(2.63)
m4_define([SMAP_VERSION_MAJOR], 0)
m4_define([SMAP_VERSION_MINOR], 0)
-m4_define([SMAP_VERSION_PATCH], 93)
+m4_define([SMAP_VERSION_PATCH], 94)
AC_INIT([smap],
SMAP_VERSION_MAJOR.SMAP_VERSION_MINOR[]m4_ifdef([SMAP_VERSION_PATCH],.SMAP_VERSION_PATCH),
[gray+smap@gnu.org.ua])
diff --git a/doc/Config b/doc/Config
index ecd455f..51a1c1d 100644
--- a/doc/Config
+++ b/doc/Config
@@ -113,6 +113,7 @@ $print_foot_navigation = \&gray_print_foot_navigation;
$print_About = \&gray_print_About;
$cell = \&gray_multitable_cell;
$print_page_foot = \&gray_print_page_foot;
+$image = \&gray_default_image;
sub gray_multitable_cell($$)
{
@@ -363,3 +364,38 @@ sub gray_print_section
and $nw >= $WORDS_IN_PAGE));
}
}
+
+sub gray_default_image($$$$$$$$$$$)
+{
+ my $file = shift;
+ my $base = shift;
+ my $preformatted = shift;
+ my $file_name = shift;
+ my $alt = shift;
+ my $width = shift;
+ my $height = shift;
+ my $raw_alt = shift;
+ my $extension = shift;
+ my $working_dir = shift;
+ my $file_path = shift;
+
+ if (!defined($file_path) or $file_path eq '')
+ {
+ if (defined($extension) and $extension ne '')
+ {
+ $file = "$base.$extension";
+ }
+ else
+ {
+ $file = "$base.jpg";
+ }
+ main::echo_warn ("no image file for $base, (using $file)");
+ }
+ $alt = &$protect_text($base) if (!defined($alt) or ($alt eq ''));
+ return "[ $alt ]" if ($preformatted);
+ # it is possible that $file_name is more correct as it allows the user
+ # to chose the relative path.
+ $file = &$protect_text($file_name);
+ return "<img src=\"/software/smap/graphics/$file\" alt=\"$alt\">";
+}
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1a6e3b0..d1e8bdb 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -19,7 +19,8 @@ smap_TEXINFOS=\
fdl.texi\
sockmap.texi\
debugcat.texi\
- ex-meta1.texi
+ ex-meta1.texi\
+ macros.texi
EXTRA_DIST = \
gendocs_template\
@@ -71,6 +72,8 @@ manual:
$(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual'
manual.tar.bz2: manual
- tar cfj manual.tar.bz2 manual
+ tar cf manual.tar manual
+ tar -r -f manual.tar --transform 's|^|graphics/|' smapflow.png
+ bzip2 -f manual.tar
man-tar: manual.tar.bz2
diff --git a/doc/ex-meta1.texi b/doc/ex-meta1.texi
index 905e135..1cf02ac 100644
--- a/doc/ex-meta1.texi
+++ b/doc/ex-meta1.texi
@@ -2,6 +2,7 @@
@c Copyright (C) 2010 Sergey Poznyakoff
@c See file smap.texi for copying conditions.
@c *******************************************************************
+@cindex MeTA1
In this appendix we will show how to use the @samp{mailutils}
module (@pxref{mailutils module}) to configure local user and alias maps for
@acronym{MeTA1}. For this purpose, we will assume that the actual
diff --git a/doc/gendocs_template b/doc/gendocs_template
index 30bf3c4..0e0bb50 100755
--- a/doc/gendocs_template
+++ b/doc/gendocs_template
@@ -4,7 +4,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
- <title>Mailfromd - General-Purpose Mail Filter</title>
+ <title>SMAP - Socket Map Server</title>
<link rev="made" href="mailto:gray@gnu.org.ua" />
<link rel="stylesheet" type="text/css" href="gray.css" />
<link rel="icon" type="image/png" href="/graphics/gnu-head-icon.png" />
@@ -12,7 +12,7 @@
<body>
<!--#include virtual="inc/header.html" -->
<ul class='tabs'>
- <li><a href="mailfromd.html">Main</a></li>
+ <li><a href="smap.html">Main</a></li>
<li><a href="download.html">Downloads</a></li>
<li><a class="active" href="manual.html">Documentation</a></li>
</ul>
diff --git a/doc/macros.texi b/doc/macros.texi
new file mode 100644
index 0000000..810c6a0
--- a/dev/null
+++ b/doc/macros.texi
@@ -0,0 +1,13 @@
+@c This file is part of the Smap manual.
+@c Copyright (C) 2010 Sergey Poznyakoff
+@c See file smap.texi for copying conditions.
+@c *******************************************************************
+@macro smapdopidx{long,short}
+@opindex \short\, -\short\ option, @command{smapd}
+@opindex \long\, --\long\ option, @command{smapd}
+@end macro
+
+@macro smapcopidx{long,short}
+@opindex \short\, -\short\ option, @command{smapc}
+@opindex \long\, --\long\ option, @command{smapc}
+@end macro
diff --git a/doc/smap.texi b/doc/smap.texi
index 452d4f5..6faef2c 100644
--- a/doc/smap.texi
+++ b/doc/smap.texi
@@ -21,6 +21,7 @@
@syncodeindex fl cp
@include version.texi
+@include macros.texi
@ifinfo
@dircategory Email
@@ -284,6 +285,7 @@ this request.
@node smapd
@chapter The Socket Map Server
+@prindex smapd
Socket map server @command{smapd} is the main part of the package.
When invoked, it reads the @dfn{configuration file} and parses its
command line to determine its configuration settings. Command line
@@ -313,6 +315,7 @@ Comments are introduced with the @samp{#} character: the character
itself and everything after it up to next newline is ignored. For a
detailed description, see @ref{smapd-config}.
+@cindex smapd, alternative configuration file for
You can instruct @command{smapd} to read an alternative
configuration file instead of the default one. It may be necessary,
for example, to test a new configuration. To do so, use the
@@ -323,6 +326,7 @@ option. Its argument specifies the file name to read, e.g.:
$ smapd -c ./mysmapd.conf
@end example
+@cindex smapd, configuration checking
To check whether your configuration is error-free, use the
@option{--lint} (@option{-t}) option. It instructs @command{smapd} to
parse the configuration file and exit after that. Any errors found
@@ -390,6 +394,7 @@ using @samp{inet-mode yes} statement.
@section Logging
@cindex logging
@cindex diagnostics
+@cindex syslog
The server determines automatically where its diagnostics output
should go. By default, it goes to standard error. However, after
detaching from the terminal in standalone mode, @command{smapd}
@@ -417,6 +422,9 @@ command line, using the @option{--log-tag} (@option{-L}) option,
@node debugging
@section Tracing and Debugging
+@cindex debugging
+@cindex query traces
+@cindex tracing queries
The amount of information logged by the server is configurable.
By default, it is quite silent and outputs only diagnostics
that call to special attention, such as errors and the like. You may
@@ -443,6 +451,8 @@ file.
priority.
@anchor{trace-pattern}
+@cindex trace patterns
+@cindex patterns in query traces
Some requests may be of particular interest to you, whereas others
may not be relevant at all. There is a way to abridge the traces to
show those relevant requests only. If you give the
@@ -468,11 +478,18 @@ trace-pattern OK
statements) may be given. The server will log only those queries that
match one of the patterns specified by them.
+@cindex debugging information
@dfn{Debugging information} is auxiliary diagnostics reflecting
various details of internal functionality of @command{smapd}.
Although aimed primarily to help in debugging the server, it may
occasionally be of use for server administrators as well.
+@cindex debugging specification
+@cindex specification, debugging
+@cindex debug level
+@cindex level, debugging
+@cindex debug category
+@cindex category, debugging
Debugging information is requested using the @option{--debug}
(@option{-x}) command line option or @samp{debug} configuration
statement. In both cases, the argument is a @dfn{debug
@@ -494,6 +511,9 @@ option (or @samp{debug} configuration statements).
@node privileges
@section Runtime Privileges
+@cindex runtime privileges
+@cindex privileges, runtime
+@cindex setuid
By default @command{smapd} runs with the privileges of the user that
started it. Normally, this user is root. If you wish it to switch to
some unprivileged user after startup, use the @code{user}
@@ -539,12 +559,14 @@ this technique.
@node servers
@section Server Configuration
+@cindex server configuration
@dfn{Servers} are internal @command{smapd} objects, responsible for
listening on sockets and handling socket I/O operations. Each server
has a @dfn{server id}, which is a unique name associated to it, and
@dfn{socket address}, which describes the socket this server handles.
@anchor{smap url}
+@cindex URL
Socket addresses are represented as @dfn{URL}s. Smap version
@value{VERSION} recognizes the following URL forms:
@@ -568,6 +590,7 @@ unix:///var/run/smap.sock
means UNIX socket @file{/var/run/smap.sock}.
@end table
+@kwindex server
The @code{server} statement configures servers. It takes two
mandatory arguments: the socked ID and URL, e.g.:
@@ -689,12 +712,12 @@ be omitted. There are following cases:
Set only owner GID, do not change the UID.
@end table
-
Note, that this statement cannot be used outside of @code{server} scope.
@end deffn
@node loadable modules
@section Loadable Modules
+@cindex modules
@dfn{Mapper modules} are external pieces of software designed to
handle a particular subset of map queries. They are built as
shared libraries and loaded into @command{smapd} at startup.
@@ -709,6 +732,8 @@ The @var{module-id} is a unique identifier, which will subsequently be
used to refer to that module.
@end deffn
+@cindex load path
+@cindex module load path
A @dfn{module load path} is an internal list of directories which
@command{smapd} scans in order to find a loadable file name specified in
@code{module} statement. By default the scan order is as follows:
@@ -724,6 +749,8 @@ set by the file @file{/etc/ld.so.conf} and the environment variable
@env{LD_LIBRARY_PATH}).
@end enumerate
+@vrindex LTDL_LIBRARY_PATH
+@vrindex LD_LIBRARY_PATH
Values of @env{LTDL_LIBRARY_PATH} and @env{LD_LIBRARY_PATH} must be
colon-separated lists of absolute directory names, for example:
@samp{/usr/lib/mypkg:/lib/foo'}.
@@ -750,6 +777,7 @@ directory names.
@node databases
@section Databases
+@cindex database, smap
A @dfn{database} is a logical entity associated with a particular
module, that provides a specific configuration for it. In other
words, database is a configured instance of the module.
@@ -780,6 +808,9 @@ string @samp{TEMP Try again later}.
@node dispatch rules
@section Query Dispatch Rules
+@cindex dispatch rules
+@cindex rules, dispatch
+@kwindex dispatch
When a query arrives, @command{smapd} uses @dfn{query dispatch rules} to
decide to what database to dispatch this query. Dispatch rules are
somewhat similar to ACLs: each rule consists of a set of conditions
@@ -791,6 +822,7 @@ indicates the database to dispatch this query to. If the list is
exhausted and no matching rule was found, @command{smapd} sends back
the default @samp{NOTFOUND} reply.
+@kwindex map
Consider for example the following rule:
@example
@@ -820,6 +852,7 @@ dispatch map regexp /(alias)|(virtusers)/ database maildb
@xref{cond-map, The map condition}, for a detailed description of this
condition.
+@kwindex from
Another important condition is @code{from}. It returns @samp{True}
if its argument, which is an IP address or a CIDR, matches the IP of
the machine that sent the query. For example, the following rule
@@ -875,6 +908,7 @@ dispatch from 192.168.0.0/27 \
database user
@end example
+@kwindex default, dispatch condition
There is a special condition which is convenient for the last rule
in the list. The @samp{default} condition always returns @samp{True},
so this rule:
@@ -889,6 +923,11 @@ The @samp{default} condition cannot be combined with other conditions.
@node exit codes
@section Smapd Exit Codes
+@cindex exit codes
+@kwindex EX_OK
+@kwindex EX_USAGE
+@kwindex EX_UNAVAILABLE
+@kwindex EX_CONFIG
The following table summarizes exit codes used by @command{smapd}.
For each code it lists its decimal number, symbolic name from the
@file{sysexits.h} header file, and its meaning.
@@ -903,10 +942,14 @@ For each code it lists its decimal number, symbolic name from the
@node smapd-options
@chapter Command Line Syntax
+@cindex options, command line
+@cindex command line options
Most command line options have two forms, called short and long
forms. Both forms are absolutely identical in function; they are
interchangeable.
+@cindex short option form
+@cindex option, short form
The @dfn{short} form is a traditional form for UNIX utilities.
In this form, the option consists of a single dash, followed by a
single letter, e.g. @option{-c}.
@@ -925,6 +968,8 @@ the last option in such a cluster, otherwise it would be impossible to
specify the argument for it. Anyway, it is much more readable to
specify such options separated.
+@cindex long option form
+@cindex option, long form
The @dfn{long} option names are probably easier to memorize than
their short counterparts. They consist of two dashes, followed by a
multi-letter option name, which is usually selected to be a mnemonics
@@ -953,67 +998,82 @@ and a cross reference is provided to more in-depth explanation in the
body of the manual.
@table @option
+@smapdopidx{c, config}
@item -c @var{file}
@itemx --config=@var{file}
Read configuration from @var{file}, instead of the default
@file{/etc/smapd.conf}. @xref{smapd,, --config}.
+@smapdopidx{t, lint}
@item -t
@itemx --lint
Test configuration and exit with code @samp{0} if the file
parsed without errors and @samp{78} otherwise. Any errors found
are reported on the standard error. @xref{smapd,, --lint}.
+@smapdopidx{f, foreground}
@item -f
@itemx --foreground
Do not detach from the controlling terminal, operate in foreground.
+@smapdopidx{e, stderr}
@item -e
@itemx --stderr
Output diagnostic to stderr. @xref{logging}.
+@smapdopidx{l, syslog}
@item -l
@itemx --syslog
Output diagnostic to syslog (default). @xref{logging}.
+@smapdopidx{s, single-process}
@item -s
@itemx --single-process
Operate in single-process mode. This option is intended to help in
debugging @command{smapd}. @emph{Do not use it in production
environment!}
+@smapdopidx{i, inetd}
@item -i
@itemx --inetd
Operate in inetd mode (@pxref{inetd-mode}).
+@smapdopidx{T, trace}
@item -T
@itemx --trace
Trace queries and replies. @xref{debugging,, Query traces}.
+@smapdopidx{p, trace-pattern}
@item -p @var{pattern}
@itemx --trace-pattern=@var{pattern}
Trace only queries that begin with the given @var{pattern}.
@xref{trace-pattern}.
+@smapdopidx{x, debug}
@item -x @var{level}
@itemx --debug=@var{level}
Set debug verbosity level. @xref{debugging,,Debugging information}.
+@smapdopidx{L, log-tag}
@item -L
@itemx --log-tag=@var{tag}
Set syslog tag. @xref{logging}.
-@item -f @var{facility}
+@smapdopidx{F, log-facility}
+@item -F @var{facility}
@itemx --log-facility=@var{facility}
Set syslog facility. @xref{logging,, log-facility}.
+@smapdopidx{h, help}
@item -h
@itemx --help
Give a concise summary of the command line options.
+@opindex --usage, --usage option, @command{smapd}
@item --usage
Give a short usage reminder.
+@smapdopidx{V, version}
@item -V
@itemx --version
Print program version.
@@ -1021,6 +1081,7 @@ Print program version.
@node smapd-config
@chapter Smapd Configuration File
+@cindex configuration file, @command{smapd}
The @command{smapd} configuration file consists, on a lexical level,
of logical lines. A @dfn{logical line} is any sequence of characters
between two unescaped newline characters. The word @samp{unescaped}
@@ -1028,12 +1089,15 @@ means a newline character not preceded by a single backslash. Thus,
escaped newlines allow to combine several physical lines into a single
logical one.
+@cindex comments, configuration
Within a logical line, unescaped @samp{#} character introduces a
comment. The character itself and the rest of characters after it up
to the end of line are ignored.
Empty lines are ignored as well.
+@cindex configuration statement
+@cindex statement, configuration
Each not empty line constitutes a @dfn{configuration statement}.
The statement is first split into words. A @dfn{word} is any
contiguous sequence of non-whitespace characters. Singly-quoted
@@ -1041,6 +1105,7 @@ and doubly-quoted strings are also considered words. Within a
doubly-quoted string, backslash character introduces an @dfn{escape
sequence}. The following escape sequences are supported:
+@cindex escape sequences
@float Table, escape-sequences
@caption{Escape sequences}
@multitable @columnfractions 0.30 .5
@@ -1232,6 +1297,8 @@ following statements are allowed for use in the block statement:
@item reuseaddr
@item single-process
@item user
+@item socket-mode
+@item socket-owner
@end itemize
Their meaning is the same as of the corresponding statements in
@@ -1321,11 +1388,15 @@ algorithm:
@itemx is
Literal equality. Map name must be exactly the same as @var{string}.
+@cindex globbing patterns
+@cindex pattern, globbing
@item like
@itemx fnmatch
Match using shell wildcard patterns (@pxref{glob,Globbing
patterns,,glob(7), Glob(7) man page}).
+@cindex regular expressions
+@cindex expression, regular
@item regexp
Match using regular expressions. @var{String} must have the following
form:
@@ -1377,6 +1448,7 @@ Pass this query to the database @var{dbname} (@pxref{config-database,dbname}).
@node modules
@chapter Modules Shipped with Smap
+@cindex module installation directory
Smap is shipped with a set of loadable modules, which are installed
in its default module directory, @file{@var{$prefix}/lib/smap}. The
modules are configurable on a per-module (@pxref{loadable modules}),
@@ -1394,6 +1466,7 @@ in detail in the following sections.
@node echo module
@section The @samp{echo} Module
+@kwindex echo
The echo module is the simplest of all modules. It sends back a
static reply string, no matter what the query was. This module is
useful for default databases, which catch erroneous or not handled
@@ -1424,11 +1497,13 @@ dispatch default database default
@node mailutils module
@section The @samp{mailutils} Module
+@kwindex mailutils
This module uses GNU Mailutils
(@uref{http://www.gnu.org/software/mailutils}) and provides two main
modes:
@table @samp
+@cindex auth, mailutils mode
@item auth
This mode uses GNU Mailutils authorization mechanism to obtain
user data (similar to the system @samp{getpwnam} routine) and returns
@@ -1436,6 +1511,7 @@ positive reply if the data were retrieved and negative reply
otherwise. @xref{MeTA1}, for an example on how to use it as a local
user and alias database.
+@cindex mbq, mailutils mode
@item mbq
This mode allows to check whether the user's mailbox exceeded the
allotted quota, and if not, whether it is able to accept a message
@@ -1453,51 +1529,68 @@ abbreviation of @dfn{Mailbox Quota}.
@node expansion
@subsection Variable Expansion
+@cindex variable expansion
+@cindex expansion, variable
In the discussion below we often refer to @dfn{meta-variable
expansion} in strings. This is a process, whereby any sequence
@samp{$@{@var{variable}@}} is replaced with the value of
@var{variable}. The defined variables are:
@table @asis
+@kwindex db
@item db
The database name.
+@kwindex map
@item map
The map name.
+@kwindex key
@item key
The lookup key.
+@kwindex diag
@item diag
If the key was not found or some error occurred, this variable expands
to a short diagnostics string, suitable for return message.
Otherwise, expands to empty string.
+@kwindex name
@item name
The @samp{name} field from the retrieved record. Empty string if
the user not found.
+@kwindex passwd
@item passwd
The @samp{passwd} field from the retrieved record. Empty string if
the user not found.
+@kwindex uid
@item uid
The @samp{uid} field from the retrieved record. If the user was not
found, expands to @samp{-1}.
+@kwindex gid
@item gid
The @samp{gid} field from the retrieved record. If the user was not
found, expands to @samp{-1}.
+@kwindex gecos
@item gecos
The @samp{gecos} field from the retrieved record. Empty string if
the user not found.
+@kwindex dir
@item dir
The @samp{dir} field from the retrieved record. Empty string if
the user not found.
+@kwindex shell
@item shell
The @samp{shell} field from the retrieved record. Empty string if
the user not found.
+@kwindex mailbox
@item mailbox
The @samp{mailbox} field from the retrieved record. Empty string if
the user not found.
+@kwindex quota
@item quota
The @samp{quota} field from the retrieved record. If the user was not
found, expands to @samp{NONE}.
+@kwindex mbsize
@item mbsize
Mailbox size, in bytes. Defined only in @samp{mbq} mode.
+@kwindex msgsize
@item msgsize
Expected message size, in bytes. Defined only in @samp{mbq} mode.
@end table
@@ -1512,13 +1605,16 @@ module mailutils mailutils [args]
Arguments are:
@table @option
+@kwindex config-verbose
@item config-verbose
Verbosely trace the processing of the main Mailutils configuration
files.
+@kwindex config-dump
@item config-dump
Dump the parse tree from the Mailutils configuration.
+@kwindex positive-reply
@item positive-reply=@var{str}
Declare default positive reply string. This string is returned when
the underlying database was able to found the requested key. Prior
@@ -1527,6 +1623,7 @@ above.
Default positive reply string is @samp{OK}.
+@kwindex negative-reply
@item negative-reply=@var{str}
Declare default negative reply string. This string is returned when
the underlying database failed to found the requested key. Prior
@@ -1534,12 +1631,15 @@ to returning, @var{str} is subject to meta-variable expansion.
Default negative reply string is @samp{NOTFOUND}.
+@kwindex onerror-reply
@item onerror-reply=@var{str}
Declare a reply to be returned on error. Prior
to returning, @var{str} is subject to meta-variable expansion.
Default string is @samp{NOTFOUND}.
@end table
+@cindex configuration file, mailutils
+@cindex mailutils configuration file
The module reads most of its configuration settings from the main
Mailutils configuration file. @xref{configuration, Mailutils Configuration
File,, mailutils, GNU Mailutils Manual}, for a description of GNU
@@ -1590,6 +1690,7 @@ is assumed. Optional @var{args} may be used to supply additional
database configuration. These are:
@table @option
+@kwindex positive-reply
@item positive-reply=@var{str}
Declare positive reply string. This string is returned when
the underlying database was able to found the requested key. Prior
@@ -1600,6 +1701,7 @@ Default positive reply string is @samp{OK}, unless overridden by the
module-level @option{positive-reply} option (@pxref{db-mailutils,
positive-reply}.
+@kwindex negative-reply
@item negative-reply=@var{str}
Declare negative reply string. This string is returned when
the underlying database failed to found the requested key. Prior
@@ -1609,6 +1711,7 @@ Default negative reply string is @samp{NOTFOUND}, unless overridden by the
module-level @option{positive-reply} option (@pxref{db-mailutils,
negative-reply}.
+@kwindex onerror-reply
@item onerror-reply=@var{str}
Declare a reply to be returned on error. Prior
to returning, @var{str} is subject to meta-variable expansion.
@@ -1619,6 +1722,7 @@ onerr-reply}.
@node auth
@subsection Mailutils Auth Mode
+@cindex auth mode, mailutils
Mailutils module in @samp{auth} mode uses GNU Mailutils
authorization mechanism to obtain user data. It returns
@samp{positive-reply} if the data were retrieved and @samp{negative-reply}
@@ -1627,7 +1731,8 @@ aliases. The key is normally a user name (either local part or fully
qualified).
@xref{MeTA1}, for an example on how to use it.
-
+
+@cindex mbq mode, mailutils
@node mbq
@subsection Mailutils MBQ Mode
@acronym{MBQ}, or @dfn{Mailbox Quota} mode, uses key as the name of
@@ -1649,8 +1754,10 @@ Two additional meta-variables may be used in reply templates to return
quota-related information:
@table @asis
+@kwindex mbsize
@item mbsize
Mailbox size, in bytes. Defined only in @samp{mbq} mode.
+@kwindex msgsize
@item msgsize
Expected message size, in bytes. Defined only in @samp{mbq} mode.
@end table
@@ -1688,6 +1795,7 @@ violating its quota.
@node guile module
@section The @samp{guile} Module
+@cindex guile module
@dfn{Guile} is an acronym for @dfn{GNU's Ubiquitous Intelligent
Language for Extensions}. It provides a Scheme interpreter conforming
to the R5RS language specification and a number of convenience
@@ -1796,18 +1904,23 @@ its @code{cdr} gives the corresponding function. The defined function
names and their semantics are described in the following table:
@table @asis
+@kwindex init
@item init
Initialize the module.
+@kwindex done
@item done
Close the module, releasing any resources held by it.
+@kwindex open
@item open
Open the database.
+@kwindex close
@item close
Close the database.
+@kwindex query
@item query
Handle a socket map query
@end table
@@ -1831,6 +1944,7 @@ Particular virtual functions are described in @ref{Guile API}.
@node Guile Output Ports
@subsection Guile Output Ports
+@cindex output ports, Guile
Guile modules are executed in a specially prepared environment.
Current error port is redirected so that everything written to it ends
up in the @command{smapd} error stream. So, if @command{smapd} is
@@ -2016,6 +2130,9 @@ the current output port, e.g.:
@node smapc
@chapter Socket map client
@cindex smapc, socket client utility
+@cindex single query mode, @command{smapc}
+@cindex interactive mode, @command{smapc}
+@cindex mode, @command{smapc}
The @command{smapc} program is a console-based utility for querying
socket map servers. It has two operation modes. In @dfn{single query
mode}, the utility performs a query, displays its result and exits
@@ -2085,6 +2202,8 @@ OK smith dmk <rev@@another.domain>
@node Interactive Mode
@section Interactive Mode
+@cindex interactive mode
+@cindex readline
If insufficient number of arguments is given in the command line,
@command{smapc} enters interactive mode. In this mode it reads
commands from the standard input, executes them and displays the
@@ -2101,6 +2220,8 @@ of the program, enclosed in parentheses:
(smapc) _
@end example
+@cindex command prefix
+@cindex prefix, command
Depending on the first character, your input is recognized either as
a @command{smapc} command, or as a query. All @command{smapc}
commands begin with a single punctuation character, called
@@ -2138,6 +2259,7 @@ If you wish to change to another URL, give another @samp{open}
command. Do not bother to close the previously opened socket: it will
be done automatically.
+@cindex default map
@anchor{smapc-defmap}
@kwindex map
If you are going to send a series of queries using the same map, you
@@ -2297,7 +2419,6 @@ Displays the copyright statement.
@node Initialization File
@section Initialization File
-@section Initialization File
@cindex init file
@cindex initialization file
@findex .smapc
@@ -2339,6 +2460,7 @@ and a cross reference is provided to more in-depth explanation in the
body of the manual.
@table @option
+@smapcopidx{B, batch}
@item -B
@itemx --batch
Enable batch mode. This mode is optimized for reading input from
@@ -2347,42 +2469,52 @@ input history are disabled, and input prompt is not shown. This
mode is enabled automatically if @command{smapd} detects that its
standard input is not connected to a terminal.
+@smapcopidx{p, prompt}
@item -p @var{string}
@itemx --prompt=@var{string}
Change command prompt. @xref{smapc-prompt}.
+@smapcopidx{Q, quiet}
@item -Q
@itemx --quiet
Do not print the normal welcome banner. @xref{smapc-quiet}.
+@smapcopidx{q, norc}
@item -q
@itemx --norc
Do not read initialization file. @xref{Initialization File}.
+@smapcopidx{S, server}
@item -S @var{url}
@itemx --server=@var{url}
Connect to server at the given @var{url}. @xref{smapc-open}.
+@smapcopidx{s, source}
@item -s @var{addr}
@itemx --source=@var{addr}
Set source address. @xref{smapc-source}.
+@smapcopidx{T, trace}
@item -T
@itemx --trace
Enable query traces. @xref{debugging, traces}.
+@smapcopidx{x, debug}
@item -x @var{spec}
@itemx --debug=@var{spec}
Set debug verbosity level. @xref{debugging, Debugging information},
for a detailed description.
+@smapcopidx{h, help}
@item -h
@itemx --help
Give a short summary of available command line options.
+@opindex --usage, --usage option, @command{smapc}
@item --usage
Display a list of available command line options.
+@smapcopidx{V, version}
@item -V
@itemx --version
Print program version and exit.

Return to:

Send suggestions and report system problems to the System administrator.