NAME

log_input - run a command, collecting all stdout & stderr to file

DESCRIPTION

Take a command line, run this command as a child process, collection all output into a specified logfile, with timestamps.

When a signal is received, it will be logged. If the signal is a SIGCONT, the logger will check to see how many children are still alive, and log that count. If the signal is a SIGHUP or SIGTERM, the child process will be killed, before log_input itself exits (with whatever exit code the child exited with).

For each line of output received from the child, the log file is checked to see if it would exceed 1Gb. If it would, then the log file is closed, renamed to include a timestamp (of the time of closure), and a new log file with the original name is opened.

exit_status

ARGUMENTS

*

If provided, set the exit status to this.

RETURNS

• The exit status of the logged process, or undef if it has not yet finished.

log_file

ARGUMENTS

*

If provided, set the log file (handle) to this.

RETURNS

• The file handle of the log file.

log_file_name

ARGUMENTS

*

If provided, set the log file (name) to this.

RETURNS

• The file name of the log file.

SYNOPSIS

log_input [options] <logfile> <command>

option:          Value     Default   Unit   Meaning
-h|--nohup       boolean   false            Ignore SIGHUP in child
-m|--maxsize     int       1Gb              Maximum log size in bytes
-A|--noarchive   boolean   false            Don't archive old logs
--preserve-lines int       128              Keep n lines if not archiving(-A)
--help                                      Produce summary help on stdout
--longhelp                                  Produce long help on stdout
--man                                       Produce full man page on stdout

logfile is a single shell word. command may be multiple shell words.

OPTIONS

Options come in short (single-character) and/or long forms. Short options are preceded by a single dash (-x), whilst long options are preceded by a double-dash (--option). Long options may be abbreviated to the minimal distinct prefix. Single char options may be bundled (-v -a -x == -vax), values may be interspersed (-v 1 -a 2 -x 3 == -v1a2x3). Options taking string values will assume that anything immediately following is a string value, even if the string is optional and/or the "value" could be interpreted as another option (if -v takes a string, -vax will give the value "ax" to the option -v). Options which are boolean must use the long form to negate, prefixed by "no_" (--foo may be negated by --no_foo).

log_input will only see options presented prior to the specification of the logfile. Logfiles with names beginning with '-' are not usable. Any options presented after the logfile will be considered as part of the command to run.

nohup|h

Attempt to ignore the NOHUP signal in the logger and child; this is useful if you may want to detach the controlling terminal, for example. See nohup.

Note that we cannot promise that the child will ignore it, unfortunately. If the child installs its own HUP handler, we can not affect it.

maxsize|m

The maximum permissable size for a log file. Once this size is reached, the logfile will be moved to a timestamped name, and a new one opened. The size is given in bytes.

noarchive|A

Don't create archive files when the log gets cleaned (due to exceeding the maximum size). Instead, just restart the log file (preserving the last n lines, where n is preserve-lines)

preserve-lines

The number of log lines to preserve when rotating but not archiving logs. Note that up to twice this number of lines are kept in memory whilst running, so a larger number increases the memory footprint. Also be careful that the total size of the lines does not itself exceed the maxsize, to avoid unpredictable behaviour. Defaults to 128.

help

Print a brief help message and exits.

longhelp

Print a longer help message and exits.

man

Prints the manual page and exits.

AUTHOR

Martyn J. Pearce fluffy@cpan.org

Copyright (c) 2001 Martyn J. Pearce.  This program is free software; you can
redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO