CMSCOPE changed

1 files changed, 322 insertions, 0 deletions

diff --git a/usr/man/man3/err.3 b/usr/man/man3/err.3
new file mode 100755
index 000000000..fe10b9d5a
--- /dev/null
+++ b/usr/man/man3/err.3
@@ -0,0 +1,322 @@
+.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{
+.    if \nF \{
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "err 3"
+.TH err 3 "2014-06-05" "0.9.8za" "OpenSSL"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+err \- error codes
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& #include <openssl/err.h>
+\&
+\& unsigned long ERR_get_error(void);
+\& unsigned long ERR_peek_error(void);
+\& unsigned long ERR_get_error_line(const char **file, int *line);
+\& unsigned long ERR_peek_error_line(const char **file, int *line);
+\& unsigned long ERR_get_error_line_data(const char **file, int *line,
+\&         const char **data, int *flags);
+\& unsigned long ERR_peek_error_line_data(const char **file, int *line,
+\&         const char **data, int *flags);
+\&
+\& int ERR_GET_LIB(unsigned long e);
+\& int ERR_GET_FUNC(unsigned long e);
+\& int ERR_GET_REASON(unsigned long e);
+\&
+\& void ERR_clear_error(void);
+\&
+\& char *ERR_error_string(unsigned long e, char *buf);
+\& const char *ERR_lib_error_string(unsigned long e);
+\& const char *ERR_func_error_string(unsigned long e);
+\& const char *ERR_reason_error_string(unsigned long e);
+\&
+\& void ERR_print_errors(BIO *bp);
+\& void ERR_print_errors_fp(FILE *fp);
+\&
+\& void ERR_load_crypto_strings(void);
+\& void ERR_free_strings(void);
+\&
+\& void ERR_remove_state(unsigned long pid);
+\&
+\& void ERR_put_error(int lib, int func, int reason, const char *file,
+\&         int line);
+\& void ERR_add_error_data(int num, ...);
+\&
+\& void ERR_load_strings(int lib,ERR_STRING_DATA str[]);
+\& unsigned long ERR_PACK(int lib, int func, int reason);
+\& int ERR_get_next_error_library(void);
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+When a call to the OpenSSL library fails, this is usually signalled
+by the return value, and an error code is stored in an error queue
+associated with the current thread. The \fBerr\fR library provides
+functions to obtain these error codes and textual error messages.
+.PP
+The \fIERR_get_error\fR\|(3) manpage describes how to
+access error codes.
+.PP
+Error codes contain information about where the error occurred, and
+what went wrong. \s-1\fIERR_GET_LIB\s0\fR\|(3) describes how to
+extract this information. A method to obtain human-readable error
+messages is described in \fIERR_error_string\fR\|(3).
+.PP
+\&\fIERR_clear_error\fR\|(3) can be used to clear the
+error queue.
+.PP
+Note that \fIERR_remove_state\fR\|(3) should be used to
+avoid memory leaks when threads are terminated.
+.SH "ADDING NEW ERROR CODES TO OPENSSL"
+.IX Header "ADDING NEW ERROR CODES TO OPENSSL"
+See \fIERR_put_error\fR\|(3) if you want to record error codes in the
+OpenSSL error system from within your application.
+.PP
+The remainder of this section is of interest only if you want to add
+new error codes to OpenSSL or add error codes from external libraries.
+.SS "Reporting errors"
+.IX Subsection "Reporting errors"
+Each sub-library has a specific macro \fIXXXerr()\fR that is used to report
+errors. Its first argument is a function code \fB\s-1XXX_F_...\s0\fR, the second
+argument is a reason code \fB\s-1XXX_R_...\s0\fR. Function codes are derived
+from the function names; reason codes consist of textual error
+descriptions. For example, the function \fIssl23_read()\fR reports a
+\&\*(L"handshake failure\*(R" as follows:
+.PP
+.Vb 1
+\& SSLerr(SSL_F_SSL23_READ, SSL_R_SSL_HANDSHAKE_FAILURE);
+.Ve
+.PP
+Function and reason codes should consist of upper case characters,
+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 \*(L"\s-1SSL23_READ\*(R"\s0 in the above example.
+.PP
+The trailing section of a reason code (after the \*(L"_R_\*(R") is translated
+into lower case and underscores changed to spaces.
+.PP
+When you are using new function or reason codes, run \fBmake errors\fR.
+The necessary \fB#define\fRs will then automatically be added to the
+sub-library's header file.
+.PP
+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 \s-1ASN1\s0 code which must use
+the \fIASN1err()\fR macro.
+.SS "Adding new libraries"
+.IX Subsection "Adding new libraries"
+When adding a new sub-library to OpenSSL, assign it a library number
+\&\fB\s-1ERR_LIB_XXX\s0\fR, define a macro \fIXXXerr()\fR (both in \fBerr.h\fR), add its
+name to \fBERR_str_libraries[]\fR (in \fBcrypto/err/err.c\fR), and add
+\&\f(CW\*(C`ERR_load_XXX_strings()\*(C'\fR to the \fIERR_load_crypto_strings()\fR function
+(in \fBcrypto/err/err_all.c\fR). Finally, add an entry
+.PP
+.Vb 1
+\& L      XXX     xxx.h   xxx_err.c
+.Ve
+.PP
+to \fBcrypto/err/openssl.ec\fR, and add \fBxxx_err.c\fR to the Makefile.
+Running \fBmake errors\fR will then generate a file \fBxxx_err.c\fR, and
+add all error codes used in the library to \fBxxx.h\fR.
+.PP
+Additionally the library include file must have a certain form.
+Typically it will initially look like this:
+.PP
+.Vb 2
+\& #ifndef HEADER_XXX_H
+\& #define HEADER_XXX_H
+\&
+\& #ifdef _\|_cplusplus
+\& extern "C" {
+\& #endif
+\&
+\& /* Include files */
+\&
+\& #include <openssl/bio.h>
+\& #include <openssl/x509.h>
+\&
+\& /* Macros, structures and function prototypes */
+\&
+\&
+\& /* BEGIN ERROR CODES */
+.Ve
+.PP
+The \fB\s-1BEGIN ERROR CODES\s0\fR sequence is used by the error code
+generation script as the point to place new error codes, any text
+after this point will be overwritten when \fBmake errors\fR is run.
+The closing #endif etc will be automatically added by the script.
+.PP
+The generated C error code file \fBxxx_err.c\fR will load the header
+files \fBstdio.h\fR, \fBopenssl/err.h\fR and \fBopenssl/xxx.h\fR so the
+header file must load any additional header files containing any
+definitions it uses.
+.SH "USING ERROR CODES IN EXTERNAL LIBRARIES"
+.IX Header "USING ERROR CODES IN EXTERNAL LIBRARIES"
+It is also possible to use OpenSSL's error code scheme in external
+libraries. The library needs to load its own codes and call the OpenSSL
+error code insertion script \fBmkerr.pl\fR explicitly to add codes to
+the header file and generate the C error code file. This will normally
+be done if the external library needs to generate new \s-1ASN1\s0 structures
+but it can also be used to add more general purpose error code handling.
+.PP
+\&\s-1TBA\s0 more details
+.SH "INTERNALS"
+.IX Header "INTERNALS"
+The error queues are stored in a hash table with one \fB\s-1ERR_STATE\s0\fR
+entry for each pid. \fIERR_get_state()\fR returns the current thread's
+\&\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
+codes. When more error codes are added, the old ones are overwritten,
+on the assumption that the most recent errors are most important.
+.PP
+Error strings are also stored in hash table. The hash tables can
+be obtained by calling ERR_get_err_state_table(void) and
+ERR_get_string_table(void) respectively.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fICRYPTO_set_id_callback\fR\|(3),
+\&\fICRYPTO_set_locking_callback\fR\|(3),
+\&\fIERR_get_error\fR\|(3),
+\&\s-1\fIERR_GET_LIB\s0\fR\|(3),
+\&\fIERR_clear_error\fR\|(3),
+\&\fIERR_error_string\fR\|(3),
+\&\fIERR_print_errors\fR\|(3),
+\&\fIERR_load_crypto_strings\fR\|(3),
+\&\fIERR_remove_state\fR\|(3),
+\&\fIERR_put_error\fR\|(3),
+\&\fIERR_load_strings\fR\|(3),
+\&\fISSL_get_error\fR\|(3)