head 1.18; access; symbols L2_0_9_13:1.18 FSL_1_7_0:1.18 L2_0_9_12:1.18 LMTP2NNTP_1_4_1:1.18 LMTP2NNTP_1_4_0:1.18 FSL_1_6_1:1.18 L2_0_9_11:1.18 FSL_1_6_0:1.17 FSL_1_6b2:1.17 L2_0_9_10:1.17 FSL_1_6b1:1.17 L2_0_9_9:1.17 LMTP2NNTP_1_3_0:1.16 LMTP2NNTP_1_3b2:1.16 LMTP2NNTP_1_3b1:1.16 LMTP2NNTP_1_3a3:1.16 FSL_1_5_0:1.16 LMTP2NNTP_1_3a2:1.16 FSL_1_5a3:1.16 LMTP2NNTP_1_3a1:1.16 FSL_1_5a2:1.16 L2_0_9_8:1.16 FSL_1_5a1:1.16 L2_0_9_7:1.16 L2_0_9_6:1.16 FSL_1_4_0:1.15 FSL_1_4b1:1.15 L2_0_9_5:1.15 FSL_1_4a1:1.15 FSL_1_3_0:1.15 FSL_1_3b1:1.15 L2_0_9_4:1.15 FSL_1_2_1:1.15 L2_0_9_3:1.15 FSL_1_2_0:1.15 L2_0_9_2:1.15 FSL_1_1_0:1.14 FSL_1_1b1:1.14 WORKOFF:1.14.0.2 WORKOFF_BP:1.14 FSL_1_0_8:1.14 LMTP2NNTP_1_2_0:1.14 LMTP2NNTP_1_2b4:1.14 LMTP2NNTP_1_2b3:1.14 LMTP2NNTP_1_2b2:1.14 LMTP2NNTP_1_2b1:1.14 LMTP2NNTP_1_2a8:1.14 LMTP2NNTP_1_2a7:1.14 FSL_1_0_7:1.14 FSL_1_0_6:1.13 FSL_1_0_5:1.13 FSL_1_0_4:1.13 L2_0_9_1:1.13 FSL_1_0_3:1.13 LMTP2NNTP_1_2a6:1.13 FSL_1_0_2:1.13 FSL_1_0_1:1.13 FSL_1_0_0:1.13 FSL_0_9_0:1.13 L2_0_9_0:1.13 FSL_0_1_12:1.12 FSL_0_1_11:1.12 FSL_0_1_10:1.12 FSL_0_1_9:1.12 FSL_0_1_8:1.12 FSL_0_1_7:1.12 FSL_0_1_6:1.12 FSL_0_1_5:1.12 FSL_0_1_1:1.12 LMTP2NNTP_1_2a5:1.12 LMTP2NNTP_1_2a4:1.12 LMTP2NNTP_1_2a3:1.12 LMTP2NNTP_1_2a1:1.11 LMTP2NNTP_1_1_1:1.7 LMTP2NNTP_1_1_0:1.7 LMTP2NNTP_1_1b4:1.7 LMTP2NNTP_1_1b3:1.7 L2_CHANNEL_ONLY_REVAMPING_BEFORE:1.7 LMTP2NNTP_1_1b2:1.7 LMTP2NNTP_1_1b1:1.7 L2_0_1_0:1.4 START_MICHAEL:1.4 L2_INITIAL:1.1.1.1 OSSP:1.1.1; locks; strict; comment @# @; 1.18 date 2005.10.03.08.08.11; author rse; state Exp; branches; next 1.17; 1.17 date 2005.01.24.15.03.17; author rse; state Exp; branches; next 1.16; 1.16 date 2004.02.17.09.21.04; author thl; state Exp; branches; next 1.15; 1.15 date 2003.06.30.11.13.08; author thl; state Exp; branches; next 1.14; 1.14 date 2003.01.06.11.41.51; author rse; state Exp; branches 1.14.2.1; next 1.13; 1.13 date 2002.07.30.19.08.24; author rse; state Exp; branches; next 1.12; 1.12 date 2002.01.02.17.07.38; author rse; state Exp; branches; next 1.11; 1.11 date 2001.12.08.20.58.14; author rse; state Exp; branches; next 1.10; 1.10 date 2001.11.16.23.00.47; author rse; state Exp; branches; next 1.9; 1.9 date 2001.11.15.09.47.32; author ms; state Exp; branches; next 1.8; 1.8 date 2001.11.09.12.45.37; author rse; state Exp; branches; next 1.7; 1.7 date 2001.09.20.16.26.56; author ms; state Exp; branches; next 1.6; 1.6 date 2001.09.14.19.22.38; author rse; state Exp; branches; next 1.5; 1.5 date 2001.09.14.13.26.16; author rse; state Exp; branches; next 1.4; 1.4 date 2001.08.15.10.36.03; author rse; state Exp; branches; next 1.3; 1.3 date 2001.05.11.19.50.52; author rse; state Exp; branches; next 1.2; 1.2 date 2001.05.10.20.00.31; author rse; state Exp; branches; next 1.1; 1.1 date 2001.05.10.19.46.01; author rse; state Exp; branches 1.1.1.1; next ; 1.14.2.1 date 2004.02.17.09.22.00; author thl; state Exp; branches; next ; 1.1.1.1 date 2001.05.10.19.46.01; author rse; state Exp; branches; next ; desc @@ 1.18 log @Adjust copyright messages for new year 2005. @ text @## ## OSSP l2 - Flexible Logging ## Copyright (c) 2001-2005 Cable & Wireless ## Copyright (c) 2001-2005 The OSSP Project ## Copyright (c) 2001-2005 Ralf S. Engelschall ## ## This file is part of OSSP l2, a flexible logging library which ## can be found at http://www.ossp.org/pkg/lib/l2/. ## ## Permission to use, copy, modify, and distribute this software for ## any purpose with or without fee is hereby granted, provided that ## the above copyright notice and this permission notice appear in all ## copies. ## ## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF ## SUCH DAMAGE. ## ## l2.pod: Unix manual page for C API ## =pod =head1 NAME B - Flexible Logging =head1 VERSION OSSP l2 L2_VERSION_STR =head1 SYNOPSIS ... =head1 DESCRIPTION B is a C library providing a very flexible and sophisticated Unix logging facility. It is based on the model of arbitrary number of channels, stacked together in a top-down data flow tree structure with filtering channels in internal nodes and output channels on the leave nodes. Channel trees can be either constructed manually through lower-level API functions or all at once with a single API function controlled by a compact syntactical description of the channel tree. For generating log messages a printf-style formatting engine is provided which can be extended through callback functions. The data flow inside the channel tree is controlled by (eight fixed and nine custom) logging message severity levels which are assigned to each individual channel. Channels are implemented by channel handlers which can be even customer supplied for creating own channels which seamlessly integrate into the framework. For convenience reasons, B already ships with pre-implemented filtering (noop, filter, prefix, buffer) and output (null, fd, file, pipe, socket, syslog, smtp) channels which already cover mostly all use cases of logging. A language is provided to allow for channel specification and configuration. Thus, the channel tree can be constructed either by the API and its ANSI C bindings or through the use of this B channel definition language. Applying the API allows fine grained control of the channel tree. Additionally, the API allows for a more interactive channel definition. However, using the channel definition language to define the channel tree is more convenient, and takes less coding effort. The channel definition language is almost always sufficient for an application using B. =head1 LOGGING LEVELS PANIC fatal error -> immediate abort (SIGBUS, SIGSEGV) CRITICAL temporary failure -> sleep, retry possible (malloc == NULL) ERROR functionality error WARNING functionality successful NOTICE operation, statistics, start/stop --- border line production/testing --- INFO step-by-step TRACE I/O tracing --- border line end-user/developer DEBUG debugging messages =head1 CHANNEL TREE SPECIFICATION An B channel tree can be descriped by a textual specification according to the following Backus-Naur-Form (BNF): tree ::= stream stream ::= channel | channel "->" stream | channel "->" "{" streams "}" streams ::= stream | stream ";" streams channel ::= channel_level "/" channel_level ":" channel_cons | channel_level ":" channel_cons | channel_cons channel_level ::= IDENTIFIER | "(" channel_level_mask ")" channel_level_mask ::= IDENTIFIER | IDENTIFIER "|" channel_level_mask channel_cons ::= IDENTIFIER channel_params channel_params ::= EMPTY | "(" channel_param_list ")" channel_param_list ::= EMPTY | channel_param | channel_param "," channel_param_list channel_param ::= IDENTIFIER "=" PARAMETER An example of such a channel tree specification is: noop -> { debug: prefix(prefix="[%d-%m-%Y/%H:%M:%S] ") -> buffer(size=16384) -> file(path=foo.log, trunc=0); error: syslog(ident=foo, facility=user, remotehost=syslog.example.com, target=remote); panic: smtp(host=mail.example.com, rcpt=foo@@example.com); } =head1 FUNCTIONS The following functions are provided by the B API: =head1 AVAILABLE CHANNEL HANDLERS =head2 Syslog Output Channel Handler (l2_handler_syslog) The Syslog output channel handler C sends the incoming message either via syslog(3) to a local syslogd(8) or via BSD Syslog protocol to a remote Syslog service. It conforms to RFC 3164 (The BSD syslog Protocol; C. Lonvick; August 2001). It provides the following channel parameters: =over 4 =item B (optional, C) Sets the location of the target Syslog service. Possible values are C (the default) or C. If C is used, the parameters C has to be set, too. =item B (optional, C) Host name or IP address of the remote Syslog service. No default exists, user has to provide value. =item B (optional, C) Port number of the remote SMTP service. Default is C<514>. =item B (optional, C) The name of the local host, I any domain appended. =item B (optional, C) The Syslog facility used for all messages. It has to be one of the following: C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C. =item B (I, C) Arbitrary string identifying the program. There is no default, user has to provide value. =item B (optional, C) Boolean flag whether to add the Process ID (pid) to the B tag in messages. Default is C<0>. =back =head2 Pipe Output Channel Handler (l2_handler_pipe) The Pipe output channel handler C sends the incoming message to the standard input of a chosen command, passed to the l2 library as a parameter when calling l2_configure. Any command that operates on the standard input (c language descriptor stdin) can be used, but attention is advised due to the wide variety of commands and their particular exit behaviours. Attention! Commands that exit on their own and with a success return value will not be restarted, however those returning with non-zero exit codes will be restarted. B reopens closed pipe channels due to faulted command processes in this way. Should such a reconnection be required after a command's successful self-termination, l2_channel_open() may be called again on the same pipe channel pointer previously used. Stream logging will then write to the pipe channel handler, which will forward the log messages to the given command as always. To find out if a pipe channel has closed due to the behaviour of its command process, the l2_channel_write() operation may be called on it with a non-NULL message parameter, and 0 as the buffsize parameter. The return result will be L2_OK if the channel is open. Using the C language, such a check might look like: TODO NOTE FROM MICHAEL: This info will change once the pipe channel handler is redesigned to allow for proper process termination, signal handling of such processes, and subsequent channel closing!!!!!!!!!!! if (l2_channel_write(pPipechannel, L2_LEVEL_NOTICE, "", 0) != L2_OK) if (l2_channel_open(pPipechannel) != L2_OK) exit(1); /* failure */ The command passed to the pipe channel handler may also be stopped while still using a B stream log. If a command process is stopped no action is taken until further logging occurs. As soon as the pipe channel handler receives a message due to a l2_stream_log operation, it will attempt to restart the stopped command process and write to its standard input. If the effort to restart the command process fails then the command process is considered dead, and B will terminate the process and close the channel. A l2_channel_open() will then reopen the pipe channel using configuration information previously entered with l2_channel_configure(). It provides the following channel parameters: =over 4 =item B (optional, C) B will execute the command at this user-provided path, and pipe messages to its standard input when l2_stream_log operations are called. =back =head2 SMTP Output Channel Handler (l2_handler_smtp) The SMTP output channel handler C sends the incoming message via Simple Mail Transfer Protocol (SMTP) as an Email to a remote mail service. It conforms to RFC 2821 (Simple Mail Transfer Protocol; J. Klensin; April 2001) and RFC 2822 (Internet Message Format; P. Resnick; April 2001). It provides the following channel parameters: =over 4 =item B (optional, C) Arbitrary string identifying the program using B. Default is C which means no program identification. =item B (optional, C) Hostname of the underlying machine. Default is set through uname(3) or C. =item B (optional, C) Username corresponding to the UID of the underlying process. Default is set through resolving getuid(2) or C. =item B (optional, C) Sender Email address for outgoing mails. Default is set through B and B. =item B (I, C) Recipient Email address for outgoing mails. No default exists, user has to provide value. =item B (optional, C) Arbitrary string identifying the generated Email message. Default is C<[L2] log channel output on {localhost}>. =item B (I, C) Host name or IP address of the remote SMTP service. No default exists, user has to provide value. =item B (optional, C) Port name or number of the remote SMTP service. Default is C (25). =item B (optional, C) Timeout in seconds for all I/O operations. Default is C<30>. =back =cut @ 1.17 log @Adjust copyright messages for new year 2005. @ text @d3 3 a5 3 ## Copyright (c) 2001-2004 Cable & Wireless ## Copyright (c) 2001-2004 The OSSP Project ## Copyright (c) 2001-2004 Ralf S. Engelschall @ 1.16 log @correct spelling: privileges, convenient; @ text @d3 3 a5 3 ## Copyright (c) 2001-2003 Cable & Wireless Deutschland GmbH ## Copyright (c) 2001-2003 The OSSP Project (http://www.ossp.org/) ## Copyright (c) 2001-2003 Ralf S. Engelschall @ 1.15 log @introduce "trunc=" option for file channel; change default to append; keep support for obsolete "append" option @ text @d63 1 a63 1 into the framework. For convinience reasons, B already ships with @ 1.14 log @- remove trailing whitespaces - adjust copyright messages - consistently use "OSSP l2" - consistently talk about "Flexible Logging" - use standard OSSP ASCII-art @ text @d121 1 a121 1 -> file(path=foo.log, append=1); @ 1.14.2.1 log @correct spelling: privileges, convenient; @ text @d63 1 a63 1 into the framework. For convenience reasons, B already ships with @ 1.13 log @polish for release @ text @d2 4 a5 3 ## OSSP l2 - Logging Library ## Copyright (c) 2001-2002 The OSSP Project (http://www.ossp.org/) ## Copyright (c) 2001-2002 Cable & Wireless Deutschland (http://www.cw.com/de/) d7 1 a7 1 ## This file is part of OSSP L2, a flexible logging library which d27 1 a27 1 ## d35 1 a35 1 B - Logging Library d39 1 a39 1 L2 L2_VERSION_STR d47 1 a47 1 OSSP L2 is a C library providing a very flexible and sophisticated d63 1 a63 1 into the framework. For convinience reasons, L2 already ships with d70 1 a70 1 bindings or through the use of this L2 channel definition language. Applying d75 1 a75 1 always sufficient for an application using L2. d92 1 a92 1 An L2 channel tree can be descriped by a textual specification according d131 1 a131 1 The following functions are provided by the B API: d157 1 a157 1 =item B (optional, C) d162 1 a162 1 =item B (optional, C) d166 1 a166 1 =item B (optional, C) d174 1 a174 1 =item B (I, C) d179 1 a179 1 =item B (optional, C) d198 1 a198 1 restarted. L2 reopens closed pipe channels due to faulted command processes in d218 1 a218 1 using a L2 stream log. If a command process is stopped no action is taken d223 1 a223 1 dead, and L2 will terminate the process and close the channel. A d233 1 a233 1 L2 will execute the command at this user-provided path, and pipe messages to d252 1 a252 1 Arbitrary string identifying the program using B. d285 1 a285 1 =item B (optional, C) @ 1.12 log @bump copyright year @ text @d2 1 a2 1 ## L2 - OSSP Logging Library d7 1 a7 1 ## can be found at http://www.ossp.org/pkg/l2/. @ 1.11 log @rember a few things from the past team meetings @ text @d3 2 a4 2 ## Copyright (c) 2001 The OSSP Project (http://www.ossp.org/) ## Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/) @ 1.10 log @Birthday commit: Shorten grammar to the usual BNF notation and add an example. @ text @d76 13 @ 1.9 log @Added L2CDL grammar text (L2 Channel Definition Language.) Looks crappy. @ text @d76 1 a76 1 =head1 L2 CHANNEL DEFINITION EBNF GRAMMAR d78 2 a79 3 /* channel tree */ tree : stream ; d81 33 a113 45 /* stream of channels */ stream : channel | channel T_OP_ARROW stream | channel T_OP_ARROW '{' streams '}' ; /* list of sibling streams */ streams : stream | stream ';' streams ; /* channel */ channel : channel_level '/' channel_level ':' channel_cons | channel_level ':' channel_cons | channel_cons ; /* channel level */ channel_level : T_ID | '(' channel_level_mask ')' ; /* channel level mask */ channel_level_mask : T_ID | T_ID '|' channel_level_mask ; /* channel constructor */ channel_cons : T_ID channel_params ; /* channel parameters */ channel_params : /* empty */ | '(' channel_param_list ')' ; /* channel parameter list */ channel_param_list : /* empty */ | channel_param | channel_param ',' channel_param_list ; /* channel parameter */ channel_param : T_ID '=' T_PARAM ; @ 1.8 log @first cut for an L2 summary @ text @d67 61 @ 1.7 log @Debugging of channel's behavior logic when facing problematic children. @ text @d46 20 a65 1 The B library is... @ 1.6 log @document syslog channel @ text @d105 52 @ 1.5 log @provide documentation for SMTP channel @ text @d54 51 d107 1 a107 1 The SMTP output channel handler C sends the incoming @ 1.4 log @Fix more ossp.com references by replacing with the correct domain name ossp.org. @ text @d52 61 @ 1.3 log @Major overhaul and improvement of build environment. Especially we now added optional support for C++ building with --with-cxx. @ text @d7 1 a7 1 ## can be found at http://www.ossp.com/pkg/l2/. @ 1.2 log @get rid of old Str stuff @ text @d27 1 a27 1 ## l2.pod: Unix manual page d50 1 a50 1 The following functions are provided by the B API: @ 1.1 log @Initial revision @ text @d2 3 a4 2 ## Str - String Library ## Copyright (c) 1999-2000 Ralf S. Engelschall d6 2 a7 2 ## This file is part of Str, a string handling and manipulation ## library which can be found at http://www.engelschall.com/sw/str/. d26 2 a28 39 ## str.pod: Unix manual page ## # Parts of this manual page (the str_format description) is: # # Copyright (c) 1990, 1991, 1993 # The Regents of the University of California. All rights reserved. # # This code is derived from software contributed to Berkeley by # Chris Torek and the American National Standards Committee X3, # on Information Processing Systems. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # 1. Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # 3. All advertising materials mentioning features or use of this software # must display the following acknowledgement: # This product includes software developed by the University of # California, Berkeley and its contributors. # 4. Neither the name of the University nor the names of its contributors # may be used to endorse or promote products derived from this software # without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. d34 1 a34 1 B - String Library d38 1 a38 1 Str STR_VERSION_STR d42 1 a42 13 B, B, B, B, B, B, B, B, B, B, B, B, B. d46 1 a46 5 The B library is a generic string library written in ANSI C which provides functions for handling, matching, parsing, searching and formatting of C strings. So it can be considered as a superset of POSIX string(3), but its main intention is to provide a more convinient and compact API plus a more generalized functionality. a50 666 =over 4 =item str_size_t B(const char *I); This function determines the length of string I, i.e., the number of characters starting at I that precede the terminating C character. It returns C if I is C. =item char *B(char *I, const char *I, size_t I); This copies the characters in string I into the string I, but never more than I characters (if I is greater than C<0>). The two involved strings can overlap and the characters in I are always C-terminated. The string I has to be large enough to hold all characters to be copied. function returns C if I or I are C. Else it returns the pointer to the written C-terminating character in I. =item char *B(const char *I, str_size_t I); This returns a copy of the characters in string I, but never more than I characters if I is greater than C<0>. It returns C if I is C. The returned string has to be deallocated later with free(3). =item char *B(char *I, ...); This functions concatenates the characters of all string arguments into a new allocated string and returns this new string. If I is C the function returns C. Else it returns the pointer to the written final C-terminating character in I. The returned string later has to be deallicated with free(3). =item char *B(char *I, str_size_t I, str_size_t I, char *I, str_size_t I); This splices the string I into string I, i.e., the I characters at offset I in I are removed and at their location the string I is inserted (or just the first I characters of I if I is greater than C<0>). It returns C if I or I are C. Else the string I is returned. The function supports also the situation where I is a sub-string of I as long as the area I...I and I...I do not overlap. The caller always has to make sure that enough room exists in I. =item int B(const char *I, const char *I, str_size_t I, int I); This performs a lexicographical comparison of the two strings I and I (but never compares more than I characters of them) and returns one of three return values: a value lower than C<0> if I is lexicographically lower than I, a vlue of exactly C<0> if I and I are equal and a value greater than C<0> if I is lexicographically higher than I. Per default (I is C<0>) the comparison is case-sensitive, but if C is used for I the comparison is done in a case-insensitive way. =item char *B(const char *I, size_t I, const char *I, int I); This functions spans a string I according to the characters specified in I. If I is C<0>, this means that I is spanned from left to right starting at I (and ending either when reaching the terminating C character or already after I spanned characters) as long as the characters of I are contained in I. Alternatively one can use a I of C to indicate that I is spanned as long as the characters of I are I contained in I, i.e., I then specifies the complement of the spanning characters. In both cases one can additionally "or" (with the C operator ``C<|>'') C into I to indicate that the spanning is done right to left starting at the terminating C character of I (and ending either when reaching I or already after I spanned characters). =item char *B(const char *I, str_size_t I, const char *I); This functions searches for the (smaller) string I inside (larger) string I. If I is not C<0>, the search is performed only inside the first I characters of I. =item char *B(char **I, const char *I, const char *I, const char *I, int I); This function considers the string I to consist of a sequence of zero or more text tokens separated by spans of one or more characters from the separator string I. However, text between matched pairs of quotemarks (characters in I) is treated as plain text, never as delimiter (separator) text. Each call of this function returns a pointer to the first character of the first token of I. The token is C-terminated, i.e., the string I is processed in a destructive way. If there are quotation marks or escape sequences, the input string is rewritten with quoted sections and escape sequences properly interpreted. This function keeps track of its parsing position in the string between separate calls by simply adjusting the callers I pointer, so that subsequent calls with the same pointer variable I will start processing from the position immediately after the last returned token. In this way subsequent calls will work through the string I until no tokens remain. When no token remains in I, C is returned. The string of token separators (I) and the string of quote characters (I) may be changed from call to call. If a character in the string I is not quoted or escaped, and is in the I set, then it is overwritten with a C character and the rest of the string is ignored. The characters to be used as quote characters are specified in the I set, and must be used in balanced pairs. If there is more than one flavor of quote character, one kind of quote character may be used to quote another kind. If an unbalanced quote is found, the function silently act as if one had been placed at the end of the input string. The I and I strings must be disjoint, i.e., they have to share no characters. The I argument can be used to modify the processing of the string (default for I is C<0>): C forces I characters to be stripped from quoted tokens; C enables the interpretation (and expansion) of backslash escape sequences (`B<\x>') through ANSI-C rules; C forces that after the terminating C is written and the token returned, further delimiters are skipped (this allows one to make sure that the delimiters for one word don't become part of the next word if one change delimiters between calls); and C enables the recognition and expansion of ANSI C Trigraph sequences (as a side effect this enables C, too). =item int B(const char *I, const char *I, ...); This parses the string I according to the parsing operation specified by I. If the parsing operation succeeds, C is returned. Else C is returned. The I string usually has one of the following two syntax variants: `B I I I I*' (for matching operations) and `B I I I I I I*' (for substitution operations). For more details about the syntax variants and semantic of the I argument see section B below. The syntax of the I part in I is mostly equivalent to Perl 5's regular expression syntax. For the complete and gory details see perlre(1). A brief summary you can find under section B below. =item int B(char *I, str_size_t I, const char *I, ...); This formats a new string according to I and optionally following arguments and writes it into the string I, but never more than I characters at all. It returns the number of written characters. If I is C it just calculates the number of characters which would be written. The function generates the output string under the control of the I format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of stdarg(3)) are converted for output. The format string I is composed of zero or more directives: ordinary characters (not B<%>), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character B<%>. The arguments must correspond properly (after type promotion) with the conversion specifier. Which conversion specifications are supported are described in detail under B below. =item unsigned long B(const char *I, str_size_t I, int I); This function calculates a hash value of string I (or of its first I characters if I is equal to C<0>). The following hashing functions are supported and can be selected with I: STR_HASH_DJBX33 (Daniel J. Berstein, Times 33 Hash with Addition), STR_HASH_BJDDJ (Bob Jenkins, Dr. Dobbs Journal), and STR_HASH_MACRC32 (Mark Adler, Cyclic Redundancy Check with 32-Bit). This function is intended for fast use in hashing algorithms and I for use as cryptographically strong message digests. =item int B(char *I, str_size_t I, unsigned char *I, str_size_t I, int I); This function Base64 encodes I bytes starting at I and writes the resulting string into I (but never more than I characters are written). The I for this operation has to be C. Additionally one can OR the value C to enable strict encoding where after every 72th output character a newline character is inserted. The function returns the number of output characters written. If I is C the function just calculates the number of required output characters. Alternatively, if I is C the string I (or the first I characters only if I is not C<0>) is decoded and the output bytes written at I. Again, if I is C only the number of required output bytes are calculated. =back =head1 GORY DETAILS In this part of the documentation more complex topics are documented in detail. =head2 Perl Regular Expressions The regular expressions used in B are more or less Perl compatible (they are provided by a stripped down and built-in version of the I library). So the syntax description in perlre(1) applies and don't has to be repeated here again. For a deeper understanding and details you should have a look at the book `I' (see also the perlbook(1) manpage) by I. For convinience reasons we give you only a brief summary of Perl compatible regular expressions: The following metacharacters have their standard egrep(1) meanings: \ Quote the next metacharacter ^ Match the beginning of the line . Match any character (except newline) $ Match the end of the line (or before newline at the end) | Alternation () Grouping [] Character class The following standard quantifiers are recognized: * Match 0 or more times (greedy) *? Match 0 or more times (non greedy) + Match 1 or more times (greedy) +? Match 1 or more times (non greedy) ? Match 1 or 0 times (greedy) ?? Match 1 or 0 times (non greedy) {n} Match exactly n times (greedy) {n}? Match exactly n times (non greedy) {n,} Match at least n times (greedy) {n,}? Match at least n times (non greedy) {n,m} Match at least n but not more than m times (greedy) {n,m}? Match at least n but not more than m times (non greedy) The following backslash sequences are recognized: \t Tab (HT, TAB) \n Newline (LF, NL) \r Return (CR) \f Form feed (FF) \a Alarm (bell) (BEL) \e Escape (think troff) (ESC) \033 Octal char \x1B Hex char \c[ Control char \l Lowercase next char \u Uppercase next char \L Lowercase till \E \U Uppercase till \E \E End case modification \Q Quote (disable) pattern metacharacters till \E The following non zero-width assertions are recognized: \w Match a "word" character (alphanumeric plus "_") \W Match a non-word character \s Match a whitespace character \S Match a non-whitespace character \d Match a digit character \D Match a non-digit character The following zero-width assertions are recognized: \b Match a word boundary \B Match a non-(word boundary) \A Match only at beginning of string \Z Match only at end of string, or before newline at the end \z Match only at end of string \G Match only where previous m//g left off (works only with /g) The following regular expression extensions are recognized: (?#text) An embedded comment (?:pattern) This is for clustering, not capturing (simple) (?imsx-imsx:pattern) This is for clustering, not capturing (full) (?=pattern) A zero-width positive lookahead assertion (?!pattern) A zero-width negative lookahead assertion (?<=pattern) A zero-width positive lookbehind assertion (?pattern) An "independent" subexpression (?(cond)yes-re) Conditional expression (simple) (?(cond)yes-re|no-re) Conditional expression (full) (?imsx-imsx) One or more embedded pattern-match modifiers =head2 Parsing Specification The B(const char *I, const char *I, ...) function is a very flexible but complex one. The argument I is the string on which the parsing operation specified by argument I is applied. The parsing semantics are highly influenced by Perl's `B<=~>' matching operator, because one of the main goals of str_parse(3) is to allow one to rewrite typical Perl matching constructs into C. Now to the gory details. In general, the I argument of str_parse(3) has one of the following two syntax variants: =over 4 =item B `B I I I I*': This matches I against the Perl-style regular expression I under the control of zero or more I which control the parsing semantics. The stripped down I syntax `I' is equivalent to `BIB'. For each grouping pair of parenthesis in I, the text in I which was grouped by the parenthesis is extracted into new strings. These per default are allocated as seperate strings and returned to the caller through following `B' arguments. The caller is required to free(3) them later. =item B `B I I I I I I*': This matches I against the Perl-style regular expression I under the control of zero or more I which control the parsing semantics. As a result of the operation, a new string formed which consists of I but with the part which matched I replaced by I. The result string is returned to the caller through a `B' argument. The caller is required to free(3) this later. For each grouping pair of parenthesis in I, the text in I which was grouped by the parenthesis is extracted into new strings and can be referenced for expansion via `B<$n>' (n=1,..) in I. Additionally any str_format(3) style `B<%>' constructs in I are expanded through additional caller supplied arguments. =back The following I are supported: =over 4 =item B If the I flag `B' is specified, the extracted strings are bundled together into a single chunk of memory and its address is returned to the caller with a additional `B' argument which has to preceed the regular string arguments. The caller then has to free(3) only this chunk of memory in order to free all extracted strings at once. =item B If the case-I flag `B' is specified, I is matched in case-insensitive way. =item B If the I flag `B' is specified, this indicates to the B library that the whole I string is constant and that its internal pre-processing (it is compiled into a deterministic finite automaton (DFA) internally) has to be done only once (the B library then caches the DFA which corresponds to the I argument). =item B If the I flag `B' is specified, the I's legibility is extended by permitting embedded whitespace and comments to allow one to write down complex regular expressions more cleary and even in a documented way. =item B If the I lines flag `B' is specified, the string I is treated as multiple lines. That is, this changes the regular expression meta characters `B<^>' and `B<$>' from matching at only the very start or end of the string I to the start or end of any line anywhere within the string I. =item B If the I line flag `B' is specified, the string I is treated as single line. That is, this changes the regular expression meta character `B<.>' to match any character whatsoever, even a newline, which it normally would not match. =back =head1 CONVERSION SPECIFICATION In the format string of str_format(3) each conversion specification is introduced by the character B<%>. After the B<%>, the following appear in sequence: =over 4 =item o An optional field, consisting of a decimal digit string followed by a B<$>, specifying the next argument to access. If this field is not provided, the argument following the last argument accessed will be used. Arguments are numbered starting at B<1>. If unaccessed arguments in the format string are interspersed with ones that are accessed the results will be indeterminate. =item o Zero or more of the following flags: A B<#> character specifying that the value should be converted to an ``alternate form''. For B, B, B, B, B

