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.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" From: @(#)err.3 8.1 (Berkeley) 6/9/93 29.\" $FreeBSD$ 30.\" 31.Dd June 25, 2015 32.Dt ERR 3 33.Os 34.Sh NAME 35.Nm err , 36.Nm verr , 37.Nm errc , 38.Nm verrc , 39.Nm errx , 40.Nm verrx , 41.Nm warn , 42.Nm vwarn , 43.Nm warnc , 44.Nm vwarnc , 45.Nm warnx , 46.Nm vwarnx , 47.Nm err_set_exit , 48.Nm err_set_exit_b , 49.Nm err_set_file 50.Nd formatted error messages 51.Sh LIBRARY 52.Lb libc 53.Sh SYNOPSIS 54.In err.h 55.Ft void 56.Fn err "int eval" "const char *fmt" "..." 57.Ft void 58.Fn err_set_exit "void (*exitfunc)(int)" 59.Ft void 60.Fn err_set_exit_b "void (^exitblock)(int)" 61.Ft void 62.Fn err_set_file "void *vfp" 63.Ft void 64.Fn errc "int eval" "int code" "const char *fmt" "..." 65.Ft void 66.Fn errx "int eval" "const char *fmt" "..." 67.Ft void 68.Fn warn "const char *fmt" "..." 69.Ft void 70.Fn warnc "int code" "const char *fmt" "..." 71.Ft void 72.Fn warnx "const char *fmt" "..." 73.In stdarg.h 74.Ft void 75.Fn verr "int eval" "const char *fmt" "va_list args" 76.Ft void 77.Fn verrc "int eval" "int code" "const char *fmt" "va_list args" 78.Ft void 79.Fn verrx "int eval" "const char *fmt" "va_list args" 80.Ft void 81.Fn vwarn "const char *fmt" "va_list args" 82.Ft void 83.Fn vwarnc "int code" "const char *fmt" "va_list args" 84.Ft void 85.Fn vwarnx "const char *fmt" "va_list args" 86.Sh DESCRIPTION 87The 88.Fn err 89and 90.Fn warn 91family of functions display a formatted error message on the standard 92error output, or on another file specified using the 93.Fn err_set_file 94function. 95In all cases, the last component of the program name, a colon character, 96and a space are output. 97If the 98.Fa fmt 99argument is not NULL, the 100.Xr printf 3 Ns 101-like formatted error message is output. 102The output is terminated by a newline character. 103.Pp 104The 105.Fn err , 106.Fn errc , 107.Fn verr , 108.Fn verrc , 109.Fn warn , 110.Fn warnc , 111.Fn vwarn , 112and 113.Fn vwarnc 114functions append an error message obtained from 115.Xr strerror 3 116based on a supplied error code value or the global variable 117.Va errno , 118preceded by another colon and space unless the 119.Fa fmt 120argument is 121.Dv NULL . 122.Pp 123In the case of the 124.Fn errc , 125.Fn verrc , 126.Fn warnc , 127and 128.Fn vwarnc 129functions, 130the 131.Fa code 132argument is used to look up the error message. 133.Pp 134The 135.Fn err , 136.Fn verr , 137.Fn warn , 138and 139.Fn vwarn 140functions use the global variable 141.Va errno 142to look up the error message. 143.Pp 144The 145.Fn errx 146and 147.Fn warnx 148functions do not append an error message. 149.Pp 150The 151.Fn err , 152.Fn verr , 153.Fn errc , 154.Fn verrc , 155.Fn errx , 156and 157.Fn verrx 158functions do not return, but exit with the value of the argument 159.Fa eval . 160It is recommended that the standard values defined in 161.Xr sysexits 3 162be used for the value of 163.Fa eval . 164The 165.Fn err_set_exit 166function can be used to specify a function which is called before 167.Xr exit 3 168to perform any necessary cleanup. 169Passing a null function pointer for 170.Va exitfunc 171resets the hook to do nothing. 172The 173.Fn err_set_exit_b 174function is like 175.Fn err_set_exit , 176except it takes the block pointer, 177.Va exitblock , 178instead of a function pointer. 179Note that the 180.Fn Block_copy 181function is used by 182.Fn err_set_exit_b 183to make a copy in case the block is freed or goes out of scope. 184The 185.Fn err_set_file 186function sets the output stream used by the other functions. 187Its 188.Fa vfp 189argument must be either a pointer to an open stream 190(possibly already converted to void *) 191or a null pointer 192(in which case the output stream is set to standard error). 193.Sh EXAMPLES 194Display the current errno information string and exit: 195.Bd -literal -offset indent 196if ((p = malloc(size)) == NULL) 197 err(EX_OSERR, NULL); 198if ((fd = open(file_name, O_RDONLY, 0)) == -1) 199 err(EX_NOINPUT, "%s", file_name); 200.Ed 201.Pp 202Display an error message and exit: 203.Bd -literal -offset indent 204if (tm.tm_hour < START_TIME) 205 errx(EX_DATAERR, "too early, wait until %s", 206 start_time_string); 207.Ed 208.Pp 209Warn of an error: 210.Bd -literal -offset indent 211if ((fd = open(raw_device, O_RDONLY, 0)) == -1) 212 warnx("%s: %s: trying the block device", 213 raw_device, strerror(errno)); 214if ((fd = open(block_device, O_RDONLY, 0)) == -1) 215 err(EX_OSFILE, "%s", block_device); 216.Ed 217.Pp 218Warn of an error without using the global variable 219.Va errno : 220.Bd -literal -offset indent 221error = my_function(); /* returns a value from <errno.h> */ 222if (error != 0) 223 warnc(error, "my_function"); 224.Ed 225.Sh SEE ALSO 226.Xr exit 3 , 227.Xr fmtmsg 3 , 228.Xr printf 3 , 229.Xr strerror 3 , 230.Xr sysexits 3 231.Sh STANDARDS 232The 233.Fn err 234and 235.Fn warn 236families of functions are 237.Bx 238extensions. 239As such they should not be used in truly portable code. 240Use 241.Fn strerror 242or similar functions instead. 243.Sh HISTORY 244The 245.Fn err 246and 247.Fn warn 248functions first appeared in 249.Bx 4.4 . 250The 251.Fn err_set_exit 252and 253.Fn err_set_file 254functions first appeared in 255.Fx 2.1 . 256The 257.Fn errc 258and 259.Fn warnc 260functions first appeared in 261.Fx 3.0 . 262The 263.Fn err_set_exit_b 264function first appeared in Mac OS X. This implementation was 265created by Stacey Son for 266.Fx 11.0 . 267