diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-06-19 18:18:58 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2010-06-19 18:18:58 +0300 |
commit | 3b49db92dc4a67f72a4d641f3ac9492f4a44578c (patch) | |
tree | 8701771e3e5f3631b03b85e1a62f98f71ef6973d | |
parent | b4ff3aa84bd151a4a575c10b141be425ecc9b867 (diff) | |
download | smap-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
-rw-r--r-- | NEWS | 4 | ||||
-rw-r--r-- | configure.ac | 2 | ||||
-rw-r--r-- | doc/Config | 36 | ||||
-rw-r--r-- | doc/Makefile.am | 7 | ||||
-rw-r--r-- | doc/ex-meta1.texi | 1 | ||||
-rwxr-xr-x | doc/gendocs_template | 4 | ||||
-rw-r--r-- | doc/macros.texi | 13 | ||||
-rw-r--r-- | doc/smap.texi | 140 |
8 files changed, 196 insertions, 11 deletions
@@ -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]) @@ -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 --- /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. |