Thu Apr 28 15:01:27 2011 UTC ()
New sentence, new line. Use more markup.


(wiz)
diff -r1.5 -r1.6 src/usr.bin/compile_et/compile_et.1
cvs diff -r1.5 -r1.6 src/usr.bin/compile_et/Attic/compile_et.1 (expand / switch to unified diff)

--- src/usr.bin/compile_et/Attic/compile_et.1 2010/04/05 21:33:09 1.5
+++ src/usr.bin/compile_et/Attic/compile_et.1 2011/04/28 15:01:27 1.6
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: compile_et.1,v 1.5 2010/04/05 21:33:09 pgoyette Exp $ 1.\" $NetBSD: compile_et.1,v 1.6 2011/04/28 15:01:27 wiz Exp $
2.\" 2.\"
3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Gregory McGarry. 7.\" by Gregory McGarry.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -25,94 +25,99 @@ @@ -25,94 +25,99 @@
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd November 9, 2001 30.Dd November 9, 2001
31.Dt COMPILE_ET 1 31.Dt COMPILE_ET 1
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm compile_et 34.Nm compile_et
35.Nd error table compiler 35.Nd error table compiler
36.Sh SYNOPSIS 36.Sh SYNOPSIS
37.Nm 37.Nm
38.Op Ar --version 38.Op Fl Fl help
39.Op Ar --help 39.Op Fl Fl version
40.Ar file 40.Ar file
41.Sh DESCRIPTION 41.Sh DESCRIPTION
42The 42The
43.Nm 43.Nm
44utility reads the table describing error-code names and their 44utility reads the table describing error-code names and their
45associated messages in the file 45associated messages in the file
46.Ar file 46.Ar file
47and generates a C source file suitable for use with the 47and generates a C source file suitable for use with the
48.Xr com_err 3 48.Xr com_err 3
49library. The source file 49library.
 50The source file
50.Ar file 51.Ar file
51must end with a suffix of 52must end with a suffix of
52.Dq .et 53.Dq .et
53and 54and
54.Nm 55.Nm
55writes a C header file 56writes a C header file
56.Pa file.h 57.Pa file.h
57which contains definitions of the numerical values of the error codes 58which contains definitions of the numerical values of the error codes
58defined in the error table and a C source file 59defined in the error table and a C source file
59.Pa file.c 60.Pa file.c
60which should be compiled and linked with the executable. 61which should be compiled and linked with the executable.
61.Pp 62.Pp
62The source file is a plain ASCII text file. A 63The source file is a plain ASCII text file.
 64A
63.Dq \&# 65.Dq \&#
64in the source file 66in the source file
65is treated as a comment character, and all remaining text to the end 67is treated as a comment character, and all remaining text to the end
66of the source line will be ignored. The source file consists of the 68of the source line will be ignored.
67following declarations: 69The source file consists of the following declarations:
68.Bl -tag -offset indent -width XXXXXX 70.Bl -tag -offset indent -width XXXXXX
69.It id [ Em base ] Em string 71.It id [ Em base ] Em string
70Defines an identification string (such as a version string) which is 72Defines an identification string (such as a version string) which is
71recorded in the generated files. It is mandatory and must be the 73recorded in the generated files.
72first declaration in the source file. 74It is mandatory and must be the first declaration in the source
 75file.
73.It et Em name 76.It et Em name
74Specifies the name of the error table to be 77Specifies the name of the error table to be
75.Em name . 78.Em name .
76It is mandatory and must be declared after the id declaration and 79It is mandatory and must be declared after the id declaration and
77before all other declarations. The name of table is limited to four 80before all other declarations.
78ASCII characters. The optional argument 81The name of table is limited to four ASCII characters.
 82The optional argument
79.Em base 83.Em base
80specifies the base value of error codes the table. 84specifies the base value of error codes the table.
81.Pp 85.Pp
82The name of the table is used to construct the name of a function 86The name of the table is used to construct the name of a function
83.Fn initialize_<name>_error_table 87.Fn initialize_<name>_error_table
84which must be called to register the error table with the 88which must be called to register the error table with the
85.Xr com_err 3 89.Xr com_err 3
86library. A re-entrant (thread-safe) version called 90library.
 91A re-entrant (thread-safe) version called
87.Fn initialize_<name>_error_table_r 92.Fn initialize_<name>_error_table_r
88is also defined. 93is also defined.
89.It prefix Op Em string 94.It prefix Op Em string
90Defines a prefix to be applied to all error code names. If no string 95Defines a prefix to be applied to all error code names.
91is specified, the prefix is not defined. It is an optional 96If no string is specified, the prefix is not defined.
92declaration and can appear more than once. 97It is an optional declaration and can appear more than once.
93.It index Em val 98.It index Em val
94Specifies the index 99Specifies the index
95.Em val 100.Em val
96in the error table for the following error code declaration. 101in the error table for the following error code declaration.
97Subsequent error codes are allocated sequentially from the same value. 102Subsequent error codes are allocated sequentially from the same value.
98It is an optional declaration and can appear more than once. 103It is an optional declaration and can appear more than once.
99.It ec Em cname , Em msg 104.It ec Em cname , Em msg
100Defines an error code with the name 105Defines an error code with the name
101.Em cname 106.Em cname
102and its associated error message 107and its associated error message
103.Em msg . 108.Em msg .
104The error codes are assigned sequentially increasing numbers. The 109The error codes are assigned sequentially increasing numbers.
105name is placed into the C header file as an enumerated type. 110The name is placed into the C header file as an enumerated type.
106.It end 111.It end
107Indicates the end of the error table. 112Indicates the end of the error table.
108.El 113.El
109.Pp 114.Pp
110To maintain compatibility, new codes should be added to the end of an 115To maintain compatibility, new codes should be added to the end of an
111existing table, and codes should not be removed from tables. 116existing table, and codes should not be removed from tables.
112.Sh EXAMPLES 117.Sh EXAMPLES
113A short sample error table might be 118A short sample error table might be
114.Pa test_err.et : 119.Pa test_err.et :
115.Pp 120.Pp
116.Bd -literal 121.Bd -literal
117 # example error table source file 122 # example error table source file
118 id "\e$Id\e$" 123 id "\e$Id\e$"
@@ -123,22 +128,27 @@ A short sample error table might be @@ -123,22 +128,27 @@ A short sample error table might be
123 ec NOMEM, "Out of memory" 128 ec NOMEM, "Out of memory"
124 ec INVAL, "Invalid argument" 129 ec INVAL, "Invalid argument"
125 end 130 end
126.Ed 131.Ed
127.Pp 132.Pp
128Compiling the source file 133Compiling the source file
129.Pa test_err.et 134.Pa test_err.et
130with 135with
131.Nm 136.Nm
132will create a C header file 137will create a C header file
133.Pa test_err.h 138.Pa test_err.h
134containing the enumerated type 139containing the enumerated type
135.Va test_error_number 140.Va test_error_number
136with values TEST_PERM, TEST_IO, TEST_NOMEM and 141with values
137TEST_INVAL, and a C source file 142.Dv TEST_PERM ,
 143.Dv TEST_IO ,
 144.Dv TEST_NOMEM
 145and
 146.Dv TEST_INVAL ,
 147and a C source file
138.Pa test_err.c 148.Pa test_err.c
139containing the 149containing the
140.Xr com_err 3 150.Xr com_err 3
141initialisation function 151initialisation function
142.Fn initialize_test_error_table . 152.Fn initialize_test_error_table .
143.Sh SEE ALSO 153.Sh SEE ALSO
144.Xr com_err 3 154.Xr com_err 3