1.\" $NetBSD: err.3,v 1.24 2024/02/02 21:16:41 jkoshy Exp $ 2.\" 3.\" Copyright (c) 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)err.3 8.1 (Berkeley) 6/9/93 31.\" 32.Dd February 2, 2024 33.Dt ERR 3 34.Os 35.Sh NAME 36.Nm err , 37.Nm verr , 38.Nm errx , 39.Nm verrx , 40.Nm errc , 41.Nm verrc , 42.Nm warn , 43.Nm vwarn , 44.Nm warnx , 45.Nm vwarnx , 46.Nm warnc , 47.Nm vwarnc 48.Nd formatted error messages 49.Sh LIBRARY 50.Lb libc 51.Sh SYNOPSIS 52.In err.h 53.Ft void 54.Fn err "int status" "const char *fmt" "..." 55.Ft void 56.Fn verr "int status" "const char *fmt" "va_list args" 57.Ft void 58.Fn errx "int status" "const char *fmt" "..." 59.Ft void 60.Fn verrx "int status" "const char *fmt" "va_list args" 61.Ft void 62.Fn errc "int status" "int code" "const char *fmt" "..." 63.Ft void 64.Fn verrc "int status" "int code" "const char *fmt" "va_list args" 65.Ft void 66.Fn warn "const char *fmt" "..." 67.Ft void 68.Fn vwarn "const char *fmt" "va_list args" 69.Ft void 70.Fn warnx "const char *fmt" "..." 71.Ft void 72.Fn vwarnx "const char *fmt" "va_list args" 73.Ft void 74.Fn warnc "int code" "const char *fmt" "..." 75.Ft void 76.Fn vwarnc "int code" "const char *fmt" "va_list args" 77.Sh DESCRIPTION 78The 79.Fn err 80and 81.Fn warn 82family of functions display a formatted error message on the standard 83error output. 84.Pp 85In all cases these functions output the last component of the program name, 86a colon character, and a space. 87If the 88.Fa fmt 89argument is not 90.Dv NULL , 91it is used as a 92.Xr printf 3 Ns 93-like format specification for the error message. 94.Pp 95In the case of the 96.Fn err , 97.Fn verr , 98.Fn warn , 99and 100.Fn vwarn 101functions, an additional error message string affiliated with the current 102value of the global variable 103.Va errno 104is output next, preceded by a colon character and a space if 105.Fa fmt 106is not 107.Dv NULL . 108The 109.Fn errc , 110.Fn verrc , 111.Fn warnc , 112and 113.Fn vwarnc 114functions take an additional 115.Ar code 116argument to be used as the error number instead of using the global 117.Va errno 118variable. 119The 120.Fn errx , 121.Fn verrx , 122.Fn warnx , 123and 124.Fn vwarnx 125functions will not output an additional error message string. 126.Pp 127In all cases, the output is terminated by a newline character. 128.Pp 129The 130.Fn err , 131.Fn verr , 132.Fn errc , 133.Fn verrc , 134.Fn errx , 135and 136.Fn verrx 137functions do not return, but instead cause the program to terminate 138with the status value given by the argument 139.Fa status . 140It is often appropriate to use the value 141.Dv EXIT_FAILURE , 142defined in 143.In stdlib.h , 144as the 145.Fa status 146argument given to these functions. 147.Sh EXAMPLES 148Display the current 149.Va errno 150information string and terminate with status indicating failure: 151.Bd -literal -offset indent 152if ((p = malloc(size)) == NULL) 153 err(EXIT_FAILURE, NULL); 154if ((fd = open(file_name, O_RDONLY, 0)) == -1) 155 err(EXIT_FAILURE, "%s", file_name); 156.Ed 157.Pp 158Display an error message and terminate with status indicating failure: 159.Bd -literal -offset indent 160if (tm.tm_hour < START_TIME) 161 errx(EXIT_FAILURE, "too early, wait until %s", 162 start_time_string); 163.Ed 164.Pp 165Warn of an error: 166.Bd -literal -offset indent 167if ((fd = open(raw_device, O_RDONLY, 0)) == -1) 168 warnx("%s: %s: trying the block device", 169 raw_device, strerror(errno)); 170if ((fd = open(block_device, O_RDONLY, 0)) == -1) 171 warn("%s", block_device); 172.Ed 173.Sh SEE ALSO 174.Xr exit 3 , 175.Xr getprogname 3 , 176.Xr printf 3 , 177.Xr strerror 3 178.Sh HISTORY 179The 180.Fn err 181and 182.Fn warn 183functions first appeared in 184.Bx 4.4 . 185The 186.Fn errc 187and 188.Fn warnc 189functions first appeared in 190.Fx 3.0 191and 192.Nx 7.0 . 193.Sh CAVEATS 194It is important never to pass a string with user-supplied data as a 195format without using 196.Ql %s . 197An attacker can put format specifiers in the string to mangle your stack, 198leading to a possible security hole. 199This holds true even if you have built the string 200.Dq by hand 201using a function like 202.Fn snprintf , 203as the resulting string may still contain user-supplied conversion specifiers 204for later interpolation by the 205.Fn err 206and 207.Fn warn 208functions. 209.Pp 210Always be sure to use the proper secure idiom: 211.Bd -literal -offset indent 212err(1, "%s", string); 213.Ed 214