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