man3/err.3

   1 .\" Copyright (c) 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     From: @(#)err.3 8.1 (Berkeley) 6/9/93
  35 .\" $FreeBSD: src/lib/libc/gen/err.3,v 1.11.2.5 2001/08/17 15:42:32 ru Exp $
  36 .\"
  37 .\" 2011-09-10, mtk, Converted from mdoc to man macros
  38 .\"
  39 .TH ERR 3 2017-09-15 "Linux" "Linux Programmer's Manual"
  40 .SH NAME
  41 err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages
  42 .SH SYNOPSIS
  43 .nf
  44 .B #include <err.h>
  45 .PP
  46 .BI "void err(int " eval ", const char *" fmt ", ...);"
  47 .PP
  48 .BI "void errx(int " eval ", const char *" fmt ", ...);"
  49 .PP
  50 .BI "void warn(const char *" fmt ", ...);"
  51 .PP
  52 .BI "void warnx(const char *" fmt ", ...);"
  53
  54 .B #include <stdarg.h>
  55 .PP
  56 .BI "void verr(int " eval ", const char *" fmt ", va_list " args );
  57 .PP
  58 .BI "void verrx(int " eval ", const char *" fmt ", va_list " args );
  59 .PP
  60 .BI "void vwarn(const char *" fmt ", va_list " args );
  61 .PP
  62 .BI "void vwarnx(const char *" fmt ", va_list " args );
  63 .fi
  64 .SH DESCRIPTION
  65 The
  66 .BR err ()
  67 and
  68 .BR warn ()
  69 family of functions display a formatted error message on the standard
  70 error output.
  71 In all cases, the last component of the program name, a colon character,
  72 and a space are output.
  73 If the
  74 .I fmt
  75 argument is not NULL, the
  76 .BR printf (3)-like
  77 formatted error message is output.
  78 The output is terminated by a newline character.
  79 .PP
  80 The
  81 .BR err (),
  82 .BR verr (),
  83 .BR warn (),
  84 and
  85 .BR vwarn ()
  86 functions append an error message obtained from
  87 .BR strerror (3)
  88 based on the global variable
  89 .IR errno ,
  90 preceded by another colon and space unless the
  91 .I fmt
  92 argument is
  93 NULL.
  94 .PP
  95 The
  96 .BR errx ()
  97 and
  98 .BR warnx ()
  99 functions do not append an error message.
 100 .PP
 101 The
 102 .BR err (),
 103 .BR verr (),
 104 .BR errx (),
 105 and
 106 .BR verrx ()
 107 functions do not return, but exit with the value of the argument
 108 .IR eval .
 109 .SH ATTRIBUTES
 110 For an explanation of the terms used in this section, see
 111 .BR attributes (7).
 112 .TS
 113 allbox;
 114 lbw17 lb lb
 115 l l l.
 116 Interface       Attribute       Value
 117 T{
 118 .BR err (),
 119 .BR errx (),
 120 .br
 121 .BR warn (),
 122 .BR warnx (),
 123 .br
 124 .BR verr (),
 125 .BR verrx (),
 126 .br
 127 .BR vwarn (),
 128 .BR vwarnx ()
 129 T}      Thread safety   MT-Safe locale
 130 .TE
 131 .sp 1
 132 .SH CONFORMING TO
 133 These functions are nonstandard BSD extensions.
 134 .\" .SH HISTORY
 135 .\" The
 136 .\" .BR err ()
 137 .\" and
 138 .\" .BR warn ()
 139 .\" functions first appeared in
 140 .\" 4.4BSD.
 141 .SH EXAMPLE
 142 Display the current
 143 .I errno
 144 information string and exit:
 145 .PP
 146 .in +4n
 147 .EX
 148 p = malloc(size);
 149 if (p == NULL)
 150     err(1, NULL);
 151 fd = open(file_name, O_RDONLY, 0);
 152 if (fd == \-1)
 153     err(1, "%s", file_name);
 154 .EE
 155 .in
 156 .PP
 157 Display an error message and exit:
 158 .PP
 159 .in +4n
 160 .EX
 161 if (tm.tm_hour < START_TIME)
 162     errx(1, "too early, wait until %s", start_time_string);
 163 .EE
 164 .in
 165 .PP
 166 Warn of an error:
 167 .PP
 168 .in +4n
 169 .EX
 170 fd = open(raw_device, O_RDONLY, 0);
 171 if (fd == \-1)
 172     warnx("%s: %s: trying the block device",
 173             raw_device, strerror(errno));
 174 fd = open(block_device, O_RDONLY, 0);
 175 if (fd == \-1)
 176     err(1, "%s", block_device);
 177 .EE
 178 .in
 179 .SH SEE ALSO
 180 .BR error (3),
 181 .BR exit (3),
 182 .BR perror (3),
 183 .BR printf (3),
 184 .BR strerror (3)