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