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 .P
  22 .BI "[[noreturn]] void err(int " eval ", const char *" fmt ", ...);"
  23 .BI "[[noreturn]] void errx(int " eval ", const char *" fmt ", ...);"
  24 .P
  25 .BI "void warn(const char *" fmt ", ...);"
  26 .BI "void warnx(const char *" fmt ", ...);"
  27 .P
  28 .B #include <stdarg.h>
  29 .P
  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 .P
  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 .P
  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 .P
  67 The
  68 .BR errx ()
  69 and
  70 .BR warnx ()
  71 functions do not append an error message.
  72 .P
  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 .TS
  85 allbox;
  86 lbx lb lb
  87 l l l.
  88 Interface       Attribute       Value
  89 T{
  90 .na
  91 .nh
  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 .SH STANDARDS
 103 BSD.
 104 .SH HISTORY
 105 .TP
 106 .BR err ()
 107 .TQ
 108 .BR warn ()
 109 4.4BSD.
 110 .SH EXAMPLES
 111 Display the current
 112 .I errno
 113 information string and exit:
 114 .P
 115 .in +4n
 116 .EX
 117 p = malloc(size);
 118 if (p == NULL)
 119     err(EXIT_FAILURE, NULL);
 120 fd = open(file_name, O_RDONLY, 0);
 121 if (fd == \-1)
 122     err(EXIT_FAILURE, "%s", file_name);
 123 .EE
 124 .in
 125 .P
 126 Display an error message and exit:
 127 .P
 128 .in +4n
 129 .EX
 130 if (tm.tm_hour < START_TIME)
 131     errx(EXIT_FAILURE, "too early, wait until %s",
 132             start_time_string);
 133 .EE
 134 .in
 135 .P
 136 Warn of an error:
 137 .P
 138 .in +4n
 139 .EX
 140 fd = open(raw_device, O_RDONLY, 0);
 141 if (fd == \-1)
 142     warnx("%s: %s: trying the block device",
 143             raw_device, strerror(errno));
 144 fd = open(block_device, O_RDONLY, 0);
 145 if (fd == \-1)
 146     err(EXIT_FAILURE, "%s", block_device);
 147 .EE
 148 .in
 149 .SH SEE ALSO
 150 .BR error (3),
 151 .BR exit (3),
 152 .BR perror (3),
 153 .BR printf (3),
 154 .BR strerror (3)