.\" Copyright (c) 1988 Massachusetts Institute of Technology,
.\" Student Information Processing Board.  All rights reserved.
.\"
.\" $OpenBSD: compile_et.1,v 1.14 2007/05/31 19:20:08 jmc Exp $
.\" $Header: /cvs/OpenBSD/src/usr.bin/compile_et/compile_et.1,v 1.14 2007/05/31 19:20:08 jmc Exp $
.\"
.Dd $Mdocdate: May 31 2007 $
.Dt COMPILE_ET 1
.Os
.Sh NAME
.Nm compile_et
.Nd error table compiler
.Sh SYNOPSIS
.Nm compile_et
.Ar file
.Sh DESCRIPTION
.Nm
converts a table listing error-code names and associated messages into
a C source file suitable for use with the
.Xr com_err 3
library.
.Pp
The source file name must end with a suffix of
.Dq .et ;
the file
consists of headers and declarations supplying the name (up to four characters
long) of the error-code table.
.Pp
The file may have these declarations:
.Bl -tag -width Ds
.It Sy id Ar string
Specify
.Ar string
as a revision control system tag.
.It Sy prefix Ar string
Prepends
.Ar string
to all error codes specified in the file.
.It Sy error_table Ar name
Specifies the name of the error table.
.It Sy index Ar number
Sets the assigned error number for the next entry.
.It Xo Sy error_code
.Ar name ,
.Qq Ar string
.Xc
Declares an error code called
.Ar name
with description
.Ar string ;
up to 256 error codes are allowed.
.It Sy end
Indicates the end of the table.
.El
.Pp
The name of the table is used to construct the name of a subroutine
.Em initialize_XXXX_error_table
which must be called in order for the
.Xr com_err 3
library to recognize the error table.
.Pp
The various error codes defined are assigned sequentially increasing
numbers (starting with a large number computed as a hash function of
the name of the table); thus for compatibility it is suggested that
new codes be added only to the end of an existing table, and that no
codes be removed from tables.
.Pp
The names defined in the table are placed into a C header file with
preprocessor directives defining them as integer constants of up to
32 bits in magnitude.
.Pp
A C source file is also generated which should be compiled and linked
with the object files which reference these error codes; it contains
the text of the messages and the initialization subroutine.
Both C files have names derived from that of the original source file, with
the
.Dq .et
suffix replaced by
.Dq \&.c
and
.Dq \&.h .
.Pp
A hash mark
.Pq Ql #
in the source file is treated as a comment character; subsequent
characters to the end of the source line will be ignored.
.Sh SEE ALSO
.Xr yacc 1 ,
.Xr com_err 3
.Rs
.%A Ken Raeburn
.%T "A Common Error Description Library for UNIX"
.Re
.Sh BUGS
Since
.Nm
uses a very simple parser based on
.Xr yacc 1 ,
its error recovery leaves much to be desired.