man3/err.3

   1 '\" t
   2 .\" Copyright (c) 1993
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\"
   5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   6 .\"
   7 .\"     From: @(#)err.3 8.1 (Berkeley) 6/9/93
   8 .\" $FreeBSD: src/lib/libc/gen/err.3,v 1.11.2.5 2001/08/17 15:42:32 ru Exp $
   9 .\"
  10 .\" 2011-09-10, mtk, Converted from mdoc to man macros
  11 .\"
  12 .TH err 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 err, verr, errx, verrx, warn, vwarn, warnx, vwarnx \- formatted error messages
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <err.h>
  21 .PP
  22 .BI "[[noreturn]] void err(int " eval ", const char *" fmt ", ...);"
  23 .BI "[[noreturn]] void errx(int " eval ", const char *" fmt ", ...);"
  24 .PP
  25 .BI "void warn(const char *" fmt ", ...);"
  26 .BI "void warnx(const char *" fmt ", ...);"
  27 .PP
  28 .B #include <stdarg.h>
  29 .PP
  30 .BI "[[noreturn]] void verr(int " eval ", const char *" fmt ", va_list " args );
  31 .BI "[[noreturn]] void verrx(int " eval ", const char *" fmt ", va_list " args );
  32 .PP
  33 .BI "void vwarn(const char *" fmt ", va_list " args );
  34 .BI "void vwarnx(const char *" fmt ", va_list " args );
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR err ()
  39 and
  40 .BR warn ()
  41 family of functions display a formatted error message on the standard
  42 error output.
  43 In all cases, the last component of the program name, a colon character,
  44 and a space are output.
  45 If the
  46 .I fmt
  47 argument is not NULL, the
  48 .BR printf (3)-like
  49 formatted error message is output.
  50 The output is terminated by a newline character.
  51 .PP
  52 The
  53 .BR err (),
  54 .BR verr (),
  55 .BR warn (),
  56 and
  57 .BR vwarn ()
  58 functions append an error message obtained from
  59 .BR strerror (3)
  60 based on the global variable
  61 .IR errno ,
  62 preceded by another colon and space unless the
  63 .I fmt
  64 argument is
  65 NULL.
  66 .PP
  67 The
  68 .BR errx ()
  69 and
  70 .BR warnx ()
  71 functions do not append an error message.
  72 .PP
  73 The
  74 .BR err (),
  75 .BR verr (),
  76 .BR errx (),
  77 and
  78 .BR verrx ()
  79 functions do not return, but exit with the value of the argument
  80 .IR eval .
  81 .SH ATTRIBUTES
  82 For an explanation of the terms used in this section, see
  83 .BR attributes (7).
  84 .ad l
  85 .nh
  86 .TS
  87 allbox;
  88 lbx lb lb
  89 l l l.
  90 Interface       Attribute       Value
  91 T{
  92 .BR err (),
  93 .BR errx (),
  94 .BR warn (),
  95 .BR warnx (),
  96 .BR verr (),
  97 .BR verrx (),
  98 .BR vwarn (),
  99 .BR vwarnx ()
 100 T}      Thread safety   MT-Safe locale
 101 .TE
 102 .hy
 103 .ad
 104 .sp 1
 105 .SH STANDARDS
 106 These functions are nonstandard BSD extensions.
 107 .\" .SH HISTORY
 108 .\" The
 109 .\" .BR err ()
 110 .\" and
 111 .\" .BR warn ()
 112 .\" functions first appeared in
 113 .\" 4.4BSD.
 114 .SH EXAMPLES
 115 Display the current
 116 .I errno
 117 information string and exit:
 118 .PP
 119 .in +4n
 120 .EX
 121 p = malloc(size);
 122 if (p == NULL)
 123     err(EXIT_FAILURE, NULL);
 124 fd = open(file_name, O_RDONLY, 0);
 125 if (fd == \-1)
 126     err(EXIT_FAILURE, "%s", file_name);
 127 .EE
 128 .in
 129 .PP
 130 Display an error message and exit:
 131 .PP
 132 .in +4n
 133 .EX
 134 if (tm.tm_hour < START_TIME)
 135     errx(EXIT_FAILURE, "too early, wait until %s",
 136             start_time_string);
 137 .EE
 138 .in
 139 .PP
 140 Warn of an error:
 141 .PP
 142 .in +4n
 143 .EX
 144 fd = open(raw_device, O_RDONLY, 0);
 145 if (fd == \-1)
 146     warnx("%s: %s: trying the block device",
 147             raw_device, strerror(errno));
 148 fd = open(block_device, O_RDONLY, 0);
 149 if (fd == \-1)
 150     err(EXIT_FAILURE, "%s", block_device);
 151 .EE
 152 .in
 153 .SH SEE ALSO
 154 .BR error (3),
 155 .BR exit (3),
 156 .BR perror (3),
 157 .BR printf (3),
 158 .BR strerror (3)