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 BSD.
 107 .SH HISTORY
 108 .TP
 109 .BR err ()
 110 .TQ
 111 .BR warn ()
 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)