man3/err.3

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