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