SYNOPSIS

       multilog script

DESCRIPTION

       script consists of any number of arguments. Each argument specifies one
       action.  The  actions  are carried out in order for each line of input.
       Note that actions may contain shell  metacharacters  that  need  to  be
       quoted when multilog is run from a shell.

       multilog  exits 0 when it sees the end of stdin. If stdin has a partial
       final line then multilog inserts a final newline.

       multilog writes a message to stderr and exits 111, without reading  any
       input, if it runs out of memory or if another multilog process is writ-
       ing to one of the same automatically rotated logs.

       If multilog has trouble writing to disk after it starts reading  input,
       it  writes a message to stderr, pauses, and tries again, without losing
       any data. Note that this may block any program feeding input to  multi-
       log.

       If multilog receives a TERM signal, it will read and process data until
       the next newline, and then exit, leaving stdin at  the  first  byte  of
       data it has not processed.

SELECTING LINES

       Each line is initially selected. The action

       -pattern
              deselects the line if pattern matches the line. The action

       +pattern
              selects the line if pattern matches the line.

       pattern  is  a string of stars and non-stars. It matches any concatena-
       tion of strings matched by all the stars  and  non-stars  in  the  same
       order.  A  non-star  matches  itself.  A star before the end of pattern
       matches any string that does not include the next character in pattern.
       A star at the end of pattern matches any string.

       For example, the action

              +hello

       selects hello. It does not select hello world.

       The action

              -named[*]: Cleaned cache *

       deselects named[135]: Cleaned cache of 3121 RRs. The first star matches
       e      prints (the first 200 bytes of) each selected line to stderr.

STATUS FILES

       The action

       =file  replaces  the  contents  of  file with (the first 1000 bytes of)
              each selected line, padded with newlines to 1001 bytes. There is
              no protection of file against power outages.

       For example, the sequence of actions

            -*
            +STAT*
            =log/status

       maintains  log/status  as  a copy of the most recent line starting with
       STAT.

TIMESTAMPING

       The action

       t      inserts an @, a precise timestamp, and a space in front of  each
              line,  using  the same format as tai64n(8).  This is required to
              be the first action.

       Patterns apply to the line after the timestamp is inserted.  For  exam-
       ple, if

            multilog t '-*' '+* fatal: *' ./main

       reads the line

            fatal: out of memory

       then it will log a line such as

            @400000003b4a39c23294b13c fatal: out of memory

       with the first * matching the timestamp.

       You  can  use tai64nlocal(8) to convert these timestamps to human-read-
       able form.

AUTOMATICALLY ROTATED LOGS

       If dir starts with a dot or slash then the action

       dir    appends each selected line to a log named dir.  If dir does  not
              exist, multilog creates it.

       The  log format is as follows.  dir is a directory containing some num-
       ber of old log files, a log file named current,  and  other  files  for
       multilog  to  keep  track  of its actions. Each old log file has a name
       644 and continues writing new lines.

       When multilog decides that current is big  enough,  it  writes  current
       safely to disk, sets the mode of current to 744, and renames current as
       an old log file. The action

       ssize  sets the maximum file size for subsequent dir actions.  multilog
              will  decide  that  current  is  big  enough if current has size
              bytes.  (multilog will also decide that current is big enough if
              it sees a newline within 2000 bytes of the maximum file size; it
              tries to finish log files at line  boundaries.)   size  must  be
              between  4096  and  16777215.  The  default maximum file size is
              99999.

              In versions 0.75 and above: If multilog receives an ALRM signal,
              it immediately decides that current is big enough, if current is
              nonempty.  The action

       nnum   sets the number of log files for subsequent dir  actions.  After
              renaming current, if multilog sees num or more old log files, it
              removes the old log file with the smallest timestamp.  num  must
              be at least 2. The default number of log files is 10. The action

       !processor
              sets a processor for subsequent dir actions.  multilog will feed
              current through processor and save the output as an old log file
              instead of current.  multilog will also  save  any  output  that
              processor  writes to descriptor 5, and make that output readable
              on descriptor 4 when it runs processor on the next log file. For
              reliability,  processor  must exit nonzero if it has any trouble
              creating its output; multilog will then run it again. Note  that
              running  processor may block any program feeding input to multi-
              log.

SEE ALSO

       supervise(8), svc(8),  svok(8),  svstat(8),  svscanboot(8),  svscan(8),
       readproctitle(8),  fghack(8),  pgrphack(8),  tai64n(8), tai64nlocal(8),
       setuidgid(8), envuidgid(8), envdir(8), softlimit(8), setlock(8)

       http://cr.yp.to/daemontools.html



                                                                   multilog(8)