ERR(3C) Standard C Library Functions ERR(3C)
NAME
err,
errc,
errx,
warn,
warnc,
warnx,
verr,
verrc,
verrx,
vwarn,
vwarnc,
vwarnx - formatted error messages
SYNOPSIS
#include <err.h> void err(
int eval,
const char *fmt,
...);
void errc(
int eval,
int code,
const char *fmt,
...);
void errx(
int eval,
const char *fmt,
...);
void warn(
const char *fmt,
...);
void warnc(
int code,
const char *fmt,
...);
void warnx(
const char *fmt,
...);
void verr(
int eval,
const char *fmt,
va_list args);
void verrc(
int eval,
int code,
const char *fmt,
va_list args);
void verrx(
int eval,
const char *fmt,
va_list args);
void vwarn(
const char *fmt,
va_list args);
void vwarnc(
int code,
const char *fmt,
va_list args);
void vwarnx(
const char *fmt,
va_list args);
DESCRIPTION
The
err() and
warn() family of functions display a formatted error
message to standard error. In all cases, the last component of the
program name, followed by a colon character and a space, are output.
If the
fmt argument is not NULL, the formatted error message is output.
In the case of the
err(),
errc(),
warn(),
warnc(),
verr(),
verrc(),
vwarn() and
vwarnc() functions, an error message obtained from
strerror(3C) is output next, preceded by a colon character and a space
if
fmt is not NULL. The
err(),
warn(),
verr() and
vwarn() functions
produce the error string affiliated with the current value of the
global variable
errno. The
errc(),
warnc(),
verrc() and
vwarnc()
functions use the provided
code value to look up the error message.
The
errx(),
verrx(),
warnx() and
vwarnx() functions will not output
this error message string.
In all cases, the output is followed by a newline character.
The
err(),
errc(),
errx(),
verr(),
verrc() and
verrx() functions do not
return, but instead cause the program to terminate with the status
value given by the
eval argument.
EXAMPLES
Example 1 Display the current
errno information string and terminate
with status indicating failure.
#include <err.h>
...
if ((p = malloc(size)) == NULL)
err(EXIT_FAILURE, NULL);
if ((fd = open(file_name, O_RDONLY, 0)) == -1)
err(EXIT_FAILURE, "%s", file_name);
Example 2 Display an error message and terminate with status indicating
failure.
if (tm.tm_hour < START_TIME)
errx(EXIT_FAILURE, "wait until %s", start_time_string);
Example 3 Warn of an error.
if ((fd = open(raw_device, O_RDONLY, 0)) == -1) {
warnx("%s: %s: trying the block device",
raw_device, strerror(errno));
}
if ((fd = open(block_device, O_RDONLY, 0)) == -1)
warn("%s", block_device);
Example 4 Warn of an error using a custom error code
int error = function_returning_error_code();
if (error != 0)
warnc(error, "%s", "function did not succeed");
WARNINGS
It is important never to pass a string with user-supplied data as a
format without using `%s'. An attacker can put format specifiers in
the string to mangle the stack, leading to a possible security hole.
This holds true even if the string has been built by hand using a
function like
snprintf(3C), as the resulting string can still contain
user-supplied conversion specifiers for later interpolation by the
err() and
warn() functions.
Always be sure to use the proper secure idiom:
err(1, "%s", string);
INTERFACE STABILITY
CommittedMT-LEVEL MT-Safe with Exceptions These functions are safe to use in multithreaded applications as long
as
setlocale(3C) is not being called to change the locale.
SEE ALSO
exit(3C),
getexecname(3C),
setlocale(3C),
strerror(3C),
attributes(7)STANDARDS
The functions described in this man page are BSD extensions and should
not be used in portable code.
illumos November 15, 2022 illumos
