Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / ERR_error_string.3
1 .rn '' }`
2 ''' $RCSfile$$Revision$$Date$
3 '''
4 ''' $Log$
5 '''
6 .de Sh
7 .br
8 .if t .Sp
9 .ne 5
10 .PP
11 \fB\\$1\fR
12 .PP
13 ..
14 .de Sp
15 .if t .sp .5v
16 .if n .sp
17 ..
18 .de Ip
19 .br
20 .ie \\n(.$>=3 .ne \\$3
21 .el .ne 3
22 .IP "\\$1" \\$2
23 ..
24 .de Vb
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve
30 .ft R
31
32 .fi
33 ..
34 '''
35 '''
36 '''     Set up \*(-- to give an unbreakable dash;
37 '''     string Tr holds user defined translation string.
38 '''     Bell System Logo is used as a dummy character.
39 '''
40 .tr \(*W-|\(bv\*(Tr
41 .ie n \{\
42 .ds -- \(*W-
43 .ds PI pi
44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46 .ds L" ""
47 .ds R" ""
48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
50 '''   such as .IP and .SH, which do another additional levels of
51 '''   double-quote interpretation
52 .ds M" """
53 .ds S" """
54 .ds N" """""
55 .ds T" """""
56 .ds L' '
57 .ds R' '
58 .ds M' '
59 .ds S' '
60 .ds N' '
61 .ds T' '
62 'br\}
63 .el\{\
64 .ds -- \(em\|
65 .tr \*(Tr
66 .ds L" ``
67 .ds R" ''
68 .ds M" ``
69 .ds S" ''
70 .ds N" ``
71 .ds T" ''
72 .ds L' `
73 .ds R' '
74 .ds M' `
75 .ds S' '
76 .ds N' `
77 .ds T' '
78 .ds PI \(*p
79 'br\}
80 .\"     If the F register is turned on, we'll generate
81 .\"     index entries out stderr for the following things:
82 .\"             TH      Title 
83 .\"             SH      Header
84 .\"             Sh      Subsection 
85 .\"             Ip      Item
86 .\"             X<>     Xref  (embedded
87 .\"     Of course, you have to process the output yourself
88 .\"     in some meaninful fashion.
89 .if \nF \{
90 .de IX
91 .tm Index:\\$1\t\\n%\t"\\$2"
92 ..
93 .nr % 0
94 .rr F
95 .\}
96 .TH ERR_error_string 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97 .UC
98 .if n .hy 0
99 .if n .na
100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101 .de CQ          \" put $1 in typewriter font
102 .ft CW
103 'if n "\c
104 'if t \\&\\$1\c
105 'if n \\&\\$1\c
106 'if n \&"
107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108 '.ft R
109 ..
110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111 .       \" AM - accent mark definitions
112 .bd B 3
113 .       \" fudge factors for nroff and troff
114 .if n \{\
115 .       ds #H 0
116 .       ds #V .8m
117 .       ds #F .3m
118 .       ds #[ \f1
119 .       ds #] \fP
120 .\}
121 .if t \{\
122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123 .       ds #V .6m
124 .       ds #F 0
125 .       ds #[ \&
126 .       ds #] \&
127 .\}
128 .       \" simple accents for nroff and troff
129 .if n \{\
130 .       ds ' \&
131 .       ds ` \&
132 .       ds ^ \&
133 .       ds , \&
134 .       ds ~ ~
135 .       ds ? ?
136 .       ds ! !
137 .       ds /
138 .       ds q
139 .\}
140 .if t \{\
141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
150 .\}
151 .       \" troff and (daisy-wheel) nroff accents
152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163 .ds ae a\h'-(\w'a'u*4/10)'e
164 .ds Ae A\h'-(\w'A'u*4/10)'E
165 .ds oe o\h'-(\w'o'u*4/10)'e
166 .ds Oe O\h'-(\w'O'u*4/10)'E
167 .       \" corrections for vroff
168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
170 .       \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
172 \{\
173 .       ds : e
174 .       ds 8 ss
175 .       ds v \h'-1'\o'\(aa\(ga'
176 .       ds _ \h'-1'^
177 .       ds . \h'-1'.
178 .       ds 3 3
179 .       ds o a
180 .       ds d- d\h'-1'\(ga
181 .       ds D- D\h'-1'\(hy
182 .       ds th \o'bp'
183 .       ds Th \o'LP'
184 .       ds ae ae
185 .       ds Ae AE
186 .       ds oe oe
187 .       ds Oe OE
188 .\}
189 .rm #[ #] #H #V #F C
190 .SH "NAME"
191 ERR_error_string, ERR_error_string_n, ERR_lib_error_string,
192 ERR_func_error_string, ERR_reason_error_string \- obtain human-readable
193 error message
194 .SH "SYNOPSIS"
195 .PP
196 .Vb 1
197 \& #include <openssl/err.h>
198 .Ve
199 .Vb 2
200 \& char *ERR_error_string(unsigned long e, char *buf);
201 \& char *ERR_error_string_n(unsigned long e, char *buf, size_t len);
202 .Ve
203 .Vb 3
204 \& const char *ERR_lib_error_string(unsigned long e);
205 \& const char *ERR_func_error_string(unsigned long e);
206 \& const char *ERR_reason_error_string(unsigned long e);
207 .Ve
208 .SH "DESCRIPTION"
209 \fIERR_error_string()\fR generates a human-readable string representing the
210 error code \fIe\fR, and places it at \fIbuf\fR. \fIbuf\fR must be at least 120
211 bytes long. If \fIbuf\fR is \fBNULL\fR, the error string is placed in a
212 static buffer.
213 \fIERR_error_string_n()\fR is a variant of \fIERR_error_string()\fR that writes
214 at most \fIlen\fR characters (including the terminating 0)
215 and truncates the string if necessary.
216 For \fIERR_error_string_n()\fR, \fIbuf\fR may not be \fBNULL\fR.
217 .PP
218 The string will have the following format:
219 .PP
220 .Vb 1
221 \& error:[error code]:[library name]:[function name]:[reason string]
222 .Ve
223 \fIerror code\fR is an 8 digit hexadecimal number, \fIlibrary name\fR,
224 \fIfunction name\fR and \fIreason string\fR are ASCII text.
225 .PP
226 \fIERR_lib_error_string()\fR, \fIERR_func_error_string()\fR and
227 \fIERR_reason_error_string()\fR return the library name, function
228 name and reason string respectively.
229 .PP
230 The OpenSSL error strings should be loaded by calling
231 ERR_load_crypto_strings(3) or, for SSL
232 applications, SSL_load_error_strings(3)
233 first.
234 If there is no text string registered for the given error code,
235 the error string will contain the numeric code.
236 .PP
237 ERR_print_errors(3) can be used to print
238 all error codes currently in the queue.
239 .SH "RETURN VALUES"
240 \fIERR_error_string()\fR returns a pointer to a static buffer containing the
241 string if \fIbuf\fR \fB== NULL\fR, \fIbuf\fR otherwise.
242 .PP
243 \fIERR_lib_error_string()\fR, \fIERR_func_error_string()\fR and
244 \fIERR_reason_error_string()\fR return the strings, and \fBNULL\fR if
245 none is registered for the error code.
246 .SH "SEE ALSO"
247 err(3), ERR_get_error(3),
248 ERR_load_crypto_strings(3),
249 SSL_load_error_strings(3)
250 ERR_print_errors(3)
251 .SH "HISTORY"
252 \fIERR_error_string()\fR is available in all versions of SSLeay and OpenSSL.
253 \fIERR_error_string_n()\fR was added in OpenSSL 0.9.6.
254
255 .rn }` ''
256 .IX Title "ERR_error_string 3"
257 .IX Name "ERR_error_string, ERR_error_string_n, ERR_lib_error_string,
258 ERR_func_error_string, ERR_reason_error_string - obtain human-readable
259 error message"
260
261 .IX Header "NAME"
262
263 .IX Header "SYNOPSIS"
264
265 .IX Header "DESCRIPTION"
266
267 .IX Header "RETURN VALUES"
268
269 .IX Header "SEE ALSO"
270
271 .IX Header "HISTORY"
272