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 .\" 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$
  30 .\"
  31 .Dd March 29, 2012
  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 and
 144 .Fn warnx
 145 functions do not append an error message.
 146 .Pp
 147 The
 148 .Fn err ,
 149 .Fn verr ,
 150 .Fn errc ,
 151 .Fn verrc ,
 152 .Fn errx ,
 153 and
 154 .Fn verrx
 155 functions do not return, but exit with the value of the argument
 156 .Fa eval .
 157 It is recommended that the standard values defined in
 158 .Xr sysexits 3
 159 be used for the value of
 160 .Fa eval .
 161 The
 162 .Fn err_set_exit
 163 function can be used to specify a function which is called before
 164 .Xr exit 3
 165 to perform any necessary cleanup; passing a null function pointer for
 166 .Va exitf
 167 resets the hook to do nothing.
 168 The
 169 .Fn err_set_file
 170 function sets the output stream used by the other functions.
 171 Its
 172 .Fa vfp
 173 argument must be either a pointer to an open stream
 174 (possibly already converted to void *)
 175 or a null pointer
 176 (in which case the output stream is set to standard error).
 177 .Sh EXAMPLES
 178 Display the current errno information string and exit:
 179 .Bd -literal -offset indent
 180 if ((p = malloc(size)) == NULL)
 181         err(EX_OSERR, NULL);
 182 if ((fd = open(file_name, O_RDONLY, 0)) == -1)
 183         err(EX_NOINPUT, "%s", file_name);
 184 .Ed
 185 .Pp
 186 Display an error message and exit:
 187 .Bd -literal -offset indent
 188 if (tm.tm_hour < START_TIME)
 189         errx(EX_DATAERR, "too early, wait until %s",
 190             start_time_string);
 191 .Ed
 192 .Pp
 193 Warn of an error:
 194 .Bd -literal -offset indent
 195 if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
 196         warnx("%s: %s: trying the block device",
 197             raw_device, strerror(errno));
 198 if ((fd = open(block_device, O_RDONLY, 0)) == -1)
 199         err(EX_OSFILE, "%s", block_device);
 200 .Ed
 201 .Pp
 202 Warn of an error without using the global variable
 203 .Va errno :
 204 .Bd -literal -offset indent
 205 error = my_function();  /* returns a value from <errno.h> */
 206 if (error != 0)
 207         warnc(error, "my_function");
 208 .Ed
 209 .Sh SEE ALSO
 210 .Xr exit 3 ,
 211 .Xr fmtmsg 3 ,
 212 .Xr printf 3 ,
 213 .Xr strerror 3 ,
 214 .Xr sysexits 3
 215 .Sh STANDARDS
 216 The
 217 .Fn err
 218 and
 219 .Fn warn
 220 families of functions are
 221 .Bx
 222 extensions.
 223 As such they should not be used in truly portable code.
 224 Use
 225 .Fn strerror
 226 or similar functions instead.
 227 .Sh HISTORY
 228 The
 229 .Fn err
 230 and
 231 .Fn warn
 232 functions first appeared in
 233 .Bx 4.4 .
 234 The
 235 .Fn err_set_exit
 236 and
 237 .Fn err_set_file
 238 functions first appeared in
 239 .Fx 2.1 .
 240 The
 241 .Fn errc
 242 and
 243 .Fn warnc
 244 functions first appeared in
 245 .Fx 3.0 .