ERR(3)

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

# NAME

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

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <err.h>`

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

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

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

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

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

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

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

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

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

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

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

void
`vwarnc`(int code, 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 these functions output the last component of the program name, a colon character, and a space. If the fmt argument is not `NULL`, it is used as a printf(3)-like format specification for the error message.

In the case of the `err`(), `verr`(), `warn`(), and `vwarn`() functions, an additional error message string affiliated with the current value of the global variable errno is output next, preceded by a colon character and a space if fmt is not `NULL`. The `errc`(), `verrc`(), `warnc`(), and `vwarnc`() functions take an additional code argument to be used as the error number instead of using the global errno variable. The `errx`(), `verrx`(), `warnx`(), and `vwarnx`() functions will not output an additional error message string.

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

The `err`(), `verr`(), `errc`(), `verrc`(), `errx`(), and `verrx`() functions do not return, but instead cause the program to terminate with the status value given by the argument status. It is often appropriate to use the value `EXIT_FAILURE`, defined in `<stdlib.h>`, as the status argument given to these functions.

# EXAMPLES

Display the current errno information string and terminate with status indicating failure:

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

Display an error message and terminate with status indicating failure:

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

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);

# SEE ALSO

exit(3), getprogname(3), printf(3), strerror(3)

# HISTORY

The `err`() and `warn`() functions first appeared in 4.4BSD. The `errc`() and `warnc`() functions first appeared in FreeBSD 3.0 and NetBSD 7.0.

# 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 your stack, leading to a possible security hole. This holds true even if you have built the string “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);

February 2, 2024 | NetBSD 11.0