ERR(3) | Library Functions Manual | ERR(3)

# NAME

`err`, `verr`, `errc`, `verrc`, `errx`, `verrx`, `warn`, `vwarn`, `warnc`, `vwarnc`, `warnx`, `vwarnx` — formatted error messages

# SYNOPSIS

`#include <err.h>`

void
`err`(int eval, const char *fmt, ...);

void
`verr`(int eval, const char *fmt, va_list args);

void
`errc`(int eval, int code, const char *fmt, ...);

void
`verrc`(int eval, int code, const char *fmt, va_list args);

void
`errx`(int eval, const char *fmt, ...);

void
`verrx`(int eval, const char *fmt, va_list args);

void
`warn`(const char *fmt, ...);

void
`vwarn`(const char *fmt, va_list args);

void
`warnc`(int code, const char *fmt, ...);

void
`vwarnc`(int code, const char *fmt, va_list args);

void
`warnx`(const char *fmt, ...);

void
`vwarnx`(const char *fmt, va_list args);

# DESCRIPTION

The `err`() and `warn`() family of functions display a formatted error message on the standard error output. In all cases, the last component of the program name, followed by a colon (‘:’) character and a space, are output. The text that follows depends on the function being called. The fmt specification (and associated arguments) may be any format allowed by printf(3) or `NULL`. If the fmt argument is not `NULL`, the formatted error message is output.

In the case of the `errx`(), `verrx`(), `warnx`(), and `vwarnx`() functions only, no additional text is output, so the output looks like the following:

    progname: fmt

The other functions all output an error message string affiliated with an error value (see strerror(3)), preceded by a colon character and a space if fmt is not `NULL`. That is, the output is as follows:

    progname: fmt: error message string

if fmt is not `NULL`, or:

    progname: error message string

if it is.

In the case of the `err`(), `verr`(), `warn`(), and `vwarn`() functions, the error value used is the current value of the global variable errno, while for the `errc`(), `verrc`(), `warnc`(), and `vwarnc`() function the argument code is used.

In all cases, the output is followed by a newline character.

The `err`(), `verr`(), `errc`(), `verrc`(), `errx`(), and `verrx`() functions do not return, but exit with the value of the argument eval.

# EXAMPLES

Display the current errno information string and exit:

    if ((p = malloc(size)) == NULL)
    	err(1, NULL);
    if ((fd = open(file_name, O_RDONLY)) == -1)
    	err(1, "%s", file_name);

Display an error message and exit:

    if (tm.tm_hour < START_TIME)
    	errx(1, "too early, wait until %s", start_time_string);

Warn of an error:

    if ((fd = open(raw_device, O_RDONLY)) == -1)
    	warnx("%s: %s: trying the block device",
    	    raw_device, strerror(errno));
    if ((fd = open(block_device, O_RDONLY)) == -1)
    	err(1, "%s", block_device);

# SEE ALSO

exit(3), perror(3), printf(3), strerror(3)

# HISTORY

The functions `err`(), `errx`(), `verr`(), `verrx`(), `warn`(), `warnx`(), `vwarn`(), and `vwarnx`() first appeared in 4.4BSD. The functions `errc`(), `verrc`(), `warnc`(), and `vwarnc`() first appeared in FreeBSD 3.0 and were ported to OpenBSD 5.6.

# CAVEATS

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`(), as the resulting string may 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);

On systems other than OpenBSD, the `LC_MESSAGES` locale(1) category can cause different strings to be printed instead of the normal errno(2) messages; see CAVEATS in setlocale(3) for details.

October 24, 2021 | Debian