gen/FreeBSD/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 .\" 4. 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 .\" $FreeBSD: src/lib/libc/gen/err.3,v 1.24 2008/10/31 15:14:40 rwatson Exp $
  30 .\"
  31 .Dd May 20, 2008
  32 .Dt ERR 3
  33 .Os
  34 .Sh NAME
  35 .Nm err ,
  36 .Nm verr ,
  37 .Nm errc ,
  38 .Nm verrc ,
  39 .Nm errx ,
  40 .Nm verrx ,
  41 .Nm warn ,
  42 .Nm vwarn ,
  43 .Nm warnc ,
  44 .Nm vwarnc ,
  45 .Nm warnx ,
  46 .Nm vwarnx ,
  47 .Nm err_set_exit ,
  48 #ifdef UNIFDEF_BLOCKS
  49 .Nm err_set_exit_b ,
  50 #endif
  51 .Nm err_set_file
  52 .Nd formatted error messages
  53 .Sh LIBRARY
  54 .Lb libc
  55 .Sh SYNOPSIS
  56 .In err.h
  57 .Ft void
  58 .Fn err "int eval" "const char *fmt" "..."
  59 .Ft void
  60 .Fn err_set_exit "void (*exitf)(int)"
  61 #ifdef UNIFDEF_BLOCKS
  62 .Ft void
  63 .Fn err_set_exit_b "void (^exitb)(int)"
  64 #endif
  65 .Ft void
  66 .Fn err_set_file "void *vfp"
  67 .Ft void
  68 .Fn errc "int eval" "int code" "const char *fmt" "..."
  69 .Ft void
  70 .Fn errx "int eval" "const char *fmt" "..."
  71 .Ft void
  72 .Fn warn "const char *fmt" "..."
  73 .Ft void
  74 .Fn warnc "int code" "const char *fmt" "..."
  75 .Ft void
  76 .Fn warnx "const char *fmt" "..."
  77 .In stdarg.h
  78 .Ft void
  79 .Fn verr "int eval" "const char *fmt" "va_list args"
  80 .Ft void
  81 .Fn verrc "int eval" "int code" "const char *fmt" "va_list args"
  82 .Ft void
  83 .Fn verrx "int eval" "const char *fmt" "va_list args"
  84 .Ft void
  85 .Fn vwarn "const char *fmt" "va_list args"
  86 .Ft void
  87 .Fn vwarnc "int code" "const char *fmt" "va_list args"
  88 .Ft void
  89 .Fn vwarnx "const char *fmt" "va_list args"
  90 .Sh DESCRIPTION
  91 The
  92 .Fn err
  93 and
  94 .Fn warn
  95 family of functions display a formatted error message on the standard
  96 error output, or on another file specified using the
  97 .Fn err_set_file
  98 function.
  99 In all cases, the last component of the program name, a colon character,
 100 and a space are output.
 101 If the
 102 .Fa fmt
 103 argument is not NULL, the
 104 .Xr printf 3 Ns
 105 -like formatted error message is output.
 106 The output is terminated by a newline character.
 107 .Pp
 108 The
 109 .Fn err ,
 110 .Fn errc ,
 111 .Fn verr ,
 112 .Fn verrc ,
 113 .Fn warn ,
 114 .Fn warnc ,
 115 .Fn vwarn ,
 116 and
 117 .Fn vwarnc
 118 functions append an error message obtained from
 119 .Xr strerror 3
 120 based on a supplied error code value or the global variable
 121 .Va errno ,
 122 preceded by another colon and space unless the
 123 .Fa fmt
 124 argument is
 125 .Dv NULL .
 126 .Pp
 127 In the case of the
 128 .Fn errc ,
 129 .Fn verrc ,
 130 .Fn warnc ,
 131 and
 132 .Fn vwarnc
 133 functions,
 134 the
 135 .Fa code
 136 argument is used to look up the error message.
 137 .Pp
 138 The
 139 .Fn err ,
 140 .Fn verr ,
 141 .Fn warn ,
 142 and
 143 .Fn vwarn
 144 functions use the global variable
 145 .Va errno
 146 to look up the error message.
 147 .Pp
 148 The
 149 .Fn errx
 150 and
 151 .Fn warnx
 152 functions do not append an error message.
 153 .Pp
 154 The
 155 .Fn err ,
 156 .Fn verr ,
 157 .Fn errc ,
 158 .Fn verrc ,
 159 .Fn errx ,
 160 and
 161 .Fn verrx
 162 functions do not return, but exit with the value of the argument
 163 .Fa eval .
 164 It is recommended that the standard values defined in
 165 .Xr sysexits 3
 166 be used for the value of
 167 .Fa eval .
 168 The
 169 .Fn err_set_exit
 170 function can be used to specify a function which is called before
 171 .Xr exit 3
 172 to perform any necessary cleanup; passing a null function pointer for
 173 .Va exitf
 174 resets the hook to do nothing.
 175 #ifdef UNIFDEF_BLOCKS
 176 The
 177 .Fn err_set_exit_b
 178 function is like
 179 .Fn err_set_exit
 180 except it takes a block pointer instead of a function pointer.
 181 .Bd -ragged -offset indent
 182 Note: The
 183 .Fn Block_copy
 184 function (defined in
 185 .In Blocks.h )
 186 is used by
 187 .Fn err_set_exit_b
 188 to make a copy of the block, especially for the case when a stack-based
 189 block might go out of scope when the subroutine returns.
 190 .Ed
 191 .Pp
 192 #endif
 193 The
 194 .Fn err_set_file
 195 function sets the output stream used by the other functions.
 196 Its
 197 .Fa vfp
 198 argument must be either a pointer to an open stream
 199 (possibly already converted to void *)
 200 or a null pointer
 201 (in which case the output stream is set to standard error).
 202 .Sh EXAMPLES
 203 Display the current errno information string and exit:
 204 .Bd -literal -offset indent
 205 if ((p = malloc(size)) == NULL)
 206         err(EX_OSERR, NULL);
 207 if ((fd = open(file_name, O_RDONLY, 0)) == -1)
 208         err(EX_NOINPUT, "%s", file_name);
 209 .Ed
 210 .Pp
 211 Display an error message and exit:
 212 .Bd -literal -offset indent
 213 if (tm.tm_hour < START_TIME)
 214         errx(EX_DATAERR, "too early, wait until %s",
 215             start_time_string);
 216 .Ed
 217 .Pp
 218 Warn of an error:
 219 .Bd -literal -offset indent
 220 if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
 221         warnx("%s: %s: trying the block device",
 222             raw_device, strerror(errno));
 223 if ((fd = open(block_device, O_RDONLY, 0)) == -1)
 224         err(EX_OSFILE, "%s", block_device);
 225 .Ed
 226 .Pp
 227 Warn of an error without using the global variable
 228 .Va errno :
 229 .Bd -literal -offset indent
 230 error = my_function();  /* returns a value from <errno.h> */
 231 if (error != 0)
 232         warnc(error, "my_function");
 233 .Ed
 234 .Sh SEE ALSO
 235 .Xr exit 3 ,
 236 .Xr fmtmsg 3 ,
 237 .Xr printf 3 ,
 238 .Xr strerror 3 ,
 239 .Xr sysexits 3
 240 .Sh HISTORY
 241 The
 242 .Fn err
 243 and
 244 .Fn warn
 245 functions first appeared in
 246 .Bx 4.4 .
 247 The
 248 .Fn err_set_exit
 249 and
 250 .Fn err_set_file
 251 functions first appeared in
 252 .Fx 2.1 .
 253 The
 254 .Fn errc
 255 and
 256 .Fn warnc
 257 functions first appeared in
 258 .Fx 3.0 .
 259 #ifdef UNIFDEF_BLOCKS
 260 The
 261 .Fn err_set_exit_b
 262 function first appeared in Mac OS X 10.6.
 263 #endif