NAME
    strerror - returns a string describing an error value

SYNOPSIS
    strerror([errnum | "E_STRING"])

TYPES
    errnum      integer
    E_STRING    string

    return      string

DESCRIPTION
    With errno(errnum) numeric argument:

        strerror(errnum) will return one of:

        * system error and libc errno value related string
        * calc computation error code string
        * user-defined description string created by newerror(str)
        * "Unknown error errnum" (where errnum is in decimal)

    With strerror("E_STRING") string argument:

        If E_STRING is a valid errsym code, then the E_STRING errsym
        is converted into strerror(errnum).

        If E_STRING is not a valid errsym code, an error error condition
        is raised about the invalid E_STRING.

        For example, these two calls are equivalent:

            cstrerror(10003);   /* error 10003 has a E_STRING of "E_ADD" */
            cstrerror("E_ADD"); /* error 10003 has a E_STRING of "E_ADD" */

        See help errsym for information on E_STRING errsym codes.

        For a list of the E_STRING associated with calc computation error
        codes, see help errorcodes.

    Without a argument, strerror() returns as if it were called with:

        strerror(errno())

    That is, the string associated with the "global calc_errno value"
    is returned.

    The term "global calc_errno value" is an internal calc state.
    This is NOT a calc variable called calc_errno.

    The system error and libc errno value related string may be
    different for different systems.

    For users of libcalc:

        The libcalc array error_table[] contains the hard coded
        calc-generated error array of ECOUNT+2 pointers to strings
        starting with E__BASE, ending with E__HIGHEST and terminated
        by a NULL pointer.

        The error_table[0] is for errnum of E__BASE, and is the
        string "No error".

        The error_table[ECOUNT] is string associated with the
        highest calc-generated error message.

        The error_table[ECOUNT+1] is a NULL pointer.

     See help error for more information on the ranges of errnum and
     the meaning of the above mentioned constants.

EXAMPLE
    ; errcount(0),; errmax(20),;
    ; print errcount(), errmax()
    0 20

    ; print strerror(2)
    No such file or directory
    ; print errcount(), errmax()
    0 20

    ; x = 3 / 0;
    ; print errcount(), errmax()
    1 20
    ; print strerror()
    Division by zero

    ; a = newerror("alpha")
    ; print errcount(), errmax()
    2 20
    ; print strerror()
    alpha

    ; print strerror(999)
    Unknown error: 999
    ; print errcount(), errmax()
    2 20

LIMITS
    0 <= errnum <= 32767

    E_STRING is string that must match the regular expression: ^E_[A-Z0-9_]+$

LINK LIBRARY
    int calc_errno;                             /* global calc_errno value */

    CONST struct errtbl error_table[ECOUNT+2];  /* calc error codes, error symbols and error messages */

    bool is_e_digits(CONST char *errsym);
    bool is_valid_errnum(int errnum);
    bool is_errnum_in_error_table(int errnum);
    bool is_e_1string(CONST char *errsym);
    bool is_e_2string(CONST char *errsym);
    struct errtbl *find_errsym_in_errtbl(CONST char *errsym, CONST struct errtbl *tbl);
    struct errtbl *find_errnum_in_errtbl(int errnum, CONST struct errtbl *tbl);
    CONST struct errtbl *lookup_errnum_in_error_table(int errnum);
    int errsym_2_errnum(CONST char *errsym);
    char *errnum_2_errsym(int errnum, bool *palloced);
    char *errnum_2_errmsg(int errnum, bool *palloced);
    char *errsym_2_errmsg(CONST char *errsym, bool *palloced);

SEE ALSO
    errcount, errmax, errno, errorcodes, errsym, iserror, newerror, stoponerror

    strcat, strcpy, strlen, strncmp, strncpy, strpos,
    strprintf, strscan, strscanf, substr,

## Copyright (C) 1999-2006,2023  Landon Curt Noll
##
## Calc is open software; you can redistribute it and/or modify it under
## the terms of the version 2.1 of the GNU Lesser General Public License
## as published by the Free Software Foundation.
##
## Calc is distributed in the hope that it will be useful, but WITHOUT
## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
## or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General
## Public License for more details.
##
## A copy of version 2.1 of the GNU Lesser General Public License is
## distributed with calc under the filename COPYING-LGPL.  You should have
## received a copy with calc; if not, write to Free Software Foundation, Inc.
## 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##
## Under source code control:   1996/04/30 03:05:18
## File existed as early as:    1996
##
## chongo <was here> /\oo/\     http://www.isthe.com/chongo/
## Share and enjoy!  :-)        http://www.isthe.com/chongo/tech/comp/calc/
