1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
|
.\" Copyright (c) 1997, 2001 - 2006 Kungliga Tekniska Högskolan
.\" (Royal Institute of Technology, Stockholm, Sweden).
.\" All rights reserved.
.\"
.\" 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.
.\"
.\" 3. Neither the name of the Institute nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE 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 INSTITUTE 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.
.\"
.\" $Id: krb5_warn.3 19085 2006-11-21 07:55:20Z lha $
.\"
.Dd May 1, 2006
.Dt KRB5_WARN 3
.Os HEIMDAL
.Sh NAME
.Nm krb5_abort ,
.Nm krb5_abortx ,
.Nm krb5_clear_error_string ,
.Nm krb5_err ,
.Nm krb5_errx ,
.Nm krb5_free_error_string ,
.Nm krb5_get_err_text ,
.Nm krb5_get_error_message ,
.Nm krb5_get_error_string ,
.Nm krb5_have_error_string ,
.Nm krb5_set_error_string ,
.Nm krb5_set_warn_dest ,
.Nm krb5_get_warn_dest ,
.Nm krb5_vabort ,
.Nm krb5_vabortx ,
.Nm krb5_verr ,
.Nm krb5_verrx ,
.Nm krb5_vset_error_string ,
.Nm krb5_vwarn ,
.Nm krb5_vwarnx ,
.Nm krb5_warn ,
.Nm krb5_warnx
.Nd Heimdal warning and error functions
.Sh LIBRARY
Kerberos 5 Library (libkrb5, -lkrb5)
.Sh SYNOPSIS
.In krb5.h
.Ft krb5_error_code
.Fn krb5_abort "krb5_context context" "krb5_error_code code" "const char *fmt" "..."
.Ft krb5_error_code
.Fn krb5_abortx "krb5_context context" "krb5_error_code code" "const char *fmt" "..."
.Ft void
.Fn krb5_clear_error_string "krb5_context context"
.Ft krb5_error_code
.Fn krb5_err "krb5_context context" "int eval" "krb5_error_code code" "const char *format" "..."
.Ft krb5_error_code
.Fn krb5_errx "krb5_context context" "int eval" "const char *format" "..."
.Ft void
.Fn krb5_free_error_string "krb5_context context" "char *str"
.Ft krb5_error_code
.Fn krb5_verr "krb5_context context" "int eval" "krb5_error_code code" "const char *format" "va_list ap"
.Ft krb5_error_code
.Fn krb5_verrx "krb5_context context" "int eval" "const char *format" "va_list ap"
.Ft krb5_error_code
.Fn krb5_vset_error_string "krb5_context context" "const char *fmt" "va_list args"
.Ft krb5_error_code
.Fn krb5_vwarn "krb5_context context" "krb5_error_code code" "const char *format" "va_list ap"
.Ft krb5_error_code
.Fn krb5_vwarnx "krb5_context context" "const char *format" "va_list ap"
.Ft krb5_error_code
.Fn krb5_warn "krb5_context context" "krb5_error_code code" "const char *format" "..."
.Ft krb5_error_code
.Fn krb5_warnx "krb5_context context" "const char *format" "..."
.Ft krb5_error_code
.Fn krb5_set_error_string "krb5_context context" "const char *fmt" "..."
.Ft krb5_error_code
.Fn krb5_set_warn_dest "krb5_context context" "krb5_log_facility *facility"
.Ft "char *"
.Ft krb5_log_facility *
.Fo krb5_get_warn_dest
.Fa "krb5_context context"
.Fc
.Fn krb5_get_err_text "krb5_context context" "krb5_error_code code"
.Ft char*
.Fn krb5_get_error_string "krb5_context context"
.Ft char*
.Fn krb5_get_error_message "krb5_context context, krb5_error_code code"
.Ft krb5_boolean
.Fn krb5_have_error_string "krb5_context context"
.Ft krb5_error_code
.Fn krb5_vabortx "krb5_context context" "const char *fmt" "va_list ap"
.Ft krb5_error_code
.Fn krb5_vabort "krb5_context context" "const char *fmt" "va_list ap"
.Sh DESCRIPTION
These functions print a warning message to some destination.
.Fa format
is a printf style format specifying the message to print. The forms not ending in an
.Dq x
print the error string associated with
.Fa code
along with the message.
The
.Dq err
functions exit with exit status
.Fa eval
after printing the message.
.Pp
Applications that want to get the error message to report it to a user
or store it in a log want to use
.Fn krb5_get_error_message .
.Pp
The
.Fn krb5_set_warn_func
function sets the destination for warning messages to the specified
.Fa facility .
Messages logged with the
.Dq warn
functions have a log level of 1, while the
.Dq err
functions log with level 0.
.Pp
.Fn krb5_get_err_text
fetches the human readable strings describing the error-code.
.Pp
.Fn krb5_abort
and
.Nm krb5_abortx
behaves like
.Nm krb5_err
and
.Nm krb5_errx
but instead of exiting using the
.Xr exit 3
call,
.Xr abort 3
is used.
.Pp
.Fn krb5_free_error_string
frees the error string
.Fa str
returned by
.Fn krb5_get_error_string .
.Pp
.Fn krb5_clear_error_string
clears the error string from the
.Fa context .
.Pp
.Fn krb5_set_error_string
and
.Fn krb5_vset_error_string
sets an verbose error string in
.Fa context .
.Pp
.Fn krb5_get_error_string
fetches the error string from
.Fa context .
The error message in the context is consumed and must be freed using
.Fn krb5_free_error_string
by the caller.
See also
.Fn krb5_get_error_message ,
what is usually less verbose to use.
.Pp
.Fn krb5_have_error_string
returns
.Dv TRUE
if there is a verbose error message in the
.Fa context .
.Pp
.Fn krb5_get_error_message
fetches the error string from the context, or if there
is no customized error string in
.Fa context ,
uses
.Fa code
to return a error string.
In either case, the error message in the context is consumed and must
be freed using
.Fn krb5_free_error_string
by the caller.
.Pp
.Fn krb5_set_warn_dest
and
.Fn krb5_get_warn_dest
sets and get the log context that is used by
.Fn krb5_warn
and friends. By using this the application can control where the
output should go. For example, this is imperative to inetd servers
where logging status and error message will end up on the output
stream to the client.
.Sh EXAMPLES
Below is a simple example how to report error messages from the
Kerberos library in an application.
.Bd -literal
#include <krb5.h>
krb5_error_code
function (krb5_context context)
{
krb5_error_code ret;
ret = krb5_function (context, arg1, arg2);
if (ret) {
char *s = krb5_get_error_message(context, ret);
if (s == NULL)
errx(1, "kerberos error: %d (and out of memory)", ret);
application_logger("krb5_function failed: %s", s);
krb5_free_error_string(context, s);
return ret;
}
return 0;
}
.Ed
.Sh SEE ALSO
.Xr krb5 3 ,
.Xr krb5_openlog 3
|
