/[mailutils]/mailutils/doc/texinfo/programs.texi
ViewVC logotype

Diff of /mailutils/doc/texinfo/programs.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.20 by gray, Wed Oct 2 14:41:17 2002 UTC revision 1.21 by gray, Sun Nov 24 22:15:51 2002 UTC
# Line 1  Line 1 
1               @c This is part of the GNU Mailutils manual.  @c This is part of the GNU Mailutils manual.
2  @c Copyright (C) 1999,2000,2001 Free Software Foundation, Inc.  @c Copyright (C) 1999,2000,2001,2002 Free Software Foundation, Inc.
3  @c See file mailutils.texi for copying conditions.  @c See file mailutils.texi for copying conditions.
4  @comment *******************************************************************  @comment *******************************************************************
5    
# Line 196  or single quotes). Line 196  or single quotes).
196  @menu  @menu
197  * default::        Options understood by most GNU utilities.  * default::        Options understood by most GNU utilities.
198  * mailbox::        Specifies the mail spool location, and locking strategy.  * mailbox::        Specifies the mail spool location, and locking strategy.
199    * mailer::         Sets the mailer URL.
200  * address::        Specifies the default email address and domain.  * address::        Specifies the default email address and domain.
201  * daemon::         Options common for daemon programs.  * daemon::         Options common for daemon programs.
202  * auth::           Authentication-specific options.  * auth::           Authentication-specific options.
# Line 238  Set path to the mailspool directory Line 239  Set path to the mailspool directory
239  Set the default mailbox lock flags (E=external, R=retry, T=time, P=pid).  Set the default mailbox lock flags (E=external, R=retry, T=time, P=pid).
240  @end table  @end table
241    
242    @node mailer
243    @subsection mailer --- Sets the default mailer URL.
244    @cindex :mailer
245    
246    This option group overrides the default mailer URL (@url{sendmail:}).
247    
248    @table @option
249    @item -m @var{url}
250    @itemx --mailer @var{url}
251    @end table
252    
253  @node address  @node address
254  @subsection address --- Specifies the default email address and domain.  @subsection address --- Specifies the default email address and domain.
255  @cindex :address  @cindex :address
# Line 2179  utilities in detail. Line 2191  utilities in detail.
2191  @subsection A Sieve Interpreter  @subsection A Sieve Interpreter
2192    
2193  Sieve interpreter @command{sieve} allows to apply Sieve scripts to an  Sieve interpreter @command{sieve} allows to apply Sieve scripts to an
2194  arbitrary number of mailboxes. Currently @command{sieve} supports the  arbitrary number of mailboxes. GNU @command{sieve} supports full set
2195  following actions:  of actions and tests described in RFC 3028.
2196    
2197  @itemize  @menu
2198  @item stop  * Invoking Sieve::
2199  @item keep  * Logging and Debugging::
2200  @item discard  * Input Language::
2201  @item fileinto  * Extending Sieve::
2202  @end itemize  @end menu
2203    
2204  @subheading Invocation  @node Invoking Sieve
2205    @subsubsection Invocation
2206    
2207  The @command{sieve} invocation syntax is:  The @command{sieve} invocation syntax is:
2208    
# Line 2212  Specify debug flags. The @var{flags} arg Line 2225  Specify debug flags. The @var{flags} arg
2225  more of the following letters:  more of the following letters:
2226    
2227  @multitable @columnfractions .40 .45  @multitable @columnfractions .40 .45
 @item @samp{a} @tab Enable address parser traces  
2228  @item @samp{g} @tab Enable main parser traces  @item @samp{g} @tab Enable main parser traces
2229  @item @samp{T} @tab Enable mailutil traces  @item @samp{T} @tab Enable mailutil traces
2230  @item @samp{P} @tab Trace network protocols  @item @samp{P} @tab Trace network protocols
2231  @item @samp{t} @tab Enable sieve trace  @item @samp{t} @tab Enable sieve trace
2232  @item @samp{h} @tab Debug sieve header filling  @item @samp{i} @tab Trace the program instructions
 @item @samp{q} @tab Trace sieve message queries  
2233  @end multitable  @end multitable
2234    
2235  When omitted, @var{flags} defaults to @samp{TPt}.  @xref{Logging and Debugging}, for detailed discussion of these.
2236    
2237    @item -D
2238    @itemx --dump
2239    Compile the script, dump disassembled code on standard output and exit.
2240    
2241    @item -e @var{address}
2242    @item --email @var{address}
2243    Override the user email address. This is useful for @code{reject} and
2244    @code{redirect} actions. By default, the user email address is deduced
2245    from the user name and the full name of the machine where sieve is
2246    executed.
2247    
2248  @item -f  @item -f
2249  @itemx --mbox-url=@var{mbox}  @itemx --mbox-url=@var{mbox}
# Line 2231  Mailbox to sieve (defaults to user's sys Line 2253  Mailbox to sieve (defaults to user's sys
2253  @itemx --keep-going  @itemx --keep-going
2254  Keep on going if execution fails on a message  Keep on going if execution fails on a message
2255    
 @item -M  
 @itemx --mailer-url=@var{mailer}  
 Override the mailer URL (defaults to "sendmail:")  
   
