.\" 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 "Time 3pm"
.TH Time 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::Time \- parses and prints date in formats common to many log files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Lire::Time qw/ syslog2cal /;
\&
\&    my @ltime = localtime;
\&
\&    while ( <LOGFILE> ) {
\&        #...
\&        my $time = syslog2cal( $m, $d, $t, \e@ltime );
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module supplies many functions to parse dates in formats that you
are likely to encounter in log files. It also offers many functions to format
epoch time in useful format.
.SS "\s-1NOTE\s0 \s-1ABOUT\s0 \s-1FUNCTION\s0 \s-1EXPORT\s0"
.IX Subsection "NOTE ABOUT FUNCTION EXPORT"
Altough all documented functions are exported by default to the caller
namespace, you should explicitely import the functions you require
since exporting by default isn't recommanded by the perl modules
guidelines.
.SH "DATE PARSING FUNCTIONS"
.IX Header "DATE PARSING FUNCTIONS"
This module includes several functions that convert between a more
human readable date format and \s-1UNIX\s0 epoch time. All parsing functions
will return the number of seconds since Jan 1 1970 00:00:00 \s-1UTC\s0 and
will \fIdie()\fR when passed invalid arguments.
.SS "\fIdate2cal()\fP"
.IX Subsection "date2cal()"
.Vb 2
\&    my $time = date2cal( $year, $month, $day, $time, [$timezone] );
\&    my $time = date2cal( "2001 Mar 20 09:32:29 +0100" );
.Ve
.PP
This function will convert a date in the \fIdate\fR\|(1) default output format
to \s-1UNIX\s0 epoch time. The function accepts either the date in a string
or splitted on whitespace. If the timezone component is omitted, the
local timezone is assumed (usually based on the value of the \s-1TZ\s0
environment variable).
.SS "\fIsyslog2cal()\fP"
.IX Subsection "syslog2cal()"
.Vb 2
\&    my $time = syslog2cal( $month, $day, $time, $local_tm_ref );
\&    my $time = syslog2cal( "Mar 11 13:21:00", $local_tm_ref );
.Ve
.PP
This function will convert a date in the syslog default output format
to \s-1UNIX\s0 epoch time. The function accepts either the date in a string
or splitted on whitespace.
.PP
Since the syslog format doesn't contain timezone information, the
local timezone is assumed (usually determined by the \s-1TZ\s0 environment
variable).
.PP
The last argument is a reference to an array returned by \fIlocaltime()\fR.
.PP
.Vb 1
\&    my $local_tm_ref = [localtime()];
.Ve
.PP
It is used to determine the year.
.SS "\fIclf2cal()\fP"
.IX Subsection "clf2cal()"
.Vb 1
\&    my $time = clf2cal( "[18/Mar/2001:15:59:30 +0100]" );
.Ve
.PP
This function will convert a date as found in Common Log Format to
\&\s-1UNIX\s0 epoch time.
.SH "DATE FORMATING FUNCTIONS"
.IX Header "DATE FORMATING FUNCTIONS"
This module includes some functions to convert date in \s-1UNIX\s0 epoch time to
some more human readable output. All functions will \fIdie()\fR when passed
invalid arguments.
.SS "\fIcal2rfc()\fP"
.IX Subsection "cal2rfc()"
.Vb 1
\&    print cal2rfc( $time );
.Ve
.PP
This function will convert a date in \s-1UNIX\s0 epoch time to the \s-1RFC822\s0 format
(used in email, for example). A \s-1RFC822\s0 date looks like
.PP
.Vb 1
\&    Wed, 30 May 2001 12:45:13 +0000
.Ve
.PP
The timezone offset specification will correspond to the local
timezone (usually determined by the \s-1TZ\s0 environment variable).
.SS "\fIcal2ymdhms()\fP"
.IX Subsection "cal2ymdhms()"
.Vb 1
\&    print cal2ymdhms( $time );
.Ve
.PP
This function converts a date in \s-1UNIX\s0 epoch time to a string of the form:
.PP
.Vb 1
\&    YYYYMMDDHHMMSS
.Ve
.PP
This representation will correspond the time in the local timezone (usually determined by the \s-1TZ\s0 environment variable.)
.SS "\fIgetMonthName()\fP"
.IX Subsection "getMonthName()"
.Vb 1
\&    print getMonthName( 0 ); # Gives \*(AqJan\*(Aq
.Ve
.PP
This function takes as parameter a number (0\-11) representing the
month (as returned by \fIlocaltime()\fR for example) and will return the
English abbreviated name of that month ( Jan, Feb, etc. ).
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  Joost van Baal <joostvb@logreport.org>
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Time.pm,v 1.10 2006/07/23 13:16:30 vanbaal Exp $
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2000\-2002 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.