\" $NetBSD: err.3,v 1.24 2024/02/02 21:16:41 jkoshy Exp $
\"
\" Copyright (c) 1993
\"      The Regents of the University of California.  All rights reserved.
\"
\" Redistribution and use in source and binary forms, with or without
\" modification, are permitted provided that the following conditions
\" are met:
\" 1. Redistributions of source code must retain the above copyright
\"    notice, this list of conditions and the following disclaimer.
\" 2. Redistributions in binary form must reproduce the above copyright
\"    notice, this list of conditions and the following disclaimer in the
\"    documentation and/or other materials provided with the distribution.
\" 3. Neither the name of the University nor the names of its contributors
\"    may be used to endorse or promote products derived from this software
\"    without specific prior written permission.
\"
\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
\" SUCH DAMAGE.
\"
\"      @(#)err.3       8.1 (Berkeley) 6/9/93
\"
Dd February 2, 2024
Dt ERR 3
Os
Sh NAME
Nm err ,
Nm verr ,
Nm errx ,
Nm verrx ,
Nm errc ,
Nm verrc ,
Nm warn ,
Nm vwarn ,
Nm warnx ,
Nm vwarnx ,
Nm warnc ,
Nm vwarnc
Nd formatted error messages
Sh LIBRARY
Lb libc
Sh SYNOPSIS
In err.h
Ft void
Fn err "int status" "const char *fmt" "..."
Ft void
Fn verr "int status" "const char *fmt" "va_list args"
Ft void
Fn errx "int status" "const char *fmt" "..."
Ft void
Fn verrx "int status" "const char *fmt" "va_list args"
Ft void
Fn errc "int status" "int code" "const char *fmt" "..."
Ft void
Fn verrc "int status" "int code" "const char *fmt" "va_list args"
Ft void
Fn warn "const char *fmt" "..."
Ft void
Fn vwarn "const char *fmt" "va_list args"
Ft void
Fn warnx "const char *fmt" "..."
Ft void
Fn vwarnx "const char *fmt" "va_list args"
Ft void
Fn warnc "int code" "const char *fmt" "..."
Ft void
Fn vwarnc "int code" "const char *fmt" "va_list args"
Sh DESCRIPTION
The
Fn err
and
Fn warn
family of functions display a formatted error message on the standard
error output.
Pp
In all cases these functions output the last component of the program name,
a colon character, and a space.
If the
Fa fmt
argument is not
Dv NULL ,
it is used as a
Xr printf 3 Ns
-like format specification for the error message.
Pp
In the case of the
Fn err ,
Fn verr ,
Fn warn ,
and
Fn vwarn
functions, an additional error message string affiliated with the current
value of the global variable
Va errno
is output next, preceded by a colon character and a space if
Fa fmt
is not
Dv NULL .
The
Fn errc ,
Fn verrc ,
Fn warnc ,
and
Fn vwarnc
functions take an additional
Ar code
argument to be used as the error number instead of using the global
Va errno
variable.
The
Fn errx ,
Fn verrx ,
Fn warnx ,
and
Fn vwarnx
functions will not output an additional error message string.
Pp
In all cases, the output is terminated by a newline character.
Pp
The
Fn err ,
Fn verr ,
Fn errc ,
Fn verrc ,
Fn errx ,
and
Fn verrx
functions do not return, but instead cause the program to terminate
with the status value given by the argument
Fa status .
It is often appropriate to use the value
Dv EXIT_FAILURE ,
defined in
In stdlib.h ,
as the
Fa status
argument given to these functions.
Sh EXAMPLES
Display the current
Va errno
information string and terminate with status indicating failure:
Bd -literal -offset indent
if ((p = malloc(size)) == NULL)
       err(EXIT_FAILURE, NULL);
if ((fd = open(file_name, O_RDONLY, 0)) == -1)
       err(EXIT_FAILURE, "%s", file_name);
Ed
Pp
Display an error message and terminate with status indicating failure:
Bd -literal -offset indent
if (tm.tm_hour < START_TIME)
       errx(EXIT_FAILURE, "too early, wait until %s",
           start_time_string);
Ed
Pp
Warn of an error:
Bd -literal -offset indent
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);
Ed
Sh SEE ALSO
Xr exit 3 ,
Xr getprogname 3 ,
Xr printf 3 ,
Xr strerror 3
Sh HISTORY
The
Fn err
and
Fn warn
functions first appeared in
Bx 4.4 .
The
Fn errc
and
Fn warnc
functions first appeared in
Fx 3.0
and
Nx 7.0 .
Sh CAVEATS
It is important never to pass a string with user-supplied data as a
format without using
Ql %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
Dq by hand
using a function like
Fn snprintf ,
as the resulting string may still contain user-supplied conversion specifiers
for later interpolation by the
Fn err
and
Fn warn
functions.
Pp
Always be sure to use the proper secure idiom:
Bd -literal -offset indent
err(1, "%s", string);
Ed

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.