original/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 2013-12-30 "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 .sp
  46 .BI "void err(int " eval ", const char *" fmt ", ...);"
  47 .sp
  48 .BI "void errx(int " eval ", const char *" fmt ", ...);"
  49 .sp
  50 .BI "void warn(const char *" fmt ", ...);"
  51 .sp
  52 .BI "void warnx(const char *" fmt ", ...);"
  53 .sp
  54 .B #include <stdarg.h>
  55 .sp
  56 .BI "void verr(int " eval ", const char *" fmt ", va_list " args );
  57 .sp
  58 .BI "void verrx(int " eval ", const char *" fmt ", va_list " args );
  59 .sp
  60 .BI "void vwarn(const char *" fmt ", va_list " args );
  61 .sp
  62 .BI "void vwarnx(const char *" fmt ", va_list " args );
  63 .fi
  64 .SH DESCRIPTION
  65 The
  66 .BR err ()
  67 and
  68 .BR warn ()
  69 family of functions display a formatted error message on the standard
  70 error output.
  71 In all cases, the last component of the program name, a colon character,
  72 and a space are output.
  73 If the
  74 .I fmt
  75 argument is not NULL, the
  76 .BR printf (3)-like
  77 formatted error message is output.
  78 The output is terminated by a newline character.
  79 .PP
  80 The
  81 .BR err (),
  82 .BR verr (),
  83 .BR warn (),
  84 and
  85 .BR vwarn ()
  86 functions append an error message obtained from
  87 .BR strerror (3)
  88 based on the global variable
  89 .IR errno ,
  90 preceded by another colon and space unless the
  91 .I fmt
  92 argument is
  93 NULL.
  94 .PP
  95 The
  96 .BR errx ()
  97 and
  98 .BR warnx ()
  99 functions do not append an error message.
 100 .PP
 101 The
 102 .BR err (),
 103 .BR verr (),
 104 .BR errx (),
 105 and
 106 .BR verrx ()
 107 functions do not return, but exit with the value of the argument
 108 .IR eval .
 109 .SH CONFORMING TO
 110 These functions are nonstandard BSD extensions.
 111 .\" .SH HISTORY
 112 .\" The
 113 .\" .BR err ()
 114 .\" and
 115 .\" .BR warn ()
 116 .\" functions first appeared in
 117 .\" 4.4BSD.
 118 .SH EXAMPLE
 119 Display the current
 120 .I errno
 121 information string and exit:
 122 .in +4n
 123 .nf
 124
 125 p = malloc(size);
 126 if (p == NULL)
 127     err(1, NULL);
 128 fd = open(file_name, O_RDONLY, 0);
 129 if (fd == \-1)
 130     err(1, "%s", file_name);
 131 .fi
 132 .in
 133 .PP
 134 Display an error message and exit:
 135 .in +4n
 136 .nf
 137
 138 if (tm.tm_hour < START_TIME)
 139     errx(1, "too early, wait until %s", start_time_string);
 140 .fi
 141 .in
 142 .PP
 143 Warn of an error:
 144 .in +4n
 145 .nf
 146
 147 fd = open(raw_device, O_RDONLY, 0);
 148 if (fd == \-1)
 149     warnx("%s: %s: trying the block device",
 150             raw_device, strerror(errno));
 151 fd = open(block_device, O_RDONLY, 0);
 152 if (fd == \-1)
 153     err(1, "%s", block_device);
 154 .fi
 155 .in
 156 .SH SEE ALSO
 157 .BR error (3),
 158 .BR exit (3),
 159 .BR perror (3),
 160 .BR printf (3),
 161 .BR strerror (3)
 162 .SH COLOPHON
 163 This page is part of release 3.67 of the Linux
 164 .I man-pages
 165 project.
 166 A description of the project,
 167 information about reporting bugs,
 168 and the latest version of this page,
 169 can be found at
 170 \%http://www.kernel.org/doc/man\-pages/.