| err.3 (206048) | err.3 (215698) |
|---|---|
| 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37 | 1.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) |
| 2.\" 3.\" Standard preamble: 4.\" ======================================================================== | 2.\" 3.\" Standard preamble: 4.\" ======================================================================== |
| 5.de Sh \" Subsection heading 6.br 7.if t .Sp 8.ne 5 9.PP 10\fB\\$1\fR 11.PP 12.. | |
| 13.de Sp \" Vertical space (when we can't use .PP) 14.if t .sp .5v 15.if n .sp 16.. 17.de Vb \" Begin verbatim text 18.ft CW 19.nf 20.ne \\$1 21.. 22.de Ve \" End verbatim text 23.ft R 24.fi 25.. 26.\" Set up some character translations and predefined strings. \*(-- will 27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | 5.de Sp \" Vertical space (when we can't use .PP) 6.if t .sp .5v 7.if n .sp 8.. 9.de Vb \" Begin verbatim text 10.ft CW 11.nf 12.ne \\$1 13.. 14.de Ve \" End verbatim text 15.ft R 16.fi 17.. 18.\" Set up some character translations and predefined strings. \*(-- will 19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| 28.\" double quote, and \*(R" will give a right double quote. | will give a 29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to 30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' 31.\" expand to `' in nroff, nothing in troff, for use with C<>. 32.tr \(*W-|\(bv\*(Tr | 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- |
| 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 34.ie n \{\ 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' "" 43'br\} 44.el\{\ 45. ds -- \|\(em\| 46. ds PI \(*p 47. ds L" `` 48. ds R" '' 49'br\} 50.\" | 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 26.ie n \{\ 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' "" 35'br\} 36.el\{\ 37. ds -- \|\(em\| 38. ds PI \(*p 39. ds L" `` 40. ds R" '' 41'br\} 42.\" |
| 43.\" Escape single quotes in literal strings from groff's Unicode transform. 44.ie \n(.g .ds Aq \(aq 45.el .ds Aq ' 46.\" |
|
| 51.\" If the F register is turned on, we'll generate index entries on stderr for | 47.\" If the F register is turned on, we'll generate index entries on stderr for |
| 52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 53.\" entries marked with X<> in POD. Of course, you'll have to process the 54.\" output yourself in some meaningful fashion. | 49.\" entries marked with X<> in POD. Of course, you'll have to process the 50.\" output yourself in some meaningful fashion. |
| 55.if \nF \{\ | 51.ie \nF \{\ |
| 56. de IX 57. tm Index:\\$1\t\\n%\t"\\$2" 58.. 59. nr % 0 60. rr F 61.\} | 52. de IX 53. tm Index:\\$1\t\\n%\t"\\$2" 54.. 55. nr % 0 56. rr F 57.\} |
| 58.el \{\ 59. de IX 60.. 61.\} |
|
| 62.\" | 62.\" |
| 63.\" For nroff, turn off justification. Always turn off hyphenation; it makes 64.\" way too many mistakes in technical documents. 65.hy 0 66.if n .na 67.\" | |
| 68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 69.\" Fear. Run. Save yourself. No user-serviceable parts. 70. \" fudge factors for nroff and troff 71.if n \{\ 72. ds #H 0 73. ds #V .8m 74. ds #F .3m 75. ds #[ \f1 --- 48 unchanged lines hidden (view full) --- 124. ds Th \o'LP' 125. ds ae ae 126. ds Ae AE 127.\} 128.rm #[ #] #H #V #F C 129.\" ======================================================================== 130.\" 131.IX Title "err 3" | 63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 64.\" Fear. Run. Save yourself. No user-serviceable parts. 65. \" fudge factors for nroff and troff 66.if n \{\ 67. ds #H 0 68. ds #V .8m 69. ds #F .3m 70. ds #[ \f1 --- 48 unchanged lines hidden (view full) --- 119. ds Th \o'LP' 120. ds ae ae 121. ds Ae AE 122.\} 123.rm #[ #] #H #V #F C 124.\" ======================================================================== 125.\" 126.IX Title "err 3" |
| 132.TH err 3 "2010-03-24" "0.9.8n" "OpenSSL" | 127.TH err 3 "2010-11-16" "0.9.8p" "OpenSSL" 128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 129.\" way too many mistakes in technical documents. 130.if n .ad l 131.nh |
| 133.SH "NAME" 134err \- error codes 135.SH "SYNOPSIS" 136.IX Header "SYNOPSIS" 137.Vb 1 138\& #include <openssl/err.h> | 132.SH "NAME" 133err \- error codes 134.SH "SYNOPSIS" 135.IX Header "SYNOPSIS" 136.Vb 1 137\& #include <openssl/err.h> |
| 139.Ve 140.PP 141.Vb 8 | 138\& |
| 142\& unsigned long ERR_get_error(void); 143\& unsigned long ERR_peek_error(void); 144\& unsigned long ERR_get_error_line(const char **file, int *line); 145\& unsigned long ERR_peek_error_line(const char **file, int *line); 146\& unsigned long ERR_get_error_line_data(const char **file, int *line, 147\& const char **data, int *flags); 148\& unsigned long ERR_peek_error_line_data(const char **file, int *line, 149\& const char **data, int *flags); | 139\& unsigned long ERR_get_error(void); 140\& unsigned long ERR_peek_error(void); 141\& unsigned long ERR_get_error_line(const char **file, int *line); 142\& unsigned long ERR_peek_error_line(const char **file, int *line); 143\& unsigned long ERR_get_error_line_data(const char **file, int *line, 144\& const char **data, int *flags); 145\& unsigned long ERR_peek_error_line_data(const char **file, int *line, 146\& const char **data, int *flags); |
| 150.Ve 151.PP 152.Vb 3 | 147\& |
| 153\& int ERR_GET_LIB(unsigned long e); 154\& int ERR_GET_FUNC(unsigned long e); 155\& int ERR_GET_REASON(unsigned long e); | 148\& int ERR_GET_LIB(unsigned long e); 149\& int ERR_GET_FUNC(unsigned long e); 150\& int ERR_GET_REASON(unsigned long e); |
| 156.Ve 157.PP 158.Vb 1 | 151\& |
| 159\& void ERR_clear_error(void); | 152\& void ERR_clear_error(void); |
| 160.Ve 161.PP 162.Vb 4 | 153\& |
| 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); | 154\& char *ERR_error_string(unsigned long e, char *buf); 155\& const char *ERR_lib_error_string(unsigned long e); 156\& const char *ERR_func_error_string(unsigned long e); 157\& const char *ERR_reason_error_string(unsigned long e); |
| 167.Ve 168.PP 169.Vb 2 | 158\& |
| 170\& void ERR_print_errors(BIO *bp); 171\& void ERR_print_errors_fp(FILE *fp); | 159\& void ERR_print_errors(BIO *bp); 160\& void ERR_print_errors_fp(FILE *fp); |
| 172.Ve 173.PP 174.Vb 2 | 161\& |
| 175\& void ERR_load_crypto_strings(void); 176\& void ERR_free_strings(void); | 162\& void ERR_load_crypto_strings(void); 163\& void ERR_free_strings(void); |
| 177.Ve 178.PP 179.Vb 1 | 164\& |
| 180\& void ERR_remove_state(unsigned long pid); | 165\& void ERR_remove_state(unsigned long pid); |
| 181.Ve 182.PP 183.Vb 3 | 166\& |
| 184\& void ERR_put_error(int lib, int func, int reason, const char *file, 185\& int line); 186\& void ERR_add_error_data(int num, ...); | 167\& void ERR_put_error(int lib, int func, int reason, const char *file, 168\& int line); 169\& void ERR_add_error_data(int num, ...); |
| 187.Ve 188.PP 189.Vb 3 | 170\& |
| 190\& void ERR_load_strings(int lib,ERR_STRING_DATA str[]); 191\& unsigned long ERR_PACK(int lib, int func, int reason); 192\& int ERR_get_next_error_library(void); 193.Ve 194.SH "DESCRIPTION" 195.IX Header "DESCRIPTION" 196When a call to the OpenSSL library fails, this is usually signalled 197by the return value, and an error code is stored in an error queue --- 15 unchanged lines hidden (view full) --- 213avoid memory leaks when threads are terminated. 214.SH "ADDING NEW ERROR CODES TO OPENSSL" 215.IX Header "ADDING NEW ERROR CODES TO OPENSSL" 216See \fIERR_put_error\fR\|(3) if you want to record error codes in the 217OpenSSL error system from within your application. 218.PP 219The remainder of this section is of interest only if you want to add 220new error codes to OpenSSL or add error codes from external libraries. | 171\& void ERR_load_strings(int lib,ERR_STRING_DATA str[]); 172\& unsigned long ERR_PACK(int lib, int func, int reason); 173\& int ERR_get_next_error_library(void); 174.Ve 175.SH "DESCRIPTION" 176.IX Header "DESCRIPTION" 177When a call to the OpenSSL library fails, this is usually signalled 178by the return value, and an error code is stored in an error queue --- 15 unchanged lines hidden (view full) --- 194avoid memory leaks when threads are terminated. 195.SH "ADDING NEW ERROR CODES TO OPENSSL" 196.IX Header "ADDING NEW ERROR CODES TO OPENSSL" 197See \fIERR_put_error\fR\|(3) if you want to record error codes in the 198OpenSSL error system from within your application. 199.PP 200The remainder of this section is of interest only if you want to add 201new error codes to OpenSSL or add error codes from external libraries. |
| 221.Sh "Reporting errors" | 202.SS "Reporting errors" |
| 222.IX Subsection "Reporting errors" 223Each sub-library has a specific macro \fIXXXerr()\fR that is used to report 224errors. Its first argument is a function code \fB\s-1XXX_F_\s0...\fR, the second 225argument is a reason code \fB\s-1XXX_R_\s0...\fR. Function codes are derived 226from the function names; reason codes consist of textual error 227descriptions. For example, the function \fIssl23_read()\fR reports a 228\&\*(L"handshake failure\*(R" as follows: 229.PP --- 7 unchanged lines hidden (view full) --- 237for an appropriate function name, if none is found it just uses 238the capitalized form such as \*(L"\s-1SSL23_READ\s0\*(R" in the above example. 239.PP 240The trailing section of a reason code (after the \*(L"_R_\*(R") is translated 241into lower case and underscores changed to spaces. 242.PP 243When you are using new function or reason codes, run \fBmake errors\fR. 244The necessary \fB#define\fRs will then automatically be added to the | 203.IX Subsection "Reporting errors" 204Each sub-library has a specific macro \fIXXXerr()\fR that is used to report 205errors. Its first argument is a function code \fB\s-1XXX_F_\s0...\fR, the second 206argument is a reason code \fB\s-1XXX_R_\s0...\fR. Function codes are derived 207from the function names; reason codes consist of textual error 208descriptions. For example, the function \fIssl23_read()\fR reports a 209\&\*(L"handshake failure\*(R" as follows: 210.PP --- 7 unchanged lines hidden (view full) --- 218for an appropriate function name, if none is found it just uses 219the capitalized form such as \*(L"\s-1SSL23_READ\s0\*(R" in the above example. 220.PP 221The trailing section of a reason code (after the \*(L"_R_\*(R") is translated 222into lower case and underscores changed to spaces. 223.PP 224When you are using new function or reason codes, run \fBmake errors\fR. 225The necessary \fB#define\fRs will then automatically be added to the |
| 245sub\-library's header file. | 226sub-library's header file. |
| 246.PP 247Although a library will normally report errors using its own specific 248XXXerr macro, another library's macro can be used. This is normally 249only done when a library wants to include \s-1ASN1\s0 code which must use 250the \fIASN1err()\fR macro. | 227.PP 228Although a library will normally report errors using its own specific 229XXXerr macro, another library's macro can be used. This is normally 230only done when a library wants to include \s-1ASN1\s0 code which must use 231the \fIASN1err()\fR macro. |
| 251.Sh "Adding new libraries" | 232.SS "Adding new libraries" |
| 252.IX Subsection "Adding new libraries" 253When adding a new sub-library to OpenSSL, assign it a library number 254\&\fB\s-1ERR_LIB_XXX\s0\fR, define a macro \fIXXXerr()\fR (both in \fBerr.h\fR), add its 255name to \fBERR_str_libraries[]\fR (in \fBcrypto/err/err.c\fR), and add 256\&\f(CW\*(C`ERR_load_XXX_strings()\*(C'\fR to the \fIERR_load_crypto_strings()\fR function 257(in \fBcrypto/err/err_all.c\fR). Finally, add an entry 258.PP 259.Vb 1 --- 5 unchanged lines hidden (view full) --- 265add all error codes used in the library to \fBxxx.h\fR. 266.PP 267Additionally the library include file must have a certain form. 268Typically it will initially look like this: 269.PP 270.Vb 2 271\& #ifndef HEADER_XXX_H 272\& #define HEADER_XXX_H | 233.IX Subsection "Adding new libraries" 234When adding a new sub-library to OpenSSL, assign it a library number 235\&\fB\s-1ERR_LIB_XXX\s0\fR, define a macro \fIXXXerr()\fR (both in \fBerr.h\fR), add its 236name to \fBERR_str_libraries[]\fR (in \fBcrypto/err/err.c\fR), and add 237\&\f(CW\*(C`ERR_load_XXX_strings()\*(C'\fR to the \fIERR_load_crypto_strings()\fR function 238(in \fBcrypto/err/err_all.c\fR). Finally, add an entry 239.PP 240.Vb 1 --- 5 unchanged lines hidden (view full) --- 246add all error codes used in the library to \fBxxx.h\fR. 247.PP 248Additionally the library include file must have a certain form. 249Typically it will initially look like this: 250.PP 251.Vb 2 252\& #ifndef HEADER_XXX_H 253\& #define HEADER_XXX_H |
| 273.Ve 274.PP 275.Vb 3 276\& #ifdef __cplusplus | 254\& 255\& #ifdef _\|_cplusplus |
| 277\& extern "C" { 278\& #endif | 256\& extern "C" { 257\& #endif |
| 279.Ve 280.PP 281.Vb 1 | 258\& |
| 282\& /* Include files */ | 259\& /* Include files */ |
| 283.Ve 284.PP 285.Vb 2 | 260\& |
| 286\& #include <openssl/bio.h> 287\& #include <openssl/x509.h> | 261\& #include <openssl/bio.h> 262\& #include <openssl/x509.h> |
| 288.Ve 289.PP 290.Vb 1 | 263\& |
| 291\& /* Macros, structures and function prototypes */ | 264\& /* Macros, structures and function prototypes */ |
| 292.Ve 293.PP 294.Vb 1 | 265\& 266\& |
| 295\& /* BEGIN ERROR CODES */ 296.Ve 297.PP 298The \fB\s-1BEGIN\s0 \s-1ERROR\s0 \s-1CODES\s0\fR sequence is used by the error code 299generation script as the point to place new error codes, any text 300after this point will be overwritten when \fBmake errors\fR is run. 301The closing #endif etc will be automatically added by the script. 302.PP --- 39 unchanged lines hidden --- | 267\& /* BEGIN ERROR CODES */ 268.Ve 269.PP 270The \fB\s-1BEGIN\s0 \s-1ERROR\s0 \s-1CODES\s0\fR sequence is used by the error code 271generation script as the point to place new error codes, any text 272after this point will be overwritten when \fBmake errors\fR is run. 273The closing #endif etc will be automatically added by the script. 274.PP --- 39 unchanged lines hidden --- |