.TH erl_error 3erl "erl_interface 3.9.2" "Ericsson AB" "C Library Functions"
.SH NAME
erl_error \- Error print routines.
.SH DESCRIPTION
.LP
This module contains some error printing routines taken from "Advanced Programming in the UNIX Environment" by W\&. Richard Stevens\&.
.LP
These functions are all called in the same manner as \fIprintf()\fR\&, that is, with a string containing format specifiers followed by a list of corresponding arguments\&. All output from these functions is to \fIstderr\fR\&\&.
.SH EXPORTS
.LP
.B
void erl_err_msg(FormatStr, ... )
.br
.RS
.LP
Types:

.RS 3
const char *FormatStr;
.br
.RE
.RE
.RS
.LP
The message provided by the caller is printed\&. This function is simply a wrapper for \fIfprintf()\fR\&\&.
.RE

.LP
.B
void erl_err_quit(FormatStr, ... )
.br
.RS
.LP
Types:

.RS 3
const char *FormatStr;
.br
.RE
.RE
.RS
.LP
Use this function when a fatal error has occurred that is not because of a system call\&. The message provided by the caller is printed and the process terminates with exit value \fI1\fR\&\&. This function does not return\&.
.RE

.LP
.B
void erl_err_ret(FormatStr, ... )
.br
.RS
.LP
Types:

.RS 3
const char *FormatStr;
.br
.RE
.RE
.RS
.LP
Use this function after a failed system call\&. The message provided by the caller is printed followed by a string describing the reason for failure\&.
.RE

.LP
.B
void erl_err_sys(FormatStr, ... )
.br
.RS
.LP
Types:

.RS 3
const char *FormatStr;
.br
.RE
.RE
.RS
.LP
Use this function after a failed system call\&. The message provided by the caller is printed followed by a string describing the reason for failure, and the process terminates with exit value \fI1\fR\&\&. This function does not return\&.
.RE

.SH "ERROR REPORTING"

.LP
Most functions in \fIErl_Interface\fR\& report failures to the caller by returning some otherwise meaningless value (typically \fINULL\fR\& or a negative number)\&. As this only tells you that things did not go well, examine the error code in \fIerl_errno\fR\& if you want to find out more about the failure\&.
.SH EXPORTS
.LP
.B
volatile int erl_errno
.br
.RS
.LP
\fIerl_errno\fR\& is initially (at program startup) zero and is then set by many \fIErl_Interface\fR\& functions on failure to a non-zero error code to indicate what kind of error it encountered\&. A successful function call can change \fIerl_errno\fR\& (by calling some other function that fails), but no function does never set it to zero\&. This means that you cannot use \fIerl_errno\fR\& to see \fIif\fR\& a function call failed\&. Instead, each function reports failure in its own way (usually by returning a negative number or \fINULL\fR\&), in which case you can examine \fIerl_errno\fR\& for details\&.
.LP
\fIerl_errno\fR\& uses the error codes defined in your system\&'s \fI<errno\&.h>\fR\&\&.
.LP

.RS -4
.B
Note:
.RE
\fIerl_errno\fR\& is a "modifiable lvalue" (just like ISO C defines \fIerrno\fR\& to be) rather than a variable\&. This means it can be implemented as a macro (expanding to, for example, \fI*_erl_errno()\fR\&)\&. For reasons of thread safety (or task safety), this is exactly what we do on most platforms\&.

.RE