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


(wiz)
diff -r1.2 -r1.3 src/lib/libcom_err/com_err.3
cvs diff -r1.2 -r1.3 src/lib/libcom_err/Attic/com_err.3 (expand / switch to unified diff)

--- src/lib/libcom_err/Attic/com_err.3 2008/04/30 13:10:51 1.2
+++ src/lib/libcom_err/Attic/com_err.3 2011/04/28 14:59:27 1.3
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: com_err.3,v 1.2 2008/04/30 13:10:51 martin Exp $ 1.\" $NetBSD: com_err.3,v 1.3 2011/04/28 14:59: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
@@ -32,88 +32,94 @@ @@ -32,88 +32,94 @@
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm com_err , 34.Nm com_err ,
35.Nm com_err_va , 35.Nm com_err_va ,
36.Nm error_message , 36.Nm error_message ,
37.Nm error_table_name , 37.Nm error_table_name ,
38.Nm init_error_table , 38.Nm init_error_table ,
39.Nm set_com_err_hook , 39.Nm set_com_err_hook ,
40.Nm reset_com_err_hook 40.Nm reset_com_err_hook
41.Nd common error display library 41.Nd common error display library
42.Sh LIBRARY 42.Sh LIBRARY
43Common Error Library (libcom_err, -lcom_err) 43Common Error Library (libcom_err, -lcom_err)
44.Sh SYNOPSIS 44.Sh SYNOPSIS
45.Fd #include <stdio.h> 45.In stdio.h
46.Fd #include <stdarg.h> 46.In stdarg.h
47.Fd #include <krb5/com_err.h> 47.In krb5/com_err.h
48.Fd #include \&"XXX_err.h\&" 48.In \&"XXX_err.h\&"
49.Pp 49.Pp
50typedef void (*errf)(const char *, long, const char *, ...); 50typedef void (*errf)(const char *, long, const char *, ...);
51.Ft void 51.Ft void
52.Fn com_err "const char *whoami" "long code" "const char *format" "..." 52.Fn com_err "const char *whoami" "long code" "const char *format" "..."
53.Ft void 53.Ft void
54.Fn com_err_va "const char *whoami" "long code" "const char *format" "..." 54.Fn com_err_va "const char *whoami" "long code" "const char *format" "..."
55.Ft const char * 55.Ft const char *
56.Fn error_message "long code" 56.Fn error_message "long code"
57.Ft const char * 57.Ft const char *
58.Fn error_table_name "int num" 58.Fn error_table_name "int num"
59.Ft int 59.Ft int
60.Fn init_error_table "const char **msgs" "long base" "int count" 60.Fn init_error_table "const char **msgs" "long base" "int count"
61.Ft errf 61.Ft errf
62.Fn set_com_err_hook "errf func" 62.Fn set_com_err_hook "errf func"
63.Ft errf 63.Ft errf
64.Fn reset_com_err_hook "" 64.Fn reset_com_err_hook ""
65.Ft void 65.Ft void
66.Fn add_to_error_table "struct et_list *new_table" 66.Fn add_to_error_table "struct et_list *new_table"
67.Sh DESCRIPTION 67.Sh DESCRIPTION
68The 68The
69.Nm 69.Nm
70library provides a common error-reporting mechanism for defining and 70library provides a common error-reporting mechanism for defining and
71accessing error codes and descriptions for application software 71accessing error codes and descriptions for application software
72packages. Error descriptions are defined in a table and error codes 72packages.
73are used to index the table. The error table, the descriptions and 73Error descriptions are defined in a table and error codes are used
74the error codes are generated using 74to index the table.
 75The error table, the descriptions and the error codes are generated
 76using
75.Xr compile_et 1 . 77.Xr compile_et 1 .
76.Pp 78.Pp
77The error table is registered with the 79The error table is registered with the
78.Nm 80.Nm
79library by calling its initialisation function defined in its header 81library by calling its initialisation function defined in its header
80file. The initialisation function is generally defined as 82file.
 83The initialisation function is generally defined as
