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