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 2021-03-22 "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 "noreturn void err(int " eval ", const char *" fmt ", ...);"
  47 .BI "noreturn void errx(int " eval ", const char *" fmt ", ...);"
  48 .PP
  49 .BI "void warn(const char *" fmt ", ...);"
  50 .BI "void warnx(const char *" fmt ", ...);"
  51 .PP
  52 .B #include <stdarg.h>
  53 .PP
  54 .BI "noreturn void verr(int " eval ", const char *" fmt ", va_list " args );
  55 .BI "noreturn void verrx(int " eval ", const char *" fmt ", va_list " args );
  56 .PP
  57 .BI "void vwarn(const char *" fmt ", va_list " args );
  58 .BI "void vwarnx(const char *" fmt ", va_list " args );
  59 .fi
  60 .SH DESCRIPTION
  61 The
  62 .BR err ()
  63 and
  64 .BR warn ()
  65 family of functions display a formatted error message on the standard
  66 error output.
  67 In all cases, the last component of the program name, a colon character,
  68 and a space are output.
  69 If the
  70 .I fmt
  71 argument is not NULL, the
  72 .BR printf (3)-like
  73 formatted error message is output.
  74 The output is terminated by a newline character.
  75 .PP
  76 The
  77 .BR err (),
  78 .BR verr (),
  79 .BR warn (),
  80 and
  81 .BR vwarn ()
  82 functions append an error message obtained from
  83 .BR strerror (3)
  84 based on the global variable
  85 .IR errno ,
  86 preceded by another colon and space unless the
  87 .I fmt
  88 argument is
  89 NULL.
  90 .PP
  91 The
  92 .BR errx ()
  93 and
  94 .BR warnx ()
  95 functions do not append an error message.
  96 .PP
  97 The
  98 .BR err (),
  99 .BR verr (),
 100 .BR errx (),
 101 and
 102 .BR verrx ()
 103 functions do not return, but exit with the value of the argument
 104 .IR eval .
 105 .SH ATTRIBUTES
 106 For an explanation of the terms used in this section, see
 107 .BR attributes (7).
 108 .ad l
 109 .nh
 110 .TS
 111 allbox;
 112 lbx lb lb
 113 l l l.
 114 Interface       Attribute       Value
 115 T{
 116 .BR err (),
 117 .BR errx (),
 118 .BR warn (),
 119 .BR warnx (),
 120 .BR verr (),
 121 .BR verrx (),
 122 .BR vwarn (),
 123 .BR vwarnx ()
 124 T}      Thread safety   MT-Safe locale
 125 .TE
 126 .hy
 127 .ad
 128 .sp 1
 129 .SH CONFORMING TO
 130 These functions are nonstandard BSD extensions.
 131 .\" .SH HISTORY
 132 .\" The
 133 .\" .BR err ()
 134 .\" and
 135 .\" .BR warn ()
 136 .\" functions first appeared in
 137 .\" 4.4BSD.
 138 .SH EXAMPLES
 139 Display the current
 140 .I errno
 141 information string and exit:
 142 .PP
 143 .in +4n
 144 .EX
 145 p = malloc(size);
 146 if (p == NULL)
 147     err(EXIT_FAILURE, NULL);
 148 fd = open(file_name, O_RDONLY, 0);
 149 if (fd == \-1)
 150     err(EXIT_FAILURE, "%s", file_name);
 151 .EE
 152 .in
 153 .PP
 154 Display an error message and exit:
 155 .PP
 156 .in +4n
 157 .EX
 158 if (tm.tm_hour < START_TIME)
 159     errx(EXIT_FAILURE, "too early, wait until %s",
 160             start_time_string);
 161 .EE
 162 .in
 163 .PP
 164 Warn of an error:
 165 .PP
 166 .in +4n
 167 .EX
 168 fd = open(raw_device, O_RDONLY, 0);
 169 if (fd == \-1)
 170     warnx("%s: %s: trying the block device",
 171             raw_device, strerror(errno));
 172 fd = open(block_device, O_RDONLY, 0);
 173 if (fd == \-1)
 174     err(EXIT_FAILURE, "%s", block_device);
 175 .EE
 176 .in
 177 .SH SEE ALSO
 178 .BR error (3),
 179 .BR exit (3),
 180 .BR perror (3),
 181 .BR printf (3),
 182 .BR strerror (3)