1.\" $NetBSD: err.3,v 1.23 2023/01/05 15:13:57 kre 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 January 5, 2023 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. 84In all cases, the last component of the program name, a colon character, 85and a space are output. 86If the 87.Fa fmt 88argument is not 89.Dv NULL , 90the formatted error message is output. 91In the case of the 92.Fn err , 93.Fn verr , 94.Fn warn , 95and 96.Fn vwarn 97functions, the error message string affiliated with the current value of 98the global variable 99.Va errno 100is output next, preceded by a colon character and a space if 101.Fa fmt 102is not 103.Dv NULL . 104In all cases, the output is followed by a newline character. 105The 106.Fn errc , 107.Fn verrc , 108.Fn warnc , 109and 110.Fn vwarnc 111functions take an additional 112.Ar code 113argument to be used as the error number instead of using the global 114.Va errno 115variable. 116The 117.Fn errx , 118.Fn verrx , 119.Fn warnx , 120and 121.Fn vwarnx 122functions will not output this error message string. 123.Pp 124The 125.Fn err , 126.Fn verr , 127.Fn errc , 128.Fn verrc , 129.Fn errx , 130and 131.Fn verrx 132functions do not return, but instead cause the program to terminate 133with the status value given by the argument 134.Fa status . 135It is often appropriate to use the value 136.Dv EXIT_FAILURE , 137defined in 138.In stdlib.h , 139as the 140.Fa status 141argument given to these functions. 142.Sh EXAMPLES 143Display the current 144.Va errno 145information string and terminate with status indicating failure: 146.Bd -literal -offset indent 147if ((p = malloc(size)) == NULL) 148 err(EXIT_FAILURE, NULL); 149if ((fd = open(file_name, O_RDONLY, 0)) == -1) 150 err(EXIT_FAILURE, "%s", file_name); 151.Ed 152.Pp 153Display an error message and terminate with status indicating failure: 154.Bd -literal -offset indent 155if (tm.tm_hour < START_TIME) 156 errx(EXIT_FAILURE, "too early, wait until %s", 157 start_time_string); 158.Ed 159.Pp 160Warn of an error: 161.Bd -literal -offset indent 162if ((fd = open(raw_device, O_RDONLY, 0)) == -1) 163 warnx("%s: %s: trying the block device", 164 raw_device, strerror(errno)); 165if ((fd = open(block_device, O_RDONLY, 0)) == -1) 166 warn("%s", block_device); 167.Ed 168.Sh SEE ALSO 169.Xr exit 3 , 170.Xr getprogname 3 , 171.Xr strerror 3 172.Sh HISTORY 173The 174.Fn err 175and 176.Fn warn 177functions first appeared in 178.Bx 4.4 . 179The 180.Fn errc 181and 182.Fn warnc 183functions first appeared in 184.Fx 3.0 185and 186.Nx 7.0 . 187.Sh CAVEATS 188It is important never to pass a string with user-supplied data as a 189format without using 190.Ql %s . 191An attacker can put format specifiers in the string to mangle your stack, 192leading to a possible security hole. 193This holds true even if you have built the string 194.Dq by hand 195using a function like 196.Fn snprintf , 197as the resulting string may still contain user-supplied conversion specifiers 198for later interpolation by the 199.Fn err 200and 201.Fn warn 202functions. 203.Pp 204Always be sure to use the proper secure idiom: 205.Bd -literal -offset indent 206err(1, "%s", string); 207.Ed 208