.\"	$Id$
.\"
.\" HylaFAX Facsimile Software
.\"
.\" Copyright (c) 1995-1996 Sam Leffler
.\" Copyright (c) 1995-1996 Silicon Graphics, Inc.
.\" HylaFAX is a trademark of Silicon Graphics
.\" 
.\" Permission to use, copy, modify, distribute, and sell this software and 
.\" its documentation for any purpose is hereby granted without fee, provided
.\" that (i) the above copyright notices and this permission notice appear in
.\" all copies of the software and related documentation, and (ii) the names of
.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
.\" publicity relating to the software without the specific, prior written
.\" permission of Sam Leffler and Silicon Graphics.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  
.\" 
.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 
.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
.\" OF THIS SOFTWARE.
.\"
.if n .po 0
.ds Fx \fIHyla\s-1FAX\s+1\fP
.TH FAXWATCH 8 "January 18, 1996"
.SH NAME
faxwatch \- monitor low-level \*(Fx server actions
.SH SYNOPSIS
.B /usr/sbin/faxwatch
[
.B \-g
] [
.B \-l
] [
.BI \-h " host"
]
.I trigger-expression
.SH DESCRIPTION
.I faxwatch
registers interest in one or more events on a \*(Fx server and
then prints subsequent event messages to the standard output.
The
.I faxwatch
program is intended mainly for testing the event distribution
mechanism used by the \*(Fx servers.
.PP
The
.I trigger-expression
is supplied as an argument to a ``\s-1SITE TRIGGER\s+1'' command
passed to the 
.IR hfaxd (8)
The syntax for this expression is:
.IP
[<\fIclass\fP>['<'\fIid\fP'>'][<\fImask\fP>|'*']]*
.PP
where <\fIclass\fP> defines a class of events and is one of:
.TP
.B J
for job-related events,
.TP
.B S
for fax send-related events,
.TP 
.B R
for fax receive-related events, and
.TP
.B M
for modem-related events.
.PP
A <\fImask\fP> is a 4-hex-digit mask of trigger events (see the
table below).
If ``*'' is specified then all events in the class are matched.
.PP
An <\fIid\fP> can be used to restrict matches to a specific
job or modem.  Eventually this will need to be generalized
for job groups.
.PP
Thus an example specification that would catch any event
for the modem on ttyf2 would be ``M<ttyf2>*'', and to be
notified when job 1932 is requeued or completes one would
use ``J<1932>4c60''.
.PP
The output from
.I faxwatch
is \s-1ASCII\s+1 text that describes each event.
.I faxwatch
runs until it is interrupted.
.SH OPTIONS
.TP 10
.B \-g
Display times and dates in 
Greenwich Mean Time (\s-1GMT\s+1).
NB: \fIthis is the default\fP.
.TP 10
.BI \-h " host"
Report the status of the server on a specific
.IR host .
The
.I host
may be either a symbolic name or a network address.
If no
.B \-h
option is supplied,
.I faxwatch
uses the
.SM FAXSERVER
environment variable to identify the \*(Fx server to contact.
If this variable is not set, then
.I faxwatch
checks for a setting in the configuration files (first in the
per-user file and then in the system-wide file).
If all of the above fails, then
.I faxwatch
attempts to contact a server on the machine where it is run.
.TP 10
.B \-l
Display times and dates in the local timezone of the server.
.TP 10
.B \-v
Trace the protocol exchanges between
.I faxwatch
and the
.I hfaxd
processes on the standard output.
.SH EVENTS
The following table specifies the current set of events that may be
monitored.
This information is subject to change; consult the source code for
reference.
.sp
.nf
.ta \w'MODEM_VOICE_BEGIN    'u +\w'\fBClass  \fP'u +\w'0x80000    'u
\fBEvent	Class	Mask	Description\fP
JOB_CREATE	J	0x0001	job created
JOB_SUSPEND	J	0x0002	job suspended
JOB_READY	J	0x0004	job ready to send
JOB_SLEEP	J	0x0008	job sleeping awaiting time-to-send
JOB_DEAD	J	0x0010	job marked dead
JOB_PROCESS	J	0x0020	job processed by scheduler
JOB_REAP	J	0x0040	job corpus reaped
JOB_ACTIVE	J	0x0080	job activated
JOB_REJECT	J	0x0100	job rejected
JOB_KILL	J	0x0200	job killed
JOB_BLOCKED	J	0x0400	job blocked by other job
JOB_DELAYED	J	0x0800	job delayed by tod restriction or similar
JOB_ALTERED\(S1	J	0x1000	job parameters altered
JOB_TIMEDOUT	J	0x2000	job kill timer expired
JOB_PREP_BEGIN	J	0x4000	job preparation started
JOB_PREP_END	J	0x8000	job preparation finished
.sp .5
SEND_BEGIN	S	0x0001	fax, send attempt started
SEND_CALL	S	0x0002	fax, call placed
SEND_CONNECTED	S	0x0004	fax, call answered by fax
SEND_PAGE	S	0x0008	fax, page transmit done
SEND_DOC	S	0x0010	fax, document transmit done
SEND_POLLRCVD	S	0x0020	fax, document retrieved by poll operation
SEND_POLLDONE	S	0x0040	fax, poll operation completed
SEND_END	S	0x0080	fax, send attempt finished
SEND_REFORMAT	S	0x0100	fax, job being reformatted
SEND_REQUEUE	S	0x0200	fax, job requeued
SEND_DONE	S	0x0400	fax, send job done
.sp .5
RECV_BEGIN	R	0x0001	fax, inbound call started
RECV_START	R	0x0002	fax, session started
RECV_PAGE	R	0x0004	fax, page receive done
RECV_DOC	R	0x0008	fax, document receive done
RECV_END	R	0x0010	fax, inbound call finished
.sp .5
MODEM_ASSIGN	M	0x0001	modem assigned to job
MODEM_RELEASE	M	0x0002	modem released by job
MODEM_DOWN	M	0x0004	modem marked down
MODEM_READY	M	0x0008	modem marked ready
MODEM_BUSY	M	0x0010	modem marked busy
MODEM_WEDGED	M	0x0020	modem considered wedged
MODEM_INUSE	M	0x0040	modem in use for outbound work
MODEM_DATA_BEGIN	M	0x0080	inbound data call begun
MODEM_DATA_END	M	0x0100	inbound data call finished
MODEM_VOICE_BEGIN	M	0x0200	inbound voice call begun
MODEM_VOICE_END	M	0x0400	inbound voice call finished
MODEM_CID	M	0x0800	inbound caller-ID information
.fi
.PP
\(S1 Event to be removed soon.
.SH "SEE ALSO"
.IR hylafax-server (5),
.IR hfaxd (8).