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