lib/libc/gen/err.3

   1 .\" Copyright (c) 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)err.3 8.1 (Berkeley) 6/9/93
  29 .\"
  30 .Dd March 29, 2012
  31 .Dt ERR 3
  32 .Os
  33 .Sh NAME
  34 .Nm err ,
  35 .Nm verr ,
  36 .Nm errc ,
  37 .Nm verrc ,
  38 .Nm errx ,
  39 .Nm verrx ,
  40 .Nm warn ,
  41 .Nm vwarn ,
  42 .Nm warnc ,
  43 .Nm vwarnc ,
  44 .Nm warnx ,
  45 .Nm vwarnx ,
  46 .Nm err_set_exit ,
  47 .Nm err_set_file
  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 eval" "const char *fmt" "..."
  55 .Ft void
  56 .Fn err_set_exit "void (*exitf)(int)"
  57 .Ft void
  58 .Fn err_set_file "void *vfp"
  59 .Ft void
  60 .Fn errc "int eval" "int code" "const char *fmt" "..."
  61 .Ft void
  62 .Fn errx "int eval" "const char *fmt" "..."
  63 .Ft void
  64 .Fn warn "const char *fmt" "..."
  65 .Ft void
  66 .Fn warnc "int code" "const char *fmt" "..."
  67 .Ft void
  68 .Fn warnx "const char *fmt" "..."
  69 .In stdarg.h
  70 .Ft void
  71 .Fn verr "int eval" "const char *fmt" "va_list args"
  72 .Ft void
  73 .Fn verrc "int eval" "int code" "const char *fmt" "va_list args"
  74 .Ft void
  75 .Fn verrx "int eval" "const char *fmt" "va_list args"
  76 .Ft void
  77 .Fn vwarn "const char *fmt" "va_list args"
  78 .Ft void
  79 .Fn vwarnc "int code" "const char *fmt" "va_list args"
  80 .Ft void
  81 .Fn vwarnx "const char *fmt" "va_list args"
  82 .Sh DESCRIPTION
  83 The
  84 .Fn err
  85 and
  86 .Fn warn
  87 family of functions display a formatted error message on the standard
  88 error output, or on another file specified using the
  89 .Fn err_set_file
  90 function.
  91 In all cases, the last component of the program name, a colon character,
  92 and a space are output.
  93 If the
  94 .Fa fmt
  95 argument is not NULL, the
  96 .Xr printf 3 Ns
  97 -like formatted error message is output.
  98 The output is terminated by a newline character.
  99 .Pp
 100 The
 101 .Fn err ,
 102 .Fn errc ,
 103 .Fn verr ,
 104 .Fn verrc ,
 105 .Fn warn ,
 106 .Fn warnc ,
 107 .Fn vwarn ,
 108 and
 109 .Fn vwarnc
 110 functions append an error message obtained from
 111 .Xr strerror 3
 112 based on a supplied error code value or the global variable
 113 .Va errno ,
 114 preceded by another colon and space unless the
 115 .Fa fmt
 116 argument is
 117 .Dv NULL .
 118 .Pp
 119 In the case of the
 120 .Fn errc ,
 121 .Fn verrc ,
 122 .Fn warnc ,
 123 and
 124 .Fn vwarnc
 125 functions,
 126 the
 127 .Fa code
 128 argument is used to look up the error message.
 129 .Pp
 130 The
 131 .Fn err ,
 132 .Fn verr ,
 133 .Fn warn ,
 134 and
 135 .Fn vwarn
 136 functions use the global variable
 137 .Va errno
 138 to look up the error message.
 139 .Pp
 140 The
 141 .Fn errx
 142 and
 143 .Fn warnx
 144 functions do not append an error message.
 145 .Pp
 146 The
 147 .Fn err ,
 148 .Fn verr ,
 149 .Fn errc ,
 150 .Fn verrc ,
 151 .Fn errx ,
 152 and
 153 .Fn verrx
 154 functions do not return, but exit with the value of the argument
 155 .Fa eval .
 156 It is recommended that the standard values defined in
 157 .Xr sysexits 3
 158 be used for the value of
 159 .Fa eval .
 160 The
 161 .Fn err_set_exit
 162 function can be used to specify a function which is called before
 163 .Xr exit 3
 164 to perform any necessary cleanup; passing a null function pointer for
 165 .Va exitf
 166 resets the hook to do nothing.
 167 The
 168 .Fn err_set_file
 169 function sets the output stream used by the other functions.
 170 Its
 171 .Fa vfp
 172 argument must be either a pointer to an open stream
 173 (possibly already converted to void *)
 174 or a null pointer
 175 (in which case the output stream is set to standard error).
 176 .Sh EXAMPLES
 177 Display the current errno information string and exit:
 178 .Bd -literal -offset indent
 179 if ((p = malloc(size)) == NULL)
 180         err(EX_OSERR, NULL);
 181 if ((fd = open(file_name, O_RDONLY, 0)) == -1)
 182         err(EX_NOINPUT, "%s", file_name);
 183 .Ed
 184 .Pp
 185 Display an error message and exit:
 186 .Bd -literal -offset indent
 187 if (tm.tm_hour < START_TIME)
 188         errx(EX_DATAERR, "too early, wait until %s",
 189             start_time_string);
 190 .Ed
 191 .Pp
 192 Warn of an error:
 193 .Bd -literal -offset indent
 194 if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
 195         warnx("%s: %s: trying the block device",
 196             raw_device, strerror(errno));
 197 if ((fd = open(block_device, O_RDONLY, 0)) == -1)
 198         err(EX_OSFILE, "%s", block_device);
 199 .Ed
 200 .Pp
 201 Warn of an error without using the global variable
 202 .Va errno :
 203 .Bd -literal -offset indent
 204 error = my_function();  /* returns a value from <errno.h> */
 205 if (error != 0)
 206         warnc(error, "my_function");
 207 .Ed
 208 .Sh SEE ALSO
 209 .Xr exit 3 ,
 210 .Xr fmtmsg 3 ,
 211 .Xr printf 3 ,
 212 .Xr strerror 3 ,
 213 .Xr sysexits 3
 214 .Sh STANDARDS
 215 The
 216 .Fn err
 217 and
 218 .Fn warn
 219 families of functions are
 220 .Bx
 221 extensions.
 222 As such they should not be used in truly portable code.
 223 Use
 224 .Fn strerror
 225 or similar functions instead.
 226 .Sh HISTORY
 227 The
 228 .Fn err
 229 and
 230 .Fn warn
 231 functions first appeared in
 232 .Bx 4.4 .
 233 The
 234 .Fn err_set_exit
 235 and
 236 .Fn err_set_file
 237 functions first appeared in
 238 .Fx 2.1 .
 239 The
 240 .Fn errc
 241 and
 242 .Fn warnc
 243 functions first appeared in
 244 .Fx 3.0 .