MATILDA(1)               Chris Lightfoot               MATILDA(1)



NAME
       matilda  -  run  a  program, but swallow all of its output
       unless every invocation of the program during a  specified
       interval has failed

HUH?
           For every time She shouted `Fire!'
           They only answered `Little Liar'!
           And therefore when her Aunt returned,
           Matilda, and the House, were Burned.

       from  'Matilda,  Who  Told Lies, And Was Burned to Death',
       from Hillaire Belloc's Cautionary Tales

SYNOPSIS
       matilda interval program [argument ...]

DESCRIPTION
       Often one runs programs from cron(8) which fail from  time
       to  time,  but  constant emails full of error messages are
       boring. It's tempting to run them with  all  their  output
       redirected  to /dev/null, but that means that you'll never
       discover when problems develop.  Programs  which  interact
       with flakey web pages (for instance screen scrapers) are a
       particular problem in this regard.

       Matilda runs the program specified  on  its  command  line
       (with  any  specified  arguments),  and records whether it
       succeeded (exited with code 0) or failed in a database. If
       it  failed and this is the first time it has been run, or,
       the database records that no invocation of program through
       matilda  has  succeeded in the interval preceding the cur-
       rent time, then any output from  program  (including  any-
       thing it wrote to its standard error) is copied by matilda
       to its own standard output. In all other cases,  any  such
       output is consumed silently.

       As  a  special-case  kludge, matilda attempts to determine
       when either of standard output or standard error are  con-
       nected  to  /dev/null.  In  this case, it does not capture
       output sent to that descriptor.

       An interval must be specified as a whole number optionally
       followed  by  a  unit  which  may be `seconds', `minutes',
       `hours', `days', `weeks', or any unambiguous abbreviation.
       If no unit is specified, then `days' is assumed.

       Matilda's  database  is  by  default  stored  in  the file
       ~/.matildadb, but this may be overridden by a value in the
       environment variable MATILDA_DB.  In determining whether a
       program being invoked is the same as a previous invocation
       of  a  program,  the  program,  arguments, current working
       directory, user ID and group ID are taken into account.

EXIT CODE
       Whatever the executed program exits with,  or  99  in  the
       case that matilda itself fails.

EXAMPLES
       In the format of crontab(5):

       0 0 * * * matilda '1 week' backup
       Run `backup' every day at midnight, and swallow its output
       unless it's failed for the whole preceeding week.

       * * * * * matilda '5 minutes' ping -c 4 host
       Ping `host' every minute, and swallow  its  output  unless
       the host has been down for five minutes or more.

       * * * * * matilda '5 minutes' ping -c 4 host > /dev/null
       The same, but report only ping's standard error output.

       0 0 * * * matilda '1 week' /bin/sh -c 'prog1 > file && prog2'
       An  example  where  the program to be run itself needs its
       output redirected. In this case any standard error  output
       from  `prog1'  or  any  output at all from `prog2' will be
       reported if both have failed every day for  a  week.  Note
       the use of the -c option to /bin/sh.

       0 * * * * matilda '1 day' wget -qO index.new http://www.example.com/ \
                             && mv index.new index.html || rm -f index.new
       Attempt  to retrieve and atomically replace some file from
       a remote web site.  Complain only when it has failed for a
       whole day.

ENVIRONMENT
       MATILDA_DB

FILES
       ~/.matildadb

SEE ALSO
       cron(8), crontab(5), sh(1).

COPYRIGHT
       Copyright (C) 2004 Chris Lightfoot



                            June 2004                  MATILDA(1)