Program(3)

NAME
Lire::Program - Lire's programs common infrastructure and DLF converter API.

SYNOPSIS
Any program:

    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: ", $! );
DLF converters:

    use Lire::Program qw/ :dlf /;
    init_dlf_converter( "email" );
    while ( <> ) {
        lire_chomp(); # Optional
        # Convert logfile to DLF
    }
    end_dlf_converter( $lines, $dlflines, $errorlines );

DESCRIPTION
This module should be used by all Lire programs (at least the perl ones :-).

It includes:

1.  Common behavior for good integration in the Lire suite. (Output of performance information and other stuff).

2.  Functions for portability.

3.  Logging functions

4.  The perl DLF converter API.

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 BEGIN and END blocks to comply with Lire's policy.

1.  Only message in the proper logging format

        I<superservice> I<service> I<lr_id> I<program> I<level> I<msg>
    should be output. This module will install a __WARN__ signal handler that make sure that all module that use warn to output message are rewritten in the proper format.

2.  All programs should start by a "info" message which logs their arguments. This module takes care of this.

3.  All programs should end by printing "info" 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 of the common information):

        memory stats: vsize=10688K rss=9380K majflt=406
        elapsed time in seconds real=9 user=8.72 system=0.06
        stopped
    The memory profiling information will only be output on platform running the Linux kernel.

  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.)

$PROG
    The name of your program (that's the value of $0 without the directory path).

$LR_SUPERSERVICE
    The superservice which you are processing, or "all" if this information isn't available.

$LR_SERVICE
    The service which you are processing, or "all" if this information isn't specified.

$LR_ID
    That's the job identifier. It should be shared by all commands in a Lire job. This is the value UNSET when none was specified.

$LR_TAG
    That's the prefix to all log messages. Should correspond to

        $LR_SUPERSERVICE $LR_SERVICE $LR_ID $PROG

PORTABILITY FUNCTIONS
For portability across perl versions, the Lire::Program interface offers some functions that are usually found in the latest version of perl but that may not be present in some old ones (the oldest version of perl we support is 5.00503).

To use these functions, you need to import them explicitely or use the full name (with the namespace).

  tempfile()
    my $fh = tempfile();
    my $fh = tempfile( $template, [ SUFFIX => ".txt" ] )
    my ($fh, $name ) = tempfile( $template, [ SUFFIX => ".dlf" ] );
This is a wrapper around the File::Temp::tempfile perl function when available, and it offers a home grown version which should be safe when itsn't available. The only difference is that the file will always be created in the directory specified in $ENV{TMPDIR} or /tmp when unset.

The first argument to the function should be a template name containing at least 6 X (i.e. tempXXXXXX) which we replaced to generate a random name. When no arguments are passed, a default template of tempfileXXXXXX will be use.

Other options can be passed to the function by using key => value pair. The only option understood by the home grown version is SUFFIX which will be appended to the filename. (The perl version understands more options, but you shouldn't use them for compatibility.)

The function takes precautions against symlink attacks (and create the file with readwrite permission for the owner only). It will die(), if it fails to create a temporary file after 10 attempts. (This shouldn't happen unless someone is seriously trying to race with us.)

The function will return in scalar context a anonymous file handle opened on the temporary file. The temporary file was unlinked after creation and will thus be deleted automatically when you close the file handle.

When used in an array context, the function will return a file handle and the path to the temporary file (this can be useful for debugging purpose or when you can't passed the file by file handle to another process). In this case, the file should be deleted manually.

  tempdir()
    my $dir = tempdir();
    my $dir = tempdir( $template )
This is a wrapper around the File::Temp::tempdir perl function when available, and it offers a home grown version which should be safe when itsn't available. The only difference is that the directory will always be created in the directory specified in $ENV{TMPDIR} or /tmp when unset.

The first argument to the function should be a template name containing at least 6 X (i.e. tempXXXXXX) which we replaced to generate a random name. When no arguments are passed, a default template of tempdirXXXXXX will be use.

Other options can be passed to the function by using key => value pair. The only option understood by the home grown version is DIR which is specify wehre the directory will be created (The perl version understands more options, but you shouldn't use them for compatibility.)

The function takes precautions against symlink attacks (and create the file with readwrite permission for the owner only). It will die(), if it fails to create a temporary directory after 10 attempts. (This shouldn't happen unless someone is seriously trying to race with us.)

The function will return the name of the directory that was created.

LOGGING FUNCTIONS
Programs that need to log messages to the user should import the logging functions using the :msg tag. Using the proper lr_level() function will make sure that messages are output in the proper format.

All logging functions take any number of parameters that will be joined together to form the message (like print(), die(), warn() and friends).

  lr_emerg()
This logs a message at the "emerg" level and aborts your program. This probably shouldn't be used.

  lr_crit()
This logs a message at the "crit" level and aborts your program. This should only be used when something is really broken in the Lire program or the environment. It is used a few places in Lire when assertion that should really never fail (like a DLF file with the wrong number of fields).

  lr_err()
This logs a message at the "err" level and usually aborts your program. (It is the equivalent of a die().) The program won't abort if it's used in an eval block. Uses this for error condition.

  lr_warn()
This logs a message at the "warning" level. Perl's builtin warn is mapped to this function. Use this for non-fatal errors.

  lr_notice()
This logs a message at the "notice" level. This should be used for significant informational messages that the user should see. (By default, the user will only see messages at level "notice" or higher.)

  lr_info()
This logs a message at the "info" level. Use this for general informational messages.

  lr_debug()
This logs a message at the "debug" level. Use this for debugging messages.

DLF CONVERTERS FUNCTION
All DLF converters should import the DLF converters API by using the :dlf import tag. Consult also the Lire::DlfSchema(3pm) man page for other important information.

  init_dlf_converter()
    init_dlf_converter( $superservice );
This should be called by the DLF converter after its initialization and before starting to output DLF records. The only parameter is the name of the superservice for which this converter is outputting DLF records.

  end_dlf_converter()
    end_dlf_converter( $lines, $dlflines, $errorlines );
This should be called at the end of your program (when it has finished converting the log). This function logs the conversion statistics in the standard format and will store in the Lire database the appropriate information associated to the current job.

The parameters are:

$lines
    The number of log lines read.

$dlflines
    The number of DLF record output.

$errorlines
    The number of errors encountered.

  lire_chomp( [$line])
DLF converters should use that function instead of the chomp builtin. This function will remove UNIX or DOS line ending whereas the native chomp will only remove the native end-of-line marker. Since Lire process log files that weren't necessarly produce on the same platform, this function is more tailored to Lire.

The lire_chomp() will remove the end-of-line marker fromt the $line parameter or from $_ if that parameter is omitted.

SEE ALSO
Lire::DlfSchema(3pm)

VERSION
$Id: Program.pm,v 1.18 2002/07/09 15:26:05 flacoste Exp $

COPYRIGHT
Copyright (C) 2001 Stichting LogReport Foundation LogReport@LogReport.org

This file is part of Lire.

Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html or write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.

AUTHOR
Francis J. Lacoste <flacoste@logreport.org>