Update build for OpenSSL-0.9.8j upgrade.
[dragonfly.git] / secure / lib / libcrypto / man / err.3
CommitLineData
e257b235 1.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
28.\" double quote, and \*(R" will give a right double quote. \*(C+ will
29.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31.\" nothing in troff, for use with C<>.
32.tr \(*W-
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb 50.\"
e257b235
PA
51.\" Escape single quotes in literal strings from groff's Unicode transform.
52.ie \n(.g .ds Aq \(aq
53.el .ds Aq '
54.\"
8b0cefbb
JR
55.\" If the F register is turned on, we'll generate index entries on stderr for
56.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57.\" entries marked with X<> in POD. Of course, you'll have to process the
58.\" output yourself in some meaningful fashion.
e257b235 59.ie \nF \{\
8b0cefbb
JR
60. de IX
61. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 62..
8b0cefbb
JR
63. nr % 0
64. rr F
984263bc 65.\}
e257b235
PA
66.el \{\
67. de IX
68..
69.\}
aac4ff6f 70.\"
8b0cefbb
JR
71.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72.\" Fear. Run. Save yourself. No user-serviceable parts.
73. \" fudge factors for nroff and troff
984263bc 74.if n \{\
8b0cefbb
JR
75. ds #H 0
76. ds #V .8m
77. ds #F .3m
78. ds #[ \f1
79. ds #] \fP
984263bc
MD
80.\}
81.if t \{\
8b0cefbb
JR
82. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83. ds #V .6m
84. ds #F 0
85. ds #[ \&
86. ds #] \&
984263bc 87.\}
8b0cefbb 88. \" simple accents for nroff and troff
984263bc 89.if n \{\
8b0cefbb
JR
90. ds ' \&
91. ds ` \&
92. ds ^ \&
93. ds , \&
94. ds ~ ~
95. ds /
984263bc
MD
96.\}
97.if t \{\
8b0cefbb
JR
98. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 104.\}
8b0cefbb 105. \" troff and (daisy-wheel) nroff accents
984263bc
MD
106.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113.ds ae a\h'-(\w'a'u*4/10)'e
114.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 115. \" corrections for vroff
984263bc
MD
116.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 118. \" for low resolution devices (crt and lpr)
984263bc
MD
119.if \n(.H>23 .if \n(.V>19 \
120\{\
8b0cefbb
JR
121. ds : e
122. ds 8 ss
123. ds o a
124. ds d- d\h'-1'\(ga
125. ds D- D\h'-1'\(hy
126. ds th \o'bp'
127. ds Th \o'LP'
128. ds ae ae
129. ds Ae AE
984263bc
MD
130.\}
131.rm #[ #] #H #V #F C
8b0cefbb
JR
132.\" ========================================================================
133.\"
134.IX Title "err 3"
e257b235
PA
135.TH err 3 "2009-01-11" "0.9.8j" "OpenSSL"
136.\" For nroff, turn off justification. Always turn off hyphenation; it makes
137.\" way too many mistakes in technical documents.
138.if n .ad l
139.nh
984263bc
MD
140.SH "NAME"
141err \- error codes
142.SH "SYNOPSIS"
8b0cefbb 143.IX Header "SYNOPSIS"
984263bc
MD
144.Vb 1
145\& #include <openssl/err.h>
e257b235 146\&
984263bc
MD
147\& unsigned long ERR_get_error(void);
148\& unsigned long ERR_peek_error(void);
149\& unsigned long ERR_get_error_line(const char **file, int *line);
150\& unsigned long ERR_peek_error_line(const char **file, int *line);
151\& unsigned long ERR_get_error_line_data(const char **file, int *line,
152\& const char **data, int *flags);
153\& unsigned long ERR_peek_error_line_data(const char **file, int *line,
154\& const char **data, int *flags);
e257b235 155\&
984263bc
MD
156\& int ERR_GET_LIB(unsigned long e);
157\& int ERR_GET_FUNC(unsigned long e);
158\& int ERR_GET_REASON(unsigned long e);
e257b235 159\&
984263bc 160\& void ERR_clear_error(void);
e257b235 161\&
984263bc
MD
162\& char *ERR_error_string(unsigned long e, char *buf);
163\& const char *ERR_lib_error_string(unsigned long e);
164\& const char *ERR_func_error_string(unsigned long e);
165\& const char *ERR_reason_error_string(unsigned long e);
e257b235 166\&
984263bc
MD
167\& void ERR_print_errors(BIO *bp);
168\& void ERR_print_errors_fp(FILE *fp);
e257b235 169\&
984263bc
MD
170\& void ERR_load_crypto_strings(void);
171\& void ERR_free_strings(void);
e257b235 172\&
984263bc 173\& void ERR_remove_state(unsigned long pid);
e257b235 174\&
984263bc
MD
175\& void ERR_put_error(int lib, int func, int reason, const char *file,
176\& int line);
177\& void ERR_add_error_data(int num, ...);
e257b235 178\&
984263bc
MD
179\& void ERR_load_strings(int lib,ERR_STRING_DATA str[]);
180\& unsigned long ERR_PACK(int lib, int func, int reason);
181\& int ERR_get_next_error_library(void);
182.Ve
183.SH "DESCRIPTION"
8b0cefbb 184.IX Header "DESCRIPTION"
984263bc
MD
185When a call to the OpenSSL library fails, this is usually signalled
186by the return value, and an error code is stored in an error queue
187associated with the current thread. The \fBerr\fR library provides
188functions to obtain these error codes and textual error messages.
189.PP
8b0cefbb 190The \fIERR_get_error\fR\|(3) manpage describes how to
984263bc
MD
191access error codes.
192.PP
193Error codes contain information about where the error occurred, and
8b0cefbb 194what went wrong. \s-1\fIERR_GET_LIB\s0\fR\|(3) describes how to
984263bc 195extract this information. A method to obtain human-readable error
8b0cefbb 196messages is described in \fIERR_error_string\fR\|(3).
984263bc 197.PP
8b0cefbb 198\&\fIERR_clear_error\fR\|(3) can be used to clear the
984263bc
MD
199error queue.
200.PP
8b0cefbb 201Note that \fIERR_remove_state\fR\|(3) should be used to
984263bc
MD
202avoid memory leaks when threads are terminated.
203.SH "ADDING NEW ERROR CODES TO OPENSSL"
8b0cefbb
JR
204.IX Header "ADDING NEW ERROR CODES TO OPENSSL"
205See \fIERR_put_error\fR\|(3) if you want to record error codes in the
984263bc
MD
206OpenSSL error system from within your application.
207.PP
208The remainder of this section is of interest only if you want to add
209new error codes to OpenSSL or add error codes from external libraries.
210.Sh "Reporting errors"
8b0cefbb 211.IX Subsection "Reporting errors"
984263bc
MD
212Each sub-library has a specific macro \fIXXXerr()\fR that is used to report
213errors. Its first argument is a function code \fB\s-1XXX_F_\s0...\fR, the second
214argument is a reason code \fB\s-1XXX_R_\s0...\fR. Function codes are derived
215from the function names; reason codes consist of textual error
216descriptions. For example, the function \fIssl23_read()\fR reports a
8b0cefbb 217\&\*(L"handshake failure\*(R" as follows:
984263bc
MD
218.PP
219.Vb 1
220\& SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);
221.Ve
8b0cefbb 222.PP
984263bc
MD
223Function and reason codes should consist of upper case characters,
224numbers and underscores only. The error file generation script translates
225function codes into function names by looking in the header files
226for an appropriate function name, if none is found it just uses
227the capitalized form such as \*(L"\s-1SSL23_READ\s0\*(R" in the above example.
228.PP
8b0cefbb 229The trailing section of a reason code (after the \*(L"_R_\*(R") is translated
984263bc
MD
230into lower case and underscores changed to spaces.
231.PP
232When you are using new function or reason codes, run \fBmake errors\fR.
233The necessary \fB#define\fRs will then automatically be added to the
e257b235 234sub-library's header file.
984263bc
MD
235.PP
236Although a library will normally report errors using its own specific
237XXXerr macro, another library's macro can be used. This is normally
238only done when a library wants to include \s-1ASN1\s0 code which must use
239the \fIASN1err()\fR macro.
240.Sh "Adding new libraries"
8b0cefbb 241.IX Subsection "Adding new libraries"
984263bc 242When adding a new sub-library to OpenSSL, assign it a library number
8b0cefbb 243\&\fB\s-1ERR_LIB_XXX\s0\fR, define a macro \fIXXXerr()\fR (both in \fBerr.h\fR), add its
984263bc 244name to \fBERR_str_libraries[]\fR (in \fBcrypto/err/err.c\fR), and add
8b0cefbb 245\&\f(CW\*(C`ERR_load_XXX_strings()\*(C'\fR to the \fIERR_load_crypto_strings()\fR function
984263bc
MD
246(in \fBcrypto/err/err_all.c\fR). Finally, add an entry
247.PP
248.Vb 1
249\& L XXX xxx.h xxx_err.c
250.Ve
8b0cefbb 251.PP
984263bc
MD
252to \fBcrypto/err/openssl.ec\fR, and add \fBxxx_err.c\fR to the Makefile.
253Running \fBmake errors\fR will then generate a file \fBxxx_err.c\fR, and
254add all error codes used in the library to \fBxxx.h\fR.
255.PP
256Additionally the library include file must have a certain form.
257Typically it will initially look like this:
258.PP
259.Vb 2
260\& #ifndef HEADER_XXX_H
261\& #define HEADER_XXX_H
e257b235
PA
262\&
263\& #ifdef _\|_cplusplus
984263bc
MD
264\& extern "C" {
265\& #endif
e257b235 266\&
984263bc 267\& /* Include files */
e257b235 268\&
984263bc
MD
269\& #include <openssl/bio.h>
270\& #include <openssl/x509.h>
e257b235 271\&
984263bc 272\& /* Macros, structures and function prototypes */
e257b235
PA
273\&
274\&
984263bc
MD
275\& /* BEGIN ERROR CODES */
276.Ve
8b0cefbb 277.PP
984263bc
MD
278The \fB\s-1BEGIN\s0 \s-1ERROR\s0 \s-1CODES\s0\fR sequence is used by the error code
279generation script as the point to place new error codes, any text
280after this point will be overwritten when \fBmake errors\fR is run.
281The closing #endif etc will be automatically added by the script.
282.PP
283The generated C error code file \fBxxx_err.c\fR will load the header
284files \fBstdio.h\fR, \fBopenssl/err.h\fR and \fBopenssl/xxx.h\fR so the
285header file must load any additional header files containing any
286definitions it uses.
287.SH "USING ERROR CODES IN EXTERNAL LIBRARIES"
8b0cefbb 288.IX Header "USING ERROR CODES IN EXTERNAL LIBRARIES"
984263bc
MD
289It is also possible to use OpenSSL's error code scheme in external
290libraries. The library needs to load its own codes and call the OpenSSL
291error code insertion script \fBmkerr.pl\fR explicitly to add codes to
292the header file and generate the C error code file. This will normally
8b0cefbb 293be done if the external library needs to generate new \s-1ASN1\s0 structures
984263bc
MD
294but it can also be used to add more general purpose error code handling.
295.PP
8b0cefbb 296\&\s-1TBA\s0 more details
984263bc 297.SH "INTERNALS"
8b0cefbb
JR
298.IX Header "INTERNALS"
299The error queues are stored in a hash table with one \fB\s-1ERR_STATE\s0\fR
984263bc 300entry for each pid. \fIERR_get_state()\fR returns the current thread's
8b0cefbb 301\&\fB\s-1ERR_STATE\s0\fR. An \fB\s-1ERR_STATE\s0\fR can hold up to \fB\s-1ERR_NUM_ERRORS\s0\fR error
984263bc
MD
302codes. When more error codes are added, the old ones are overwritten,
303on the assumption that the most recent errors are most important.
304.PP
305Error strings are also stored in hash table. The hash tables can
8b0cefbb
JR
306be obtained by calling ERR_get_err_state_table(void) and
307ERR_get_string_table(void) respectively.
984263bc 308.SH "SEE ALSO"
74dab6c2 309.IX Header "SEE ALSO"
8b0cefbb
JR
310\&\fICRYPTO_set_id_callback\fR\|(3),
311\&\fICRYPTO_set_locking_callback\fR\|(3),
312\&\fIERR_get_error\fR\|(3),
313\&\s-1\fIERR_GET_LIB\s0\fR\|(3),
314\&\fIERR_clear_error\fR\|(3),
315\&\fIERR_error_string\fR\|(3),
316\&\fIERR_print_errors\fR\|(3),
317\&\fIERR_load_crypto_strings\fR\|(3),
318\&\fIERR_remove_state\fR\|(3),
319\&\fIERR_put_error\fR\|(3),
320\&\fIERR_load_strings\fR\|(3),
321\&\fISSL_get_error\fR\|(3)