.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Program 3pm"
.TH Program 3pm "2006-07-23" "Lire 2.1.1" "LogReport's Lire Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Lire::Program \- Lire's programs common infrastructure.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Any program:
.PP
.Vb 1
\&    use Lire::Program qw/ :msg /;
\&
\&    lr_info( "doing stuff " );
\&    lr_debug( "debugging information" );
\&    lr_warn( "encountered unexpected value: ", $value );
\&    open( CFGFILE, "my.conf" ) or lr_err( "open error: ", $! );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module should be used by all Lire programs (at least the Perl ones :\-).
.PP
It includes:
.IP "1." 4
Common behavior for good integration in the Lire suite. (Output of
performance information and other stuff).
.IP "2." 4
Functions for portability.
.IP "3." 4
Logging functions
.SH "COMMON BEHAVIOR FOR LIRE PROGRAMS"
.IX Header "COMMON BEHAVIOR FOR LIRE PROGRAMS"
When you use the Lire::Program module, you make sure that your program
will behave correctly in the Lire tool chain. This module will install
\&\s-1BEGIN\s0 and \s-1END\s0 blocks to comply with Lire's policy.
.IP "1." 4
Only messages in the proper logging format
.Sp
.Vb 1
\&    I<superservice> I<service> I<lr_id> I<program> I<level> I<msg>
.Ve
.Sp
should be output. This module will install a _\|_WARN_\|_ signal
handler that makes sure that all modules that use warn to output messages
are rewritten in the proper format.
.Sp
See also \fIlr_run\fR\|(1).
.IP "2." 4
All programs should start by a \f(CW\*(C`info\*(C'\fR message which logs their
arguments. This module takes care of this.
.IP "3." 4
All programs should end by printing \f(CW\*(C`info\*(C'\fR messages with performance
statistics and the message 'ended'. Using this module takes care of
this. At the end of your program the following will be output
(stripped off the common information):
.Sp
.Vb 3
\&    memory stats: vsize=10688K rss=9380K majflt=406
\&    elapsed time in seconds real=9 user=8.72 system=0.06
\&    stopped
.Ve
.Sp
The memory profiling information will only be output on platforms
running the Linux kernel.
.SS "\s-1COMMON\s0 \s-1VARIABLES\s0"
.IX Subsection "COMMON VARIABLES"
As a convenience, you can import in your namespace using the :env tag
some variables common to all Lire programs. (Note that you can also
use those variables without importing them by prefixing the variables
with the Lire::Program:: namespace.)
.ie n .IP "$PROG" 4
.el .IP "\f(CW$PROG\fR" 4
.IX Item "$PROG"
The name of your program (that's the value of \f(CW$0\fR without the directory path).
.ie n .IP "$LR_SUPERSERVICE" 4
.el .IP "\f(CW$LR_SUPERSERVICE\fR" 4
.IX Item "$LR_SUPERSERVICE"
The superservice which you are processing, or \f(CW\*(C`all\*(C'\fR if this
information isn't available.
.ie n .IP "$LR_SERVICE" 4
.el .IP "\f(CW$LR_SERVICE\fR" 4
.IX Item "$LR_SERVICE"
The service which you are processing, or \f(CW\*(C`all\*(C'\fR if this information
isn't specified.
.ie n .IP "$LR_ID" 4
.el .IP "\f(CW$LR_ID\fR" 4
.IX Item "$LR_ID"
That's the job identifier. It should be shared by all commands in a
Lire job. This is the value \s-1UNSET\s0 when none was specified.
.ie n .IP "$LR_TAG" 4
.el .IP "\f(CW$LR_TAG\fR" 4
.IX Item "$LR_TAG"
That's the prefix to all log messages. Should correspond to
.Sp
.Vb 1
\&    $LR_SUPERSERVICE $LR_SERVICE $LR_ID $PROG
.Ve
.SH "LOGGING FUNCTIONS"
.IX Header "LOGGING FUNCTIONS"
The logging functions are now part of the Lire::Logger module. Consult
\&\fILire::Logger\fR\|(3pm) for more information. The old names are still
exported from this module by using the ':msg' tag.
.SH "DLF CONVERTERS FUNCTIONS"
.IX Header "DLF CONVERTERS FUNCTIONS"
The \s-1DLF\s0 converter \s-1API\s0 is now defined in \fILire::DlfConverter\fR\|(3pm). The
\&\fILire::OldDlfAdapter\fR\|(3pm) can be used to work with old-style \s-1DLF\s0
Converters.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fILire::DlfSchema\fR\|(3pm), \fIlr_run\fR\|(1)
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  Francis J. Lacoste <flacoste@logreport.org>
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Program.pm,v 1.35 2006/07/23 13:16:29 vanbaal Exp $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2001 Stichting LogReport Foundation LogReport@LogReport.org
.PP
This file is part of Lire.
.PP
Lire is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0.  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program (see \s-1COPYING\s0); if not, check with
http://www.gnu.org/copyleft/gpl.html.