, B, and B, conversions, this option has no effect. For B conversions, the precision of the number is increased to force the first character of the output string to a zero (except if a zero value is printed with an explicit precision of zero). For B and B conversions, a non-zero result has the string B<0x> (or B<0X> for B conversions) prepended to it. For B, B, B, B, and B, conversions, the result will always contain a decimal point, even if no digits follow it (normally, a decimal point appears in the results of those conversions only if a digit follows). For B and B conversions, trailing zeros are not removed from the result as they would otherwise be. A zero `B<0>' character specifying zero padding. For all conversions except B, the converted value is padded on the left with zeros rather than blanks. If a precision is given with a numeric conversion (B, B, B, B, B, B, and B), the `B<0>' flag is ignored. A negative field width flag `B<->' indicates the converted value is to be left adjusted on the field boundary. Except for B conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A `B<->' overrides a `B<0>' if both are given. A space, specifying that a blank should be left before a positive number produced by a signed conversion (B, B, B, B, B, B, or B). A `B<+>' character specifying that a sign always be placed before a number produced by a signed conversion. A `B<+>' overrides a space if both are used. =item o An optional decimal digit string specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out the field width. =item o An optional precision, in the form of a period `B<.>' followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for B, B, B, B, B, and B conversions, the number of digits to appear after the decimal-point for B, B, and B conversions, the maximum number of significant digits for B and B conversions, or the maximum number of characters to be printed from a string for B conversions. =item o The optional character B, specifying that a following B, B, B, B, B, or B conversion corresponds to a `C' or `C' argument, or that a following B conversion corresponds to a pointer to a `C argument. =item o The optional character B (ell) specifying that a following B, B, B, B, B, or B conversion applies to a pointer to a `C' or `C' argument, or that a following B conversion corresponds to a pointer to a `C argument. =item o The optional character B, specifying that a following B, B, B, B, B, or B conversion corresponds to a `C' or `C' argument, or that a following B conversion corresponds to a pointer to a `C' argument. =item o The character B specifying that a following B, B, B, B, or B conversion corresponds to a `C' argument. =item o A character that specifies the type of conversion to be applied. =back A field width or precision, or both, may be indicated by an asterisk `B<*>' or an asterisk followed by one or more decimal digits and a `B<$>' instead of a digit string. In this case, an `C' argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is treated as though it were missing. If a single format directive mixes positional (`B') and non-positional arguments, the results are undefined. The conversion specifiers and their meanings are: =over 4 =item B The `C' (or appropriate variant) argument is converted to signed decimal (B and B), unsigned octal (B), unsigned decimal (B), or unsigned hexadecimal (B and B) notation. The letters B are used for B conversions; the letters B are used for B conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. =item B The `C argument is converted to signed decimal, unsigned octal, or unsigned decimal, as if the format had been B, B, or B respectively. These conversion characters are deprecated, and will eventually disappear. =item B The `C' argument is rounded and converted in the style `[-]d.dddB+-dd' where there is one digit before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character appears. An B conversion uses the letter B (rather than B) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00. =item B The `C' argument is rounded and converted to decimal notation in the style `[-]ddd.ddd>' where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it. =item B The `C' argument is converted in style B or B (or B for B conversions). The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it is treated as 1. Style B is used if the exponent from its conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit. =item B The `C' argument is converted to an `C, and the resulting character is written. =item B The `C' argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating C character; if a precision is specified, no more than the number specified are written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating C character. =item B

The `C pointer argument is printed in hexadecimal (as if by `B<%#x>' or `C<%#lx>). =item B The number of characters written so far is stored into the integer indicated by the `C' (or variant) pointer argument. No argument is converted. =item B<%> A `B<%>' is written. No argument is converted. The complete conversion specification is `B<%%>. =back In no case does a non-existent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. =head1 EXAMPLES In the following a few snippets of selected use cases of B are presented: =over 4 =item B char *v1 = "foo bar quux"; char *v2 = "baz"; str_splice(v1, 3, 5, v2, 0): /* now we have v1 = "foobazquux" */ .... =item B char *var = " foo \t " bar 'baz'" q'uu'x #comment"; char *tok, *p; p = var; while ((tok = str_token(p, ":", "\"'", "#", 0)) != NULL) { /* here we enter three times: 1. tok = "foo" 2. tok = " bar 'baz'" 3. tok = "quux" */ ... } =item B char *var = "foo:bar"; if (str_parse(var, "^.+?:.+$/)) { /* var matched */ ... } =item B char *var = "foo:bar"; char *cp, *v1, *v2; if (str_parse(var, "m/^(.+?):(.+)$/b", &cp, &v1, &v2)) { ... /* now we have: cp = "foo\0bar\0" and v1 and v2 pointing into it, i.e., v1 = "foo", v2 = "bar" */ ... free(cp); } =item B char *var = "foo:bar"; char *subst = "quux"; char *new; str_parse(var, "s/^(.+?):(.+)$/$1-%s-$2/", &new, subst); ... /* now we have: var = "foo:bar", new = "foo:quux:bar" */ ... free(new); =item B char *v0 = "abc..."; /* length not guessable */ char *v1 = "foo"; void *v2 = 0xDEAD; int v3 = 42; char *cp; int n; n = str_format(NULL, 0, "%s|%5s-%x-%04d", v0, v1, v2, v3); cp = malloc(n); str_format(cp, n, "%s-%x-%04d", v1, v2, v3); /* now we have cp = "abc...| foo-DEAD-0042" */ ... free(cp); =back =head1 SEE ALSO string(3), printf(3), perlre(1). =head1 HISTORY The B library was written in November and December 1999 by Ralf S. Engelschall. As building blocks various existing code was used and recycled: for the str_token(3) implementation an anchient strtok(3) flavor from William Deich 1991 was cleaned up and adjusted. As the background parsing engine for str_parse(3) a heavily stripped down version of Philip Hazel's PCRE 2.08 library was used. The str_format(3) implementation was based on Panos Tsirigotis' sprintf(3) code as adjusted by the Apache Software Foundation 1998. The formatting engine was stripped down and enhanced to support internal extensions which were required by str_format(3) and str_parse(3). =head1 AUTHOR Ralf S. Engelschall rse@@engelschall.com www.engelschall.com @ 1.1.1.1 log @L2 initial source tree @ text @@