2256  @item -n  @item -n
2257  @itemx --no-actions  @itemx --no-actions
2258  Dry run: do not execute any actions, just print what would be done.  Dry run: do not execute any actions, just print what would be done.
# Line 2242  Dry run: do not execute any actions, jus Line 2260  Dry run: do not execute any actions, jus
2260  @item -t @var{ticket}  @item -t @var{ticket}
2261  @itemx --ticket=@var{ticket}  @itemx --ticket=@var{ticket}
2262  Ticket file for mailbox authentication  Ticket file for mailbox authentication
2263    
2264    @item -v
2265    @itemx --verbose
2266    Log all actions executed.
2267  @end table  @end table
2268    
2269  Apart from these, @command{sieve} understands the options from the  Apart from these, @command{sieve} understands the options from the
2270  @code{mailbox} option group (@pxref{mailbox}).  following groups: @code{mailbox}, @code{mailer}, @code{logging}.
2271    
2272    @node Logging and Debugging
2273    @subsubsection Logging and debugging
2274    
2275    The default behavior of @command{sieve} is to remain silent about
2276    anything except errors. However, it is sometimes necessary to see
2277    which actions are executed and on which messages. This is particularly
2278    useful when debugging the sieve scripts. The @option{--verbose}
2279    (@option{-v}) option outputs log of every action executed.
2280    
2281    Option @option{--debug} allows to produce even more detailed debugging
2282    information. This option takes an argument specifying the
2283    debugging level to be enabled. The argument can consist of the
2284    following letters:
2285    
2286    @table @samp
2287    @item @samp{t}
2288    This flag enables sieve tracing. It means that every test will be logged
2289    when executed.
2290    
2291    @item @samp{T}
2292    This flag enables debugging of underlying @code{mailutils} library.
2293    
2294    @item @samp{P}
2295    Trace network protocols: produces log of network transactions executed
2296    while running the script.
2297    
2298    @item @samp{g}
2299    Enable main parser traces. This is useful for debugging the sieve grammar.
2300    
2301    @item @samp{i}
2302    Trace the program instructions. It is the most extensive debugging
2303    level. It produces the full execution log of a sieve program, showing
2304    each instruction and states of the sieve machine. It is only useful
2305    for debugging the code generator.
2306    @end table
2307    
2308    @emph{Note}, that there should be no whitespace
2309    between the short variant of the option (@option{-d}), and its
2310    argument.  Similarly, when using long option (@option{--debug}),
2311    its argument must be preceded by equal sign.
2312    
2313    If the argument to @option{--debug} is omitted, it defaults to
2314    @samp{TPt}.
2315    
2316    Option @option{--dump} produces the disassembled dump of the compiled
2317    sieve program.
2318    
2319    By default @command{sieve} output all diagnostics on standard error and verbose
2320    logs on standard output. This behaviour is changed when
2321    @option{--log-facility} is given in the command line (@pxref{logging}).
2322    This option causes @command{sieve} to output its diagnostics to
2323    the given syslog facility.
2324    
2325    @node Input Language
2326    @subsubsection Input Language
2327    
2328    @node Extending Sieve
2329    @subsubsection Extending Sieve
2330    The basic set of sieve actions, tests and comparators may be extended
2331    using loadable extensions. Usual @code{require} mechanism is used for
2332    that.
2333    
2334    When processing arguments for @code{require} statement, @command{sieve}
2335    uses the following algorithm:
2336    
2337    @enumerate 1
2338    @item Look up the name in a symbol table. If the name begins with
2339    @samp{comparator-} it is looked up in the comparator table. If it
2340    begins with @samp{test-}, the test table is used instead. Otherwise
2341    the name is looked up in the action table.
2342    
2343    @item If the name is found, the search is terminated.
2344    
2345    @item Otherwise, transform the name. First, any @samp{comparator-} or
2346    @samp{test-} prefix is stripped. Then, any character other than
2347    alphanumeric characters, @samp{.} and @samp{,} is replaced with
2348    dash (@samp{-}). The name thus obtained is used as a file name
2349    of an external loadable module.
2350    
2351    @item Try to load the module. The module is searched in the
2352    following search paths (in the order given):
2353    
2354    @enumerate 1
2355    @item Mailutils module directory. By default it is
2356    @file{$prefix/lib/mailutils}.
2357    
2358    @item The value of the environment variable LTDL_LIBRARY_PATH.
2359    
2360    @item System library search path: The system dependent library
2361    search path (e.g. on Linux it is set by the contents of the file
2362    @file{/etc/ld.so.conf} and the value of the environment variable
2363    LD_LIBRARY_PATH).
2364    
2365    @end enumerate
2366    
2367    Each search path must be a colon-separated list of absolute directories,
2368    for example, @samp{"/usr/lib/mypkg:/lib/foo"}.
2369    
2370    In any of these directories, @command{sieve} first attempts to find
2371    and load the given filename. If this fails, it tries to append the
2372    following suffixes to the file name:
2373    
2374    @enumerate 1
2375    @item the libtool archive extension @samp{.la}
2376    
2377    @item the extension used for native dynamic libraries on the host
2378    platform, e.g., @samp{.so}, @samp{.sl}, etc.
2379    @end enumerate
2380    
2381    @item If the module is found, @command{sieve} executes its
2382    initialization function (see below) and again looks up the name
2383    in the symbol table. If found, search terminates successfully.
2384    
2385    @item If either the module is not found, or the symbol wasn't
2386    found after execution of the module initialization function,
2387    search is terminated with an error status. @command{sieve} then displays
2388    the following diagnostic message:
2389    
2390    @example
2391    source for the required action NAME is not available
2392    @end example
2393    
2394    @end enumerate
2395    
2396    
2397  @c ***********************************************************************  @c ***********************************************************************
2398    
2399  @page  @page

Legend:
Removed from v.1.20  
changed lines
  Added in v.1.21

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26