81.Fn initialize_<name>_error_table , 84.Fn initialize_<name>_error_table ,
82where 85where
83.Em name 86.Em name
84is the name of the error table. 87is the name of the error table.
85.Pp 88.Pp
86Any variable which is to contain an error code should be declared 89Any variable which is to contain an error code should be declared
87.Em <name>_error_number 90.Em <name>_error_number
88where 91where
89.Em name 92.Em name
90is the name of the error table. 93is the name of the error table.
91.Sh FUNCTIONS 94.Sh FUNCTIONS
92The following functions are available to the application developer: 95The following functions are available to the application developer:
93.Bl -tag -width compact 96.Bl -tag -width compact
94.It Fn com_err "whoami" "code" "format" "..." 97.It Fn com_err "whoami" "code" "format" "..."
95Displays an error message on standard error composed of the 98Displays an error message on standard error composed of the
96.Fa whoami 99.Fa whoami
97string, which should specify the program name, followed by an error 100string, which should specify the program name, followed by an error
98message generated from 101message generated from
99.Fa code , 102.Fa code ,
100and a string produced using the 103and a string produced using the
101.Xr printf 3 104.Xr printf 3
102.Fa format 105.Fa format
103string and any following arguments. If 106string and any following arguments.
 107If
104.Fa format 108.Fa format
105is NULL, the formatted message will not be 109is
106printed. The argument 110.Dv NULL ,
 111the formatted message will not be printed.
 112The argument
107.Fa format 113.Fa format
108may not be omitted. 114may not be omitted.
109.It Fn com_err_va "whoami" "code" "format" "va_list args" 115.It Fn com_err_va "whoami" "code" "format" "va_list args"
110This routine provides an interface, equivalent to 116This routine provides an interface, equivalent to
111.Fn com_err , 117.Fn com_err ,
112which may be used by higher-level variadic functions (functions which 118which may be used by higher-level variadic functions (functions which
113accept variable numbers of arguments). 119accept variable numbers of arguments).
114.It Fn error_message "code" 120.It Fn error_message "code"
115Returns the character string error message associate with 121Returns the character string error message associate with
116.Fa code . 122.Fa code .
117If 123If
118.Fa code is associated with an unknown error table, or if 124.Fa code is associated with an unknown error table, or if
119.Fa code 125.Fa code
@@ -145,28 +151,29 @@ custom error tables that have not been g @@ -145,28 +151,29 @@ custom error tables that have not been g
145Although this routine is available for use when needed, its use should 151Although this routine is available for use when needed, its use should
146be restricted. 152be restricted.
147.It Fn set_com_err_hook "func" 153.It Fn set_com_err_hook "func"
148Provides a hook into the 154Provides a hook into the
149.Nm 155.Nm
150library to allow the routine 156library to allow the routine
151.Fa func 157.Fa func
152to be dynamically substituted for 158to be dynamically substituted for
153.Fn com_err . 159.Fn com_err .
154After 160After
155.Fn set_com_err_hook 161.Fn set_com_err_hook
156 has been called, calls to 162 has been called, calls to
157.Fn com_err 163.Fn com_err
158will turn into calls to the new hook routine. This function is 164will turn into calls to the new hook routine.
159intended to be used in daemons to use a routine which calls 165This function is intended to be used in daemons to use a routine
 166which calls
160.Xr syslog 3 , 167.Xr syslog 3 ,
161or in a window system application to pop up a dialogue box. 168or in a window system application to pop up a dialogue box.
162.It Fn reset_com_err_hook "" 169.It Fn reset_com_err_hook ""
163Turns off the hook set in 170Turns off the hook set in
164.Fn set_com_err_hook . 171.Fn set_com_err_hook .
165.It Fn add_to_error_table "new_table" 172.It Fn add_to_error_table "new_table"
166Add the error table, its messages strings and error codes in 173Add the error table, its messages strings and error codes in
167.Fa new_table 174.Fa new_table
168to the internal error table. 175to the internal error table.
169.El 176.El
170.Sh EXAMPLES 177.Sh EXAMPLES
171The following is an example using the table defined in 178The following is an example using the table defined in
172.Xr compile_et 1 : 179.Xr compile_et 1 :