.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "Mirmon 3"
.TH Mirmon 3 "2016-07-23" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Mirmon \- OO interface for mirmon objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mirmon ;
.Ve
.PP
.Vb 1
\&  $m = Mirmon -> new ( [ $path-to-config ] )
.Ve
.PP
.Vb 2
\&  $conf  = $m -> conf  ; # a Mirmon::Conf object
\&  $state = $m -> state ; # the mirmon state
.Ve
.PP
.Vb 5
\&  for my $url ( keys %$state )
\&    { $mirror = $state -> { $url } ; # a Mirmon::Mirror object
\&      $mail = $mirror -> mail ;      # contact address
\&      $mirror -> age ( time ) ;      # set mirror age
\&    }
.Ve
.PP
Many class and object methods can be used to get or set attributes :
.PP
.Vb 2
\&  $object -> attribute           # get an atttibute
\&  $object -> attribute ( $attr ) # set an atttibute
.Ve
.SH "Mirmon class methods"
.IX Header "Mirmon class methods"
.IP "\fBnew ( [$path] )\fR" 4
.IX Item "new ( [$path] )"
Create a Mirmon object from a config file found in \f(CW$path\fR,
or (by default) in the default list of possible config files.
Related objects (config, state) are created and initialised.
.IP "verbosity" 4
.IX Item "verbosity"
Mirmon always reports errors. Normally it only reports
changes (inserts/deletes) found in the mirror_list ;
in \fIquiet\fR mode, it doesn't. In \fIverbose\fR mode, it
reports progress: the startup and finishing of probes.
.Sp
.Vb 3
\&  Mirmon::verbose ( [ $bool ] ) # get/set verbose
\&  Mirmon::quiet   ( [ $bool ] ) # get/set quiet
\&  Mirmon::debug   ( [ $bool ] ) # get/set debug
.Ve
.SH "Mirmon object methods"
.IX Header "Mirmon object methods"
.IP "\fBconf\fR" 4
.IX Item "conf"
Returns Mirmon's Mirmon::Conf object.
.IP "\fBstate\fR" 4
.IX Item "state"
Returns a hashref \f(CW\*(C`{ url => mirror, ... }\*(C'\fR,
where \fIurl\fR is as specified in the mirror list
and \fImirror\fR is a Mirmon::Mirror object.
.IP "\fBregions\fR" 4
.IX Item "regions"
Returns a hashref \f(CW\*(C`{ country_code => country_name, ... }\*(C'\fR.
.IP "\fBconfig_list\fR" 4
.IX Item "config_list"
Returns the list of default locations for config files.
.ie n .IP "\fBget_dates ( \fB$get\fB [, \f(BI$URL\fB] )\fR" 4
.el .IP "\fBget_dates ( \f(CB$get\fB [, \f(CB$URL\fB] )\fR" 4
.IX Item "get_dates ( $get [, $URL] )"
Probes all mirrors if \f(CW$get\fR is \f(CW\*(C`all\*(C'\fR ; or a subset if \f(CW$get\fR is \f(CW\*(C`update\*(C'\fR ;
or only \fI$URL\fR if \f(CW$get\fR is \f(CW\*(C`url\*(C'\fR.
.SH "Mirmon::Conf object methods"
.IX Header "Mirmon::Conf object methods"
A Mirmon::Conf object represents a mirmon conguration.
It is normaly created by \fIMirmon::new()\fR.
A specified (or default) config file is read and interpreted.
.IP "attribute methods" 4
.IX Item "attribute methods"
For every config file entry, there is an attribute method :
\&\fBweb_page\fR, \fBstate\fR, \fBcountries\fR, \fBmirror_list\fR, \fBprobe\fR,
\&\fBproject_name\fR, \fBproject_url\fR, \fBicons\fR, \fBproject_logo\fR,
\&\fBtimeout\fR, \fBmax_probes\fR, \fBmin_poll\fR, \fBmax_poll\fR, \fBmin_sync\fR,
\&\fBmax_sync\fR, \fBlist_style\fR, \fBput_histo\fR, \fBrandomize\fR, \fBadd_slash\fR.
.IP "\fBroot\fR" 4
.IX Item "root"
Returns the file name of (the root of) the configuration file(s).
.IP "\fBsite_url\fR" 4
.IX Item "site_url"
Returns a hashref \f(CW\*(C`{ site => url, ... }\*(C'\fR,
as specified in the mirmon config file.
.SH "Mirmon::Mirror object methods"
.IX Header "Mirmon::Mirror object methods"
A Mirmon::Mirror object represents the last known state of a mirror.
It is normaly created by \fIMirmon::new()\fR from the state file,
as specified in the mirmon config file.
Mirmon::Mirror objects can be used to probe mirrors.
.Sh "attribute methods"
.IX Subsection "attribute methods"
.IP "\fBurl\fR" 4
.IX Item "url"
The url as given in the mirror list.
.IP "\fBage\fR" 4
.IX Item "age"
The mirror's timestamp found by the last successful probe,
or 'undef' if no probe was ever successful.
.IP "\fBlast_status\fR" 4
.IX Item "last_status"
The status of the last probe, or 'undef' if the mirror was never probed.
.IP "\fBlast_ok_probe\fR" 4
.IX Item "last_ok_probe"
The timestamp of the last successful probe or 'undef'
if the mirror was never successfully probed.
.IP "\fBprobe_history\fR" 4
.IX Item "probe_history"
The probe history is a list of 's' (for success) and 'f' (for failure)
characters indicating the result of the probe. New results are appended
whenever the mirror is probed.
.IP "\fBstate_history\fR" 4
.IX Item "state_history"
The state history consists of a timestamp, a '\-' char, and a list of
chars indicating a past status: 's' (fresh), 'b' (oldish), 'f' (old),
\&'z' (bad) or 'x' (skip).
The timestamp indicates when the state history was last updated.
The current status of the mirror is determined by the mirror's age and
a few configuration parameters (min_sync, max_sync, max_poll).
The state history is updated when the mirror is probed.
If the last update of the history was less than 24 hours ago,
the last status is replaced by the current status.
If the last update of the history was more than 24 hours ago,
the current status is appended to the history.
One or more 'skip's are inserted, if the timestamp is two or more days old
(when mirmon hasn't run for more than two days).
.IP "\fBlast_probe\fR" 4
.IX Item "last_probe"
The timestamp of the last probe, or 'undef' if the mirror was never probed.
.Sh "object methods"
.IX Subsection "object methods"
.IP "\fBmirmon\fR" 4
.IX Item "mirmon"
Returns the parent Mirmon object.
.IP "\fBstate_history_time\fR" 4
.IX Item "state_history_time"
Returns the \fItime\fR part of the state_history attribute.
.IP "\fBstate_history_hist\fR" 4
.IX Item "state_history_hist"
Returns the \fIhistory\fR part of the state_history attribute.
.IP "\fBtype\fR, \fBsite\fR, \fBhome\fR" 4
.IX Item "type, site, home"
For an url like \fIftp://www.some.org/path/to/home\fR,
the \fBtype\fR is \fIftp\fR,
the \fBsite\fR is \fIwww.some.org\fR,
and \fBhome\fR is \fIftp://www.some.org/\fR.
.IP "\fBage_in_days\fR" 4
.IX Item "age_in_days"
Returns the mirror's age (in fractional days), based on the mirror's
timestamp as found by the last successful probe ; or based on the
length of the state history if no probe was ever successful.
Returns 'undef' if the mirror was never probed.
.IP "\fBmail\fR" 4
.IX Item "mail"
Returns the mirror's contact address as specified in the mirror list.
.IP "\fBregion\fR" 4
.IX Item "region"
Returns the mirror's country code as specified in the mirror list.
.IP "\fBstart_probe\fR" 4
.IX Item "start_probe"
Start a probe for the mirror in non-blocking mode ;
returns the associated (IO::Handle) file handle.
The caller must maintain an association between
the handles and the mirror objects.
.ie n .IP "\fBfinish_probe ( \fB$handle\fB )\fR" 4
.el .IP "\fBfinish_probe ( \f(CB$handle\fB )\fR" 4
.IX Item "finish_probe ( $handle )"
Sets the (IO::Handle) \fB$handle\fR to blocking \s-1IO\s0 ;
reads a result from the handle,
and updates the state of the mirror.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
mirmon(1)

.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 4
\&  (c) 2003-2016 Henk P. Penning
\&  Faculty of Science, Utrecht University
\&  http://www.staff.science.uu.nl/~penni101/ -- penning@uu.nl
\&  mirmon-2.11 - Sat Jul 23 09:12:31 2016 ; henkp
.Ve