lib/libc/gen/err.3

   1 .\" $NetBSD: err.3,v 1.21 2014/01/16 17:21:38 christos Exp $
   2 .\"
   3 .\" Copyright (c) 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)err.3       8.1 (Berkeley) 6/9/93
  31 .\"
  32 .Dd January 16, 2014
  33 .Dt ERR 3
  34 .Os
  35 .Sh NAME
  36 .Nm err ,
  37 .Nm verr ,
  38 .Nm errx ,
  39 .Nm verrx ,
  40 .Nm errc ,
  41 .Nm verrc ,
  42 .Nm warn ,
  43 .Nm vwarn ,
  44 .Nm warnx ,
  45 .Nm vwarnx ,
  46 .Nm warnc ,
  47 .Nm vwarnc
  48 .Nd formatted error messages
  49 .Sh LIBRARY
  50 .Lb libc
  51 .Sh SYNOPSIS
  52 .In err.h
  53 .Ft void
  54 .Fn err "int status" "const char *fmt" "..."
  55 .Ft void
  56 .Fn verr "int status" "const char *fmt" "va_list args"
  57 .Ft void
  58 .Fn errx "int status" "const char *fmt" "..."
  59 .Ft void
  60 .Fn verrx "int status" "const char *fmt" "va_list args"
  61 .Ft void
  62 .Fn errc "int status" "int code" "const char *fmt" "..."
  63 .Ft void
  64 .Fn verrc "int status" "int code" "const char *fmt" "va_list args"
  65 .Ft void
  66 .Fn warn "const char *fmt" "..."
  67 .Ft void
  68 .Fn vwarn "const char *fmt" "va_list args"
  69 .Ft void
  70 .Fn warnx "const char *fmt" "..."
  71 .Ft void
  72 .Fn vwarnx "const char *fmt" "va_list args"
  73 .Ft void
  74 .Fn warnc "int code" "const char *fmt" "..."
  75 .Ft void
  76 .Fn vwarnc "int code" "const char *fmt" "va_list args"
  77 .Sh DESCRIPTION
  78 The
  79 .Fn err
  80 and
  81 .Fn warn
  82 family of functions display a formatted error message on the standard
  83 error output.
  84 In all cases, the last component of the program name, a colon character,
  85 and a space are output.
  86 If the
  87 .Fa fmt
  88 argument is not
  89 .Dv NULL ,
  90 the formatted error message is output.
  91 In the case of the
  92 .Fn err ,
  93 .Fn verr ,
  94 .Fn warn ,
  95 and
  96 .Fn vwarn
  97 functions, the error message string affiliated with the current value of
  98 the global variable
  99 .Va errno
 100 is output next, preceded by a colon character and a space if
 101 .Fa fmt
 102 is not
 103 .Dv NULL .
 104 In all cases, the output is followed by a newline character.
 105 The
 106 .Fn errc ,
 107 .Fn verrc ,
 108 .Fn warnc ,
 109 and
 110 .Fn vwarnc
 111 functions take an additional
 112 .Ar code
 113 argument to be used as the error number instead of using the global
 114 .Va errno
 115 variable.
 116 The
 117 .Fn errx ,
 118 .Fn verrx ,
 119 .Fn warnx ,
 120 and
 121 .Fn vwarnx
 122 functions will not output this error message string.
 123 .Pp
 124 The
 125 .Fn err ,
 126 .Fn verr ,
 127 .Fn errx ,
 128 and
 129 .Fn verrx
 130 functions do not return, but instead cause the program to terminate
 131 with the status value given by the argument
 132 .Fa status .
 133 It is often appropriate to use the value
 134 .Dv EXIT_FAILURE ,
 135 defined in
 136 .In stdlib.h ,
 137 as the
 138 .Fa status
 139 argument given to these functions.
 140 .Sh EXAMPLES
 141 Display the current
 142 .Va errno
 143 information string and terminate with status indicating failure:
 144 .Bd -literal -offset indent
 145 if ((p = malloc(size)) == NULL)
 146         err(EXIT_FAILURE, NULL);
 147 if ((fd = open(file_name, O_RDONLY, 0)) == -1)
 148         err(EXIT_FAILURE, "%s", file_name);
 149 .Ed
 150 .Pp
 151 Display an error message and terminate with status indicating failure:
 152 .Bd -literal -offset indent
 153 if (tm.tm_hour \*[Lt] START_TIME)
 154         errx(EXIT_FAILURE, "too early, wait until %s",
 155             start_time_string);
 156 .Ed
 157 .Pp
 158 Warn of an error:
 159 .Bd -literal -offset indent
 160 if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
 161         warnx("%s: %s: trying the block device",
 162             raw_device, strerror(errno));
 163 if ((fd = open(block_device, O_RDONLY, 0)) == -1)
 164         warn("%s", block_device);
 165 .Ed
 166 .Sh SEE ALSO
 167 .Xr exit 3 ,
 168 .Xr getprogname 3 ,
 169 .Xr strerror 3
 170 .Sh HISTORY
 171 The
 172 .Fn err
 173 and
 174 .Fn warn
 175 functions first appeared in
 176 .Bx 4.4 .
 177 The
 178 .Fn errc
 179 and
 180 .Fn warnc
 181 functions first appeared in
 182 .Fx 3.0
 183 and
 184 .Nx 7.0 .
 185 .Sh CAVEATS
 186 It is important never to pass a string with user-supplied data as a
 187 format without using
 188 .Ql %s .
 189 An attacker can put format specifiers in the string to mangle your stack,
 190 leading to a possible security hole.
 191 This holds true even if you have built the string
 192 .Dq by hand
 193 using a function like
 194 .Fn snprintf ,
 195 as the resulting string may still contain user-supplied conversion specifiers
 196 for later interpolation by the
 197 .Fn err
 198 and
 199 .Fn warn
 200 functions.
 201 .Pp
 202 Always be sure to use the proper secure idiom:
 203 .Bd -literal -offset indent
 204 err(1, "%s", string);
 205 .Ed