- New function Buf_Append(), which is given a pointer to a string to
[dragonfly.git] / contrib / com_err / compile_et.1
1 .\" Copyright (c) 1988 Massachusetts Institute of Technology,
2 .\" Student Information Processing Board.  All rights reserved.
3 .\"
4 .\" $FreeBSD: src/contrib/com_err/compile_et.1,v 1.1.2.2 2001/03/05 11:27:28 asmodai Exp $
5 .\" $DragonFly: src/contrib/com_err/compile_et.1,v 1.2 2003/06/17 04:23:58 dillon Exp $
6 .\"
7 .Dd     November 22, 1988
8 .Os
9 .Dt COMPILE_ET 1
10 .Sh NAME
11 .Nm compile_et
12 .Nd error table compiler
13 .Sh SYNOPSIS
14 .Nm compile_et
15 .Ar file
16 .Sh DESCRIPTION
17 .Nm Compile_et
18 converts a table listing error-code names and associated messages into
19 a C source file suitable for use with the
20 .Xr com_err 3
21 library.
22 .Pp
23 The source file name must end with a suffix of ``.et''; the file
24 consists of a declaration supplying the name (up to four characters
25 long) of the error-code table:
26 .Pp
27 .Em error_table name
28 .Pp
29 followed by up to 256 entries of the form:
30 .Pp
31 .Em error_code name ,
32 .No \(dq Ns Em string Ns \(dq
33 .Pp
34 and a final
35 .Pp
36 .Em end
37 .Pp
38 to indicate the end of the table.
39 .Pp
40 The name of the table is used to construct the name of a subroutine
41 .Em initialize_XXXX_error_table
42 which must be called in order for the
43 .Xr com_err 3
44 library to recognize the error table.
45 .Pp
46 The various error codes defined are assigned sequentially increasing
47 numbers (starting with a large number computed as a hash function of
48 the name of the table); thus for compatibility it is suggested that
49 new codes be added only to the end of an existing table, and that no
50 codes be removed from tables.
51 .Pp
52 The names defined in the table are placed into a C header file with
53 preprocessor directives defining them as integer constants of up to
54 32 bits in magnitude.
55 .Pp
56 A C source file is also generated which should be compiled and linked
57 with the object files which reference these error codes; it contains
58 the text of the messages and the initialization subroutine.  Both C
59 files have names derived from that of the original source file, with
60 the ``.et'' suffix replaced by ``.c'' and ``.h''.
61 .Pp
62 A ``#'' in the source file is treated as a comment character, and all
63 remaining text to the end of the source line will be ignored.
64 .Sh BUGS
65 Since
66 .Nm compile_et
67 uses a very simple parser based on
68 .Xr yacc 1 ,
69 its error recovery leaves much to be desired.
70 .Sh SEE ALSO
71 .Xr yacc 1 ,
72 .Xr com_err 3
73 .Rs
74 .%A Ken Raeburn
75 .%T "A Common Error Description Library for UNIX"
76 .Re