NetBSD-5.0.2/usr.bin/compile_et/compile_et.1

Compare this file to the similar file:
Show the results in this format:
.\"     $NetBSD: compile_et.1,v 1.2 2008/04/30 13:11:00 martin Exp $
.\"
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Gregory McGarry.
.\"
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.Dd November 9, 2001
.Dt COMPILE_ET 1
.Os
.Sh NAME
.Nm compile_et
.Nd error table compiler
.Sh SYNOPSIS
.Nm
.Op Ar --version
.Op Ar --help
.Ar file
.Sh DESCRIPTION
The
.Nm
utility reads the table describing error-code names and their
associated messages in the file
.Ar file
and generates a C source file suitable for use with the
.Xr com_err 3
library.  The source file
.Ar file
must end with a suffix of
.Dq .et
and
.Nm
writes a C header file
.Pa file.h
which contains definitions of the numerical values of the error codes
defined in the error table and a C source file
.Pa file.c
which should be compiled and linked with the executable.
.Pp
The source file is a plain ASCII text file.  A
.Dq \&#
in the source file
is treated as a comment character, and all remaining text to the end
of the source line will be ignored.  The source file consists of the
following declarations:
.Bl -tag -offset indent -width XXXXXX
.It id [ Em base ] Em string
Defines an identification string (such a a version string) which is
recorded in the generated files.  It is mandatory and must be the
first declaration in the source file.
.It et Em name
Specifies the name of the error table to be
.Em name .
It is mandatory and must be declared after the id declaration and
before all other declarations.  The name of table is limited to four
ASCII characters.  The optional argument
.Em base
specifies the base value of error codes the table.
.Pp
The name of the table is used to construct the name of a function
.Fn initialize_<name>_error_table
which must be called to register the error table the the
.Xr com_err 3
library.  A re-entrant (thread-safe) version called
.Fn initialize_<name>_error_table_r
is also defined.
.It prefix Op Em string
Defines a prefix to be applied to all error code names.  If no string
is specified, the prefix is not defined.  It is an optional
declaration and can appear more than once.
.It index Em val
Specifies the index
.Em val
in the error table for the following error code declaration.
Subsequent error codes are allocated sequentially from the same value.
It is an optional declaration and can appear more than once.
.It ec Em cname , Em msg
Defines an error code with the name
.Em cname
and its associated error message
.Em msg .
The error codes are assigned sequentially increasing numbers.  The
name is placed into the C header file as an enumerated type.
.It end
Indicates the end of the error table.
.El
.Pp
To maintain compatibility, new codes should be added to the end of an
existing table, and codes should not be removed from tables.
.Sh EXAMPLES
A short sample error table might be
.Pa test_err.et :
.Pp
.Bd -literal
	# example error table source file
	id	"\\$Id\\$"
	et	test
	prefix	TEST
	ec	PERM,		"Operation not permitted"
	ec	IO,		"I/O error"
	ec	NOMEM,		"Out of memory"
	ec	INVAL,		"Invalid argument"
	end
.Ed
.Pp
Compiling the source file
.Pa test_err.et
with
.Nm
will create a C header file
.Pa test_err.h
containing the enumerated type
.Va test_error_number
with values TEST_PERM, TEST_IO, TEST_NOMEM and
TEST_INVAL, and a C source file
.Pa test_err.c
containing the
.Xr com_err 3
initialisation function
.Fn initialize_test_error_table .
.Sh SEE ALSO
.Xr com_err 3