1.\" Copyright (c) 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)err.3 8.1 (Berkeley) 6/9/93 33.\" $FreeBSD: src/lib/libc/gen/err.3,v 1.11.2.6 2001/12/14 18:33:51 ru Exp $ 34.\" $DragonFly: src/lib/libc/gen/err.3,v 1.3 2007/06/30 19:03:52 swildner Exp $ 35.\" 36.Dd March 6, 1999 37.Dt ERR 3 38.Os 39.Sh NAME 40.Nm err , 41.Nm verr , 42.Nm errc , 43.Nm verrc , 44.Nm errx , 45.Nm verrx , 46.Nm warn , 47.Nm vwarn , 48.Nm warnc , 49.Nm vwarnc , 50.Nm warnx , 51.Nm vwarnx , 52.Nm err_set_exit , 53.Nm err_set_file 54.Nd formatted error messages 55.Sh LIBRARY 56.Lb libc 57.Sh SYNOPSIS 58.In err.h 59.Ft void 60.Fn err "int eval" "const char *fmt" "..." 61.Ft void 62.Fn err_set_exit "void (*exitf)(int)" 63.Ft void 64.Fn err_set_file "void *vfp" 65.Ft void 66.Fn errc "int eval" "int code" "const char *fmt" "..." 67.Ft void 68.Fn errx "int eval" "const char *fmt" "..." 69.Ft void 70.Fn warn "const char *fmt" "..." 71.Ft void 72.Fn warnc "int code" "const char *fmt" "..." 73.Ft void 74.Fn warnx "const char *fmt" "..." 75.In stdarg.h 76.Ft void 77.Fn verr "int eval" "const char *fmt" "va_list args" 78.Ft void 79.Fn verrc "int eval" "int code" "const char *fmt" "va_list args" 80.Ft void 81.Fn verrx "int eval" "const char *fmt" "va_list args" 82.Ft void 83.Fn vwarn "const char *fmt" "va_list args" 84.Ft void 85.Fn vwarnc "int code" "const char *fmt" "va_list args" 86.Ft void 87.Fn vwarnx "const char *fmt" "va_list args" 88.Sh DESCRIPTION 89The 90.Fn err 91and 92.Fn warn 93family of functions display a formatted error message on the standard 94error output, or on another file specified using the 95.Fn err_set_file 96function. 97In all cases, the last component of the program name, a colon character, 98and a space are output. 99If the 100.Fa fmt 101argument is not NULL, the 102.Xr printf 3 103-like formatted error message is output. 104The output is terminated by a newline character. 105.Pp 106The 107.Fn err , 108.Fn errc , 109.Fn verr , 110.Fn verrc , 111.Fn warn , 112.Fn warnc , 113.Fn vwarn , 114and 115.Fn vwarnc 116functions append an error message obtained from 117.Xr strerror 3 118based on a code or the global variable 119.Va errno , 120preceded by another colon and space unless the 121.Fa fmt 122argument is 123.Dv NULL . 124.Pp 125In the case of the 126.Fn errc , 127.Fn verrc , 128.Fn warnc , 129and 130.Fn vwarnc 131functions, 132the 133.Fa code 134argument is used to look up the error message. 135.Pp 136The 137.Fn err , 138.Fn verr , 139.Fn warn , 140and 141.Fn vwarn 142functions use the global variable 143.Va errno 144to look up the error message. 145.Pp 146The 147.Fn errx 148and 149.Fn warnx 150functions do not append an error message. 151.Pp 152The 153.Fn err , 154.Fn verr , 155.Fn errc , 156.Fn verrc , 157.Fn errx , 158and 159.Fn verrx 160functions do not return, but exit with the value of the argument 161.Fa eval . 162The 163.Fn err_set_exit 164function can be used to specify a function which is called before 165.Xr exit 3 166to perform any necessary cleanup; passing a null function pointer for 167.Va exitf 168resets the hook to do nothing. 169The 170.Fn err_set_file 171function sets the output stream used by the other functions. 172Its 173.Fa vfp 174argument must be either a pointer to an open stream 175(possibly already converted to void *) 176or a null pointer 177(in which case the output stream is set to standard error). 178.Sh EXAMPLES 179Display the current 180.Va errno 181information string and exit: 182.Bd -literal -offset indent 183if ((p = malloc(size)) == NULL) 184 err(1, NULL); 185if ((fd = open(file_name, O_RDONLY, 0)) == -1) 186 err(1, "%s", file_name); 187.Ed 188.Pp 189Display an error message and exit: 190.Bd -literal -offset indent 191if (tm.tm_hour < START_TIME) 192 errx(1, "too early, wait until %s", start_time_string); 193.Ed 194.Pp 195Warn of an error: 196.Bd -literal -offset indent 197if ((fd = open(raw_device, O_RDONLY, 0)) == -1) 198 warnx("%s: %s: trying the block device", 199 raw_device, strerror(errno)); 200if ((fd = open(block_device, O_RDONLY, 0)) == -1) 201 err(1, "%s", block_device); 202.Ed 203.Pp 204Warn of an error without using the global variable 205.Va errno : 206.Bd -literal -offset indent 207error = my_function(); /* returns a value from <errno.h> */ 208if (error != 0) 209 warnc(error, "my_function"); 210.Ed 211.Sh SEE ALSO 212.Xr exit 3 , 213.Xr printf 3 , 214.Xr strerror 3 215.Sh HISTORY 216The 217.Fn err 218and 219.Fn warn 220functions first appeared in 221.Bx 4.4 . 222The 223.Fn err_set_exit 224and 225.Fn err_set_file 226functions first appeared in 227.Fx 2.1 . 228The 229.Fn errc 230and 231.Fn warnc 232functions first appeared in 233.Fx 3.0 . 234