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


Committed

MT-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