145 lines
4.7 KiB
Groff
145 lines
4.7 KiB
Groff
.\" $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
|