| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | ERR_put_error, ERR_add_error_data, ERR_add_error_vdata - record an error
|
|---|
| 6 |
|
|---|
| 7 | =head1 SYNOPSIS
|
|---|
| 8 |
|
|---|
| 9 | #include <openssl/err.h>
|
|---|
| 10 |
|
|---|
| 11 | void ERR_put_error(int lib, int func, int reason, const char *file, int line);
|
|---|
| 12 |
|
|---|
| 13 | void ERR_add_error_data(int num, ...);
|
|---|
| 14 | void ERR_add_error_vdata(int num, va_list arg);
|
|---|
| 15 |
|
|---|
| 16 | =head1 DESCRIPTION
|
|---|
| 17 |
|
|---|
| 18 | ERR_put_error() adds an error code to the thread's error queue. It
|
|---|
| 19 | signals that the error of reason code B<reason> occurred in function
|
|---|
| 20 | B<func> of library B<lib>, in line number B<line> of B<file>.
|
|---|
| 21 | This function is usually called by a macro.
|
|---|
| 22 |
|
|---|
| 23 | ERR_add_error_data() associates the concatenation of its B<num> string
|
|---|
| 24 | arguments with the error code added last.
|
|---|
| 25 | ERR_add_error_vdata() is similar except the argument is a B<va_list>.
|
|---|
| 26 |
|
|---|
| 27 | L<ERR_load_strings(3)> can be used to register
|
|---|
| 28 | error strings so that the application can a generate human-readable
|
|---|
| 29 | error messages for the error code.
|
|---|
| 30 |
|
|---|
| 31 | =head2 Reporting errors
|
|---|
| 32 |
|
|---|
| 33 | Each sub-library has a specific macro XXXerr() that is used to report
|
|---|
| 34 | errors. Its first argument is a function code B<XXX_F_...>, the second
|
|---|
| 35 | argument is a reason code B<XXX_R_...>. Function codes are derived
|
|---|
| 36 | from the function names; reason codes consist of textual error
|
|---|
| 37 | descriptions. For example, the function ssl3_read_bytes() reports a
|
|---|
| 38 | "handshake failure" as follows:
|
|---|
| 39 |
|
|---|
| 40 | SSLerr(SSL_F_SSL3_READ_BYTES, SSL_R_SSL_HANDSHAKE_FAILURE);
|
|---|
| 41 |
|
|---|
| 42 | Function and reason codes should consist of uppercase characters,
|
|---|
| 43 | numbers and underscores only. The error file generation script translates
|
|---|
| 44 | function codes into function names by looking in the header files
|
|---|
| 45 | for an appropriate function name, if none is found it just uses
|
|---|
| 46 | the capitalized form such as "SSL3_READ_BYTES" in the above example.
|
|---|
| 47 |
|
|---|
| 48 | The trailing section of a reason code (after the "_R_") is translated
|
|---|
| 49 | into lowercase and underscores changed to spaces.
|
|---|
| 50 |
|
|---|
| 51 | Although a library will normally report errors using its own specific
|
|---|
| 52 | XXXerr macro, another library's macro can be used. This is normally
|
|---|
| 53 | only done when a library wants to include ASN1 code which must use
|
|---|
| 54 | the ASN1err() macro.
|
|---|
| 55 |
|
|---|
| 56 |
|
|---|
| 57 | =head1 RETURN VALUES
|
|---|
| 58 |
|
|---|
| 59 | ERR_put_error() and ERR_add_error_data() return
|
|---|
| 60 | no values.
|
|---|
| 61 |
|
|---|
| 62 | =head1 SEE ALSO
|
|---|
| 63 |
|
|---|
| 64 | L<ERR_load_strings(3)>
|
|---|
| 65 |
|
|---|
| 66 | =head1 COPYRIGHT
|
|---|
| 67 |
|
|---|
| 68 | Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 69 |
|
|---|
| 70 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 71 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 72 | in the file LICENSE in the source distribution or at
|
|---|
| 73 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 74 |
|
|---|
| 75 | =cut
|
|---|
