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