usr.bin/compile_et/compile_et.1

   1 .\"     $NetBSD: compile_et.1,v 1.2 2008/04/30 13:11:00 martin Exp $
   2 .\"
   3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Gregory McGarry.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  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
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd November 9, 2001
  31 .Dt COMPILE_ET 1
  32 .Os
  33 .Sh NAME
  34 .Nm compile_et
  35 .Nd error table compiler
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Ar --version
  39 .Op Ar --help
  40 .Ar file
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 utility reads the table describing error-code names and their
  45 associated messages in the file
  46 .Ar file
  47 and generates a C source file suitable for use with the
  48 .Xr com_err 3
  49 library.  The source file
  50 .Ar file
  51 must end with a suffix of
  52 .Dq .et
  53 and
  54 .Nm
  55 writes a C header file
  56 .Pa file.h
  57 which contains definitions of the numerical values of the error codes
  58 defined in the error table and a C source file
  59 .Pa file.c
  60 which should be compiled and linked with the executable.
  61 .Pp
  62 The source file is a plain ASCII text file.  A
  63 .Dq \&#
  64 in the source file
  65 is treated as a comment character, and all remaining text to the end
  66 of the source line will be ignored.  The source file consists of the
  67 following declarations:
  68 .Bl -tag -offset indent -width XXXXXX
  69 .It id [ Em base ] Em string
  70 Defines an identification string (such a a version string) which is
  71 recorded in the generated files.  It is mandatory and must be the
  72 first declaration in the source file.
  73 .It et Em name
  74 Specifies the name of the error table to be
  75 .Em name .
  76 It is mandatory and must be declared after the id declaration and
  77 before all other declarations.  The name of table is limited to four
  78 ASCII characters.  The optional argument
  79 .Em base
  80 specifies the base value of error codes the table.
  81 .Pp
  82 The name of the table is used to construct the name of a function
  83 .Fn initialize_<name>_error_table
  84 which must be called to register the error table with the
  85 .Xr com_err 3
  86 library.  A re-entrant (thread-safe) version called
  87 .Fn initialize_<name>_error_table_r
  88 is also defined.
  89 .It prefix Op Em string
  90 Defines a prefix to be applied to all error code names.  If no string
  91 is specified, the prefix is not defined.  It is an optional
  92 declaration and can appear more than once.
  93 .It index Em val
  94 Specifies the index
  95 .Em val
  96 in the error table for the following error code declaration.
  97 Subsequent error codes are allocated sequentially from the same value.
  98 It is an optional declaration and can appear more than once.
  99 .It ec Em cname , Em msg
 100 Defines an error code with the name
 101 .Em cname
 102 and its associated error message
 103 .Em msg .
 104 The error codes are assigned sequentially increasing numbers.  The
 105 name is placed into the C header file as an enumerated type.
 106 .It end
 107 Indicates the end of the error table.
 108 .El
 109 .Pp
 110 To maintain compatibility, new codes should be added to the end of an
 111 existing table, and codes should not be removed from tables.
 112 .Sh EXAMPLES
 113 A short sample error table might be
 114 .Pa test_err.et :
 115 .Pp
 116 .Bd -literal
 117         # example error table source file
 118         id      "\\$Id\\$"
 119         et      test
 120         prefix  TEST
 121         ec      PERM,           "Operation not permitted"
 122         ec      IO,             "I/O error"
 123         ec      NOMEM,          "Out of memory"
 124         ec      INVAL,          "Invalid argument"
 125         end
 126 .Ed
 127 .Pp
 128 Compiling the source file
 129 .Pa test_err.et
 130 with
 131 .Nm
 132 will create a C header file
 133 .Pa test_err.h
 134 containing the enumerated type
 135 .Va test_error_number
 136 with values TEST_PERM, TEST_IO, TEST_NOMEM and
 137 TEST_INVAL, and a C source file
 138 .Pa test_err.c
 139 containing the
 140 .Xr com_err 3
 141 initialisation function
 142 .Fn initialize_test_error_table .
 143 .Sh SEE ALSO
 144 .Xr com_err 3