.\" Copyright (c) 2003 The Anarcat
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/examples/mdoc/example.1,v 1.12.2.6 2001/08/17 13:08:35 ru Exp $
.\"
.\" Note: The date here should be updated whenever a non-trivial
.\" change is made to the manual page.
.Dd December 9, 2003
.Dt BUILDIT 8
.Os
.Sh NAME
.Nm buildit
.Nd "time a command, log its output and mail notification when finished"
.Sh SYNOPSIS
.Nm
.Op Fl m
.Fl l Pa logfile
.Ar command ...
.Sh DESCRIPTION
The
.Nm
command is a trivial wrapper script for running commands
unattended.
.Nm
will start the given
.Ar command
using
.Xr time 1 ;
log the stdout and stderr of the command
in the given
.Pa logfile ;
wait for termination of the command while printing its output on the
terminal; and then optionally mail the head and tail of the logfile to
the calling user.
.Pp
The
.Xr date 1
command is called before and after the command so that there is a
start and end date of the process in the
.Pa logfile .
.Sh OPTIONS
The options are as follows:
.Bl -tag -width ".Fl d Ar argument"
.It Fl m
do not send mail when finished.
.It Fl l Pa logfile
log stdin and stderr to this
.Pa logfile .
If the
.Pa logfile
already exists, it is moved to
.Pa logfile.old .
.El
.Sh EXAMPLES
Here are typical usages of the
.Nm
command:
.Pp
.Dl "buildit -l /var/src/install.out make installworld | whereintheworld"
.Pp
.Dl "buildit -l trace.log povray +iscene +oscene.out"
.Sh DIAGNOSTICS
Exit status is 0 on success, and 1 if the command
fails for one of the following reasons:
.Bl -diag
.It "-l parameter mandatory"
No logfile has been chosen.
.El
.Sh COMPATIBILITY
The
.Xr mail 1
command is called to send email, with the
.Fl s
flag to set the subject. This might not work equally on all systems.
.Sh SEE ALSO
.Xr time 1 ,
.Xr wait 1 ,
.Xr head 1 ,
.Xr tail 1 ,
.Xr mail 1 ,
.Xr date 1 ,
.Xr kill 1 ,
.Xr whereintheworld 8 .
.Sh HISTORY
The
.Nm
manual page was first written for worldtools 1.2
.Sh AUTHORS
The
.Nm
command and this manual page were written by
.An The Anarcat Aq anarcat@anarcat.ath.cx .
.Sh BUGS
.Nm
might leave stray processes running, even after being interrupted. This
is due to a bug in
.Xr sh
since calling
.Xr trap
from a subshell has no effect. See the file
.Pa test_trap.sh
in the source distribution for an example.