if no home directory, log into '/'; delete old #ifdef/notdef and

[unix-history] / usr / src / libexec / bugfiler / bugfiler.8

.\" Copyright (c) 1983 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms are permitted
.\" provided that the above copyright notice and this paragraph are
.\" duplicated in all such forms and that any documentation,
.\" advertising materials, and other materials related to such
.\" distribution and use acknowledge that the software was developed
.\" by the University of California, Berkeley.  The name of the
.\" University may not be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\"	@(#)bugfiler.8	6.9 (Berkeley) %G%
.\"
.TH BUGFILER 8 ""
.UC 5
.SH NAME
bugfiler \- file bug reports in folders automatically
.SH SYNOPSIS
.B bugfiler
[ -ar ] [-v version]
.SH DESCRIPTION
\fIBugfiler\fP is a program to automatically intercept, acknowledge,
redistribute and store bug reports.  \fIBugfiler\fP is normally invoked
by the mail delivery program with a line similar to the following in
/usr/lib/aliases.
.PP
.DT
	bugs:	"|bugfiler"
.br
.PP
It should be noted that the login ``bugs'' must exist for the bugfiler
to run.  Unless otherwise noted all paths used by \fIbugfiler\fP are
relative to the home directory of this login.  \fIBugfiler\fP also
expects all of its files and directories to be owned by ``bugs''.
.PP
For the bug report to be correctly filed, it must contain a line
in the following format:
.PP
.DT
	Index:	\fIfolder\fP	\fIversion\fP
.br
.PP
The directories ~bugs/\fIversion\fP and ~bugs/\fIversion\fP/\fIfolder\fP
must exist before \fIbugfiler\fP attempts to store the bug report.  Bug
reports will be stored in files named by the concatenation of \fIversion,
folder,\fP and sequential numbers, i.e. if \fIversion\fP is ``4.3BSD'' and
\fIfolder\fP is ``ucb'' the first bug report will be placed in
~bugs/4.3BSD/ucb/1.  If \fIfolder\fP contains more than one component only
the first one will be used, e.g. if \fIfolder\fP is ``bin/from.c'' or
``bin/adb/con.c'' it will be treated as if it were simply ``bin''.  The
\fI-v\fP flag is provided as a means to override the \fIversion\fP
provided within the bug report itself.
.PP
A mail acknowledgement is automatically sent to the bug report filer unless
the \fB-a\fP flag is supplied.  The file ~bugs/\fIversion\fP/bug:ack is
appended to this acknowledgement.
.PP
If the \fB-r\fP flag is not supplied, redistribution of the bug reports
is done as specified in the file ~bugs/\fIversion\fP/bug:redist.  This file
is in the format of the \fIaliases\fP(5) file, including comments and
entries requiring multiple lines, with the single exception that the
\fIfolder\fP component of the ``Index:'' line replaces the name to alias.
The special folder ``all:'' receives a redistribution of all bug reports
sent to this \fIversion\fP.  For example, the \fIbug:redist\fP file
.PP
.DT
	#	bigbug gets a copy of everything
.br
	all:	bigbug
.br
	#	ucb folder redistribution list
.br
	ucb:	karels, kjd@coke.berkeley.edu
.br
		ra@beno.css.gov
.br
.PP
will send copies of all bug reports with ``ucb'' as the \fIfolder\fP
to bigbug, karels, kjd, and ra.
.PP
Reports that cannot be filed, due to an invalid ``Index:'' line or
some other error, are placed in the directory ~bugs/errors.  The
\fIbugfiler\fP maintainer should correct these bug reports and then
run \fIbugfiler\fP, with the corrected report as its standard input,
as bug reports with errors are neither acknowledged or redistributed.
All reports that \fIbugfiler\fP handles are logged in ~bugs/log.
.PP
Valid bugs are also logged in the file ~bugs/\fIversion\fP/summary.
This file has an entry for each bug report for \fIversion\fP in the
format:
.PP
.DT
	Filename		Date
.br
		Subject:
.br
		Index:
.br
		Owner:	Bugs Bunny
.br
		Status:	Received
.br
.PP
\fIFilename\fP is the concatenation of \fIversion, folder,\fP and a number
as described above.  \fIDate\fP is the date as reported by the system
clock, using ctime(3).  The \fISubject:\fP and \fIIndex:\fP lines are
copies of the ``Subject:'' and ``Index:'' lines contained in the bug
report.  The \fIOwner\fP and \fIStatus\fP fields are intended to provide a
rudimentary method of tracking the status of bug reports.
.PP
The file ~bugs/bug:lock is the focus of all locking for \fIbugfiler.\fP
If you wish to manipulate any of the log or error files, rename or remove
it and \fIbugfiler\fP will treat all bug reports that it receives as if
they were incorrectly formatted, i.e. it will place them in the directory
~bugs/errors, for later recovery by the \fIbugfiler\fP maintainer.
Obviously, this file must be created when you first install \fIbugfiler\fP.
.PP
All errors that occur before ~bugs/log is found are logged into the system
log file, using
.IR syslog (8).
.SH FILES
.br
.TP 25
~bugs/bug:ack
the acknowledgement message
.TP 25
~bugs/bug:redist
the redistribution list
.TP 25
~bugs/bug:lock
the locking file
.TP 25
~bugs/errors/BUG_??????
bug reports with format errors
.TP 25
~bugs/log
the log file
.TP 25
~bugs/folder/summary
the summary files
.TP 25
/usr/lib/sendmail
the mail delivery program
.TP 25
/usr/lib/bugformat
a sample bug report format
.SH "SEE ALSO"
sendbug(1), aliases(5), syslog(8)
.SH BUGS
Since mail can be forwarded in a number of different ways, \fIbugfiler\fP
does not recognize forwarded mail and will acknowledge to the forwarder
instead of the original sender unless there is a `Reply-To' field in the
header.
.PP
This version of the bugfiler is not compatible with the version
released with 4.3BSD in that it doesn't complain to the sender about
incorrectly formatted bug reports.
Frankly, we got tired of the profanity, not to mention the extended
conversations
.I bugfiler
was holding with
.IR vacation (1).