mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2024-12-15 06:01:37 +08:00
Code Issues Packages Projects Releases Wiki Activity
62c3fed0cd
openssl/doc/man3/ERR_put_error.pod

100 lines
3.3 KiB
Plaintext
Raw Normal View History

Document ERR library.
2000-02-01 09:37:00 +08:00
=pod
=head1 NAME
ERR: Implement the macros ERR_raise() and ERR_raise_data() and use them The ERR_raise() macro uses a trick in C. The following is permitted: #include <stdio.h> void first(void) { printf("Hello! "); } void foo(const char *bar) { printf("%s", bar); } int main() { /* This */ (first(),foo)("cookie"); } ERR_raise_data() can be used to implement FUNCerr() as well, which takes away the need for the special function ERR_put_func_error(). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:13:52 +08:00
ERR_raise, ERR_raise_data,
ERR: Remove ERR_put_func_error() and reimplement ERR_put_error() as a macro Also, deprecate ERR_put_error() Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:25:56 +08:00
ERR_put_error, ERR_add_error_data, ERR_add_error_vdata
- record an error
Document ERR library.
2000-02-01 09:37:00 +08:00
=head1 SYNOPSIS
#include <openssl/err.h>
ERR: Implement the macros ERR_raise() and ERR_raise_data() and use them The ERR_raise() macro uses a trick in C. The following is permitted: #include <stdio.h> void first(void) { printf("Hello! "); } void foo(const char *bar) { printf("%s", bar); } int main() { /* This */ (first(),foo)("cookie"); } ERR_raise_data() can be used to implement FUNCerr() as well, which takes away the need for the special function ERR_put_func_error(). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:13:52 +08:00
void ERR_raise(int lib, int reason);
void ERR_raise_data(int lib, int reason, const char *fmt, ...);
Document ERR library.
2000-02-01 09:37:00 +08:00
void ERR_add_error_data(int num, ...);
ERR_put_error.pod: fix the name of function ERR_add_error_vdata() Reviewed-by: Rich Salz <rsalz@openssl.org> Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/1956)
2017-01-20 07:43:48 +08:00
void ERR_add_error_vdata(int num, va_list arg);
Document ERR library.
2000-02-01 09:37:00 +08:00
ERR: Remove ERR_put_func_error() and reimplement ERR_put_error() as a macro Also, deprecate ERR_put_error() Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:25:56 +08:00
Deprecated since OpenSSL 3.0:
void ERR_put_error(int lib, int func, int reason, const char *file, int line);
Document ERR library.
2000-02-01 09:37:00 +08:00
=head1 DESCRIPTION
ERR: Implement the macros ERR_raise() and ERR_raise_data() and use them The ERR_raise() macro uses a trick in C. The following is permitted: #include <stdio.h> void first(void) { printf("Hello! "); } void foo(const char *bar) { printf("%s", bar); } int main() { /* This */ (first(),foo)("cookie"); } ERR_raise_data() can be used to implement FUNCerr() as well, which takes away the need for the special function ERR_put_func_error(). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:13:52 +08:00
ERR_raise() adds a new error to the thread's error queue. The
Fix some typos Reported-by: misspell-fixer <https://github.com/vlajos/misspell-fixer> CLA: trivial Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10544)
2019-12-01 07:18:47 +08:00
error occurred in the library B<lib> for the reason given by the
ERR: Implement the macros ERR_raise() and ERR_raise_data() and use them The ERR_raise() macro uses a trick in C. The following is permitted: #include <stdio.h> void first(void) { printf("Hello! "); } void foo(const char *bar) { printf("%s", bar); } int main() { /* This */ (first(),foo)("cookie"); } ERR_raise_data() can be used to implement FUNCerr() as well, which takes away the need for the special function ERR_put_func_error(). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:13:52 +08:00
B<reason> code. Furthermore, the name of the file, the line, and name
Fix some typos Reported-by: misspell-fixer <https://github.com/vlajos/misspell-fixer> CLA: trivial Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10544)
2019-12-01 07:18:47 +08:00
of the function where the error occurred is saved with the error
ERR: Implement the macros ERR_raise() and ERR_raise_data() and use them The ERR_raise() macro uses a trick in C. The following is permitted: #include <stdio.h> void first(void) { printf("Hello! "); } void foo(const char *bar) { printf("%s", bar); } int main() { /* This */ (first(),foo)("cookie"); } ERR_raise_data() can be used to implement FUNCerr() as well, which takes away the need for the special function ERR_put_func_error(). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:13:52 +08:00
record.
ERR_raise_data() does the same thing as ERR_raise(), but also lets the
caller specify additional information as a format string B<fmt> and an
arbitrary number of values, which are processed with L<BIO_snprintf(3)>.
Document ERR library.
2000-02-01 09:37:00 +08:00
ERR_put_error() adds an error code to the thread's error queue. It
signals that the error of reason code B<reason> occurred in function
B<func> of library B<lib>, in line number B<line> of B<file>.
This function is usually called by a macro.
ERR_add_error_data() associates the concatenation of its B<num> string
arguments with the error code added last.
More doc cleanup Add missing entries to NAME section Add SYNOPSIS lines, remove old NAME entries Update find-doc-nits; better regexp's for parsing SYNOPSIS sections. Rename a couple of files to have an API name. Remove RSA_private_decrypt; it was duplicate content Update for recent doc additions Reviewed-by: Matt Caswell <matt@openssl.org>
2016-06-21 19:03:34 +08:00
ERR_add_error_vdata() is similar except the argument is a B<va_list>.
Change ERR_add_error_[v]data to append The "add error data" functions now append to the current error. Add a test for this. Cleanup some of the ERR_put functions. In the FIPS module, always append "(in the FIPS module)" to any errors. Reviewed-by: Bernd Edlinger <bernd.edlinger@hotmail.de> Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/9181)
2019-06-19 00:06:17 +08:00
Multiple calls to these functions append to the current top of the error queue.
Document ERR library.
2000-02-01 09:37:00 +08:00
Fix L<> content in manpages L<foo|foo> is sub-optimal If the xref is the same as the title, which is what we do, then you only need L<foo>. This fixes all 1457 occurrences in 349 files. Approximately. (And pod used to need both.) Reviewed-by: Richard Levitte <levitte@openssl.org>
2015-08-18 03:21:33 +08:00
L<ERR_load_strings(3)> can be used to register
Document ERR library.
2000-02-01 09:37:00 +08:00
error strings so that the application can a generate human-readable
error messages for the error code.
Clean up "generic" intro pod files. Files like dh.pod, etc., mostly duplicated the API-specific pod files. Removed the duplicated content; that often mean the whole file could be removed. Some of the content about internals got moved into README files in the source tree. Some content (e.g., err.pod) got moved into other pod pages. Annotate generic pages, remove dup NAME Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-06-10 04:39:19 +08:00
=head2 Reporting errors
ERR: Remove ERR_put_func_error() and reimplement ERR_put_error() as a macro Also, deprecate ERR_put_error() Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:25:56 +08:00
=for comment TODO(3.0) should this be internal documentation?
Clean up "generic" intro pod files. Files like dh.pod, etc., mostly duplicated the API-specific pod files. Removed the duplicated content; that often mean the whole file could be removed. Some of the content about internals got moved into README files in the source tree. Some content (e.g., err.pod) got moved into other pod pages. Annotate generic pages, remove dup NAME Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-06-10 04:39:19 +08:00
Each sub-library has a specific macro XXXerr() that is used to report
errors. Its first argument is a function code B<XXX_F_...>, the second
argument is a reason code B<XXX_R_...>. Function codes are derived
from the function names; reason codes consist of textual error
descriptions. For example, the function ssl3_read_bytes() reports a
"handshake failure" as follows:
SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE);
Fix errors found by new find-doc-nits Also patch find-doc-nits to ignore a Microsoft trademark and not flag it as a spelling error. Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/10023)
2019-09-28 01:17:09 +08:00
Function and reason codes should consist of uppercase characters,
Clean up "generic" intro pod files. Files like dh.pod, etc., mostly duplicated the API-specific pod files. Removed the duplicated content; that often mean the whole file could be removed. Some of the content about internals got moved into README files in the source tree. Some content (e.g., err.pod) got moved into other pod pages. Annotate generic pages, remove dup NAME Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-06-10 04:39:19 +08:00
numbers and underscores only. The error file generation script translates
function codes into function names by looking in the header files
for an appropriate function name, if none is found it just uses
the capitalized form such as "SSL3_READ_BYTES" in the above example.
The trailing section of a reason code (after the "_R_") is translated
Fix errors found by new find-doc-nits Also patch find-doc-nits to ignore a Microsoft trademark and not flag it as a spelling error. Reviewed-by: Richard Levitte <levitte@openssl.org> Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/10023)
2019-09-28 01:17:09 +08:00
into lowercase and underscores changed to spaces.
Clean up "generic" intro pod files. Files like dh.pod, etc., mostly duplicated the API-specific pod files. Removed the duplicated content; that often mean the whole file could be removed. Some of the content about internals got moved into README files in the source tree. Some content (e.g., err.pod) got moved into other pod pages. Annotate generic pages, remove dup NAME Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-06-10 04:39:19 +08:00
Although a library will normally report errors using its own specific
XXXerr macro, another library's macro can be used. This is normally
only done when a library wants to include ASN1 code which must use
the ASN1err() macro.
Document ERR library.
2000-02-01 09:37:00 +08:00
=head1 RETURN VALUES
ERR: Remove ERR_put_func_error() and reimplement ERR_put_error() as a macro Also, deprecate ERR_put_error() Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:25:56 +08:00
ERR_raise(), ERR_put_error(), ERR_add_error_data() and
ERR_add_error_vdata() return no values.
ERR: Implement the macros ERR_raise() and ERR_raise_data() and use them The ERR_raise() macro uses a trick in C. The following is permitted: #include <stdio.h> void first(void) { printf("Hello! "); } void foo(const char *bar) { printf("%s", bar); } int main() { /* This */ (first(),foo)("cookie"); } ERR_raise_data() can be used to implement FUNCerr() as well, which takes away the need for the special function ERR_put_func_error(). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:13:52 +08:00
=head1 NOTES
ERR: Remove ERR_put_func_error() and reimplement ERR_put_error() as a macro Also, deprecate ERR_put_error() Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:25:56 +08:00
ERR_raise() and ERR_put_error() are implemented as macros.
Document ERR library.
2000-02-01 09:37:00 +08:00
=head1 SEE ALSO
Remove ref to err(7), update copyright. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from https://github.com/openssl/openssl/pull/2825)
2017-03-02 23:07:21 +08:00
L<ERR_load_strings(3)>
Document ERR library.
2000-02-01 09:37:00 +08:00
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
=head1 COPYRIGHT
ERR: Implement the macros ERR_raise() and ERR_raise_data() and use them The ERR_raise() macro uses a trick in C. The following is permitted: #include <stdio.h> void first(void) { printf("Hello! "); } void foo(const char *bar) { printf("%s", bar); } int main() { /* This */ (first(),foo)("cookie"); } ERR_raise_data() can be used to implement FUNCerr() as well, which takes away the need for the special function ERR_put_func_error(). Reviewed-by: Paul Dale <paul.dale@oracle.com> (Merged from https://github.com/openssl/openssl/pull/9452)
2019-07-24 19:13:52 +08:00
Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved.
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
Following the license change, modify the boilerplates in doc/man3/ [skip ci] Reviewed-by: Matt Caswell <matt@openssl.org> (Merged from https://github.com/openssl/openssl/pull/7829)
2018-12-06 21:04:44 +08:00
Licensed under the Apache License 2.0 (the "License"). You may not use
Add copyright to manpages Reviewed-by: Richard Levitte <levitte@openssl.org>
2016-05-18 23:44:05 +08:00
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
Reference in New Issue Copy Permalink