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$ 34.\" 35.Dd Mar 6, 1999 36.Dt ERR 3 37.Os BSD 4 38.Sh NAME 39.Nm err , 40.Nm verr , 41.Nm errc , 42.Nm verrc , 43.Nm errx , 44.Nm verrx , 45.Nm warn , 46.Nm vwarn , 47.Nm warnc , 48.Nm vwarnc , 49.Nm warnx , 50.Nm vwarnx , 51.Nm err_set_exit , 52.Nm err_set_file 53.Nd formatted error messages 54.Sh SYNOPSIS 55.Fd #include <err.h> 56.Ft void 57.Fn err "int eval" "const char *fmt" "..." 58.Ft void 59.Fn err_set_exit "void (*exitf)(int)" 60.Ft void 61.Fn err_set_file "void *vfp" 62.Ft void 63.Fn errc "int eval" "int code" "const char *fmt" "..." 64.Ft void 65.Fn errx "int eval" "const char *fmt" "..." 66.Ft void 67.Fn warn "const char *fmt" "..." 68.Ft void 69.Fn warnc "int code" "const char *fmt" "..." 70.Ft void 71.Fn warnx "const char *fmt" "..." 72.Fd #include <stdarg.h> 73.Ft void 74.Fn verr "int eval" "const char *fmt" "va_list args" 75.Ft void 76.Fn verrc "int eval" "int code" "const char *fmt" "va_list args" 77.Ft void 78.Fn verrx "int eval" "const char *fmt" "va_list args" 79.Ft void 80.Fn vwarn "const char *fmt" "va_list args" 81.Ft void 82.Fn vwarnc "int code" "const char *fmt" "va_list args" 83.Ft void 84.Fn vwarnx "const char *fmt" "va_list args" 85.Sh DESCRIPTION 86The 87.Fn err 88and 89.Fn warn 90family of functions display a formatted error message on the standard 91error output, or on another file specified using the 92.Fn err_set_file 93function. 94In all cases, the last component of the program name, a colon character, 95and a space are output. 96If the 97.Va fmt 98argument is not NULL, the formatted error message is output. 99In the case of the 100.Fn errc , 101.Fn verrc , 102.Fn warnc , 103and 104.Fn vwarnc 105functions, 106the error message string affiliated with the 107.Va code 108argument is also output, 109preceded by another colon and space if necessary. 110In all cases, the output is followed by a newline character. 111.Pp 112The 113.Fn err , 114.Fn verr , 115.Fn warn , 116and 117.Fn vwarn 118functions use the global variable 119.Va errno 120rather than the 121.Va code 122argument of the 123.Fn errc 124family 125.Pp 126The 127.Fn err , 128.Fn verr , 129.Fn errc , 130.Fn verrc , 131.Fn errx , 132and 133.Fn verrx 134functions do not return, but exit with the value of the argument 135.Fa eval . 136The 137.Fn err_set_exit 138function can be used to specify a function which is called before 139.Xr exit 3 140to perform any necessary cleanup; passing a null function pointer for 141.Va exitf 142resets the hook to do nothing. 143The 144.Fn err_set_file 145function sets the output stream used by the other functions. 146Its 147.Va vfp 148argument must be either a pointer to an open stream 149(possibly already converted to void *) 150or a null pointer 151(in which case the output stream is set to standard error). 152.Sh EXAMPLES 153Display the current errno information string and exit: 154.Bd -literal -offset indent 155if ((p = malloc(size)) == NULL) 156 err(1, NULL); 157if ((fd = open(file_name, O_RDONLY, 0)) == -1) 158 err(1, "%s", file_name); 159.Ed 160.Pp 161Display an error message and exit: 162.Bd -literal -offset indent 163if (tm.tm_hour < START_TIME) 164 errx(1, "too early, wait until %s", start_time_string); 165.Ed 166.Pp 167Warn of an error: 168.Bd -literal -offset indent 169if ((fd = open(raw_device, O_RDONLY, 0)) == -1) 170 warnx("%s: %s: trying the block device", 171 raw_device, strerror(errno)); 172if ((fd = open(block_device, O_RDONLY, 0)) == -1) 173 err(1, "%s", block_device); 174.Ed 175.Pp 176Warn of an error without using the global variable 177.Va errno : 178.Bd -literal -offset indent 179error = my_function(); /* returns a value from <errno.h> */ 180if (error != 0) 181 warnc(error, "my_function"); 182.Ed 183.Sh SEE ALSO 184.Xr exit 3 , 185.Xr strerror 3 186.Sh HISTORY 187The 188.Fn err 189and 190.Fn warn 191functions first appeared in 192.Bx 4.4 . 193The 194.Fn err_set_exit 195and 196.Fn err_set_file 197functions first appeared in 198.Fx 2.1 . 199The 200.Fn errc 201and 202.Fn warnc 203functions first appeared in 204.Fx 3.0 . 205