1.\" The contents of this file are subject to the terms of the Common 2.\" Development and Distribution License (the "License"). You may not use 3.\" this file except in compliance with the License. 4.\" 5.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or 6.\" http://www.opensolaris.org/os/licensing. See the License for the 7.\" specific language governing permissions and limitations under the 8.\" License. 9.\" 10.\" When distributing Covered Code, include this CDDL HEADER in each file 11.\" and include the License file at usr/src/OPENSOLARIS.LICENSE. If 12.\" applicable, add the following below this CDDL HEADER, with the fields 13.\" enclosed by brackets "[]" replaced with your own identifying 14.\" information: Portions Copyright [yyyy] [name of copyright owner] 15.\" 16.\" Copyright (c) 1996-2001 Wolfram Schneider. Berlin. 17.\" Copyright (c) 1993-1995 Berkeley Software Design, Inc. 18.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. 19.\" Copyright 2014 Nexenta Systems, Inc. All Rights Reserved. 20.\" Copyright 2022 OmniOS Community Edition (OmniOSce) Association. 21.\" 22.Dd November 15, 2022 23.Dt ERR 3C 24.Os 25.Sh NAME 26.Nm err , 27.Nm errc , 28.Nm errx , 29.Nm warn , 30.Nm warnc , 31.Nm warnx , 32.Nm verr , 33.Nm verrc , 34.Nm verrx , 35.Nm vwarn , 36.Nm vwarnc , 37.Nm vwarnx 38.Nd formatted error messages 39.Sh SYNOPSIS 40.In err.h 41.Ft void 42.Fo err 43.Fa "int eval" 44.Fa "const char *fmt" 45.Fa "..." 46.Fc 47.Ft void 48.Fo errc 49.Fa "int eval" 50.Fa "int code" 51.Fa "const char *fmt" 52.Fa "..." 53.Fc 54.Ft void 55.Fo errx 56.Fa "int eval" 57.Fa "const char *fmt" 58.Fa "..." 59.Fc 60.Ft void 61.Fo warn 62.Fa "const char *fmt" 63.Fa "..." 64.Fc 65.Ft void 66.Fo warnc 67.Fa "int code" 68.Fa "const char *fmt" 69.Fa "..." 70.Fc 71.Ft void 72.Fo warnx 73.Fa "const char *fmt" 74.Fa "..." 75.Fc 76.Ft void 77.Fo verr 78.Fa "int eval" 79.Fa "const char *fmt" 80.Fa "va_list args" 81.Fc 82.Ft void 83.Fo verrc 84.Fa "int eval" 85.Fa "int code" 86.Fa "const char *fmt" 87.Fa "va_list args" 88.Fc 89.Ft void 90.Fo verrx 91.Fa "int eval" 92.Fa "const char *fmt" 93.Fa "va_list args" 94.Fc 95.Ft void 96.Fo vwarn 97.Fa "const char *fmt" 98.Fa "va_list args" 99.Fc 100.Ft void 101.Fo vwarnc 102.Fa "int code" 103.Fa "const char *fmt" 104.Fa "va_list args" 105.Fc 106.Ft void 107.Fo vwarnx 108.Fa "const char *fmt" 109.Fa "va_list args" 110.Fc 111.Sh DESCRIPTION 112The 113.Fn err 114and 115.Fn warn 116family of functions display a formatted error message to standard error. 117In all cases, the last component of the program name, followed by a colon 118character and a space, are output. 119If the 120.Ar fmt 121argument is not 122.Dv NULL , 123the formatted error message is output. 124.Pp 125In the case of the 126.Fn err , 127.Fn errc , 128.Fn warn , 129.Fn warnc , 130.Fn verr , 131.Fn verrc , 132.Fn vwarn 133and 134.Fn vwarnc 135functions, an error message obtained from 136.Xr strerror 3C 137is output next, preceded by a colon character and a space if 138.Ar fmt 139is not 140.Dv NULL . 141The 142.Fn err , 143.Fn warn , 144.Fn verr 145and 146.Fn vwarn 147functions produce the error string affiliated with the current value of the 148global variable 149.Va errno . 150The 151.Fn errc , 152.Fn warnc , 153.Fn verrc 154and 155.Fn vwarnc 156functions use the provided 157.Ar code 158value to look up the error message. 159.Pp 160The 161.Fn errx , 162.Fn verrx , 163.Fn warnx 164and 165.Fn vwarnx 166functions will not output this error message string. 167.Pp 168In all cases, the output is followed by a newline character. 169.Pp 170The 171.Fn err , 172.Fn errc , 173.Fn errx , 174.Fn verr , 175.Fn verrc 176and 177.Fn verrx 178functions do not return, but instead cause the program to terminate with the 179status value given by the 180.Ar eval 181argument. 182.Sh EXAMPLES 183.Sy Example 1 184Display the current 185.Va errno 186information string and terminate with status indicating failure. 187.Bd -literal -offset indent 188#include <err.h> 189\&... 190if ((p = malloc(size)) == NULL) 191 err(EXIT_FAILURE, NULL); 192if ((fd = open(file_name, O_RDONLY, 0)) == -1) 193 err(EXIT_FAILURE, "%s", file_name); 194.Ed 195.Pp 196.Sy Example 2 197Display an error message and terminate with status indicating failure. 198.Bd -literal -offset indent 199if (tm.tm_hour < START_TIME) 200 errx(EXIT_FAILURE, "wait until %s", start_time_string); 201.Ed 202.Pp 203.Sy Example 3 204Warn of an error. 205.Bd -literal -offset indent 206if ((fd = open(raw_device, O_RDONLY, 0)) == -1) { 207 warnx("%s: %s: trying the block device", 208 raw_device, strerror(errno)); 209} 210if ((fd = open(block_device, O_RDONLY, 0)) == -1) 211 warn("%s", block_device); 212.Ed 213.Pp 214.Sy Example 4 215Warn of an error using a custom error code 216.Bd -literal -offset indent 217int error = function_returning_error_code(); 218if (error != 0) 219 warnc(error, "%s", "function did not succeed"); 220.Ed 221.Sh WARNINGS 222It is important never to pass a string with user-supplied data as a format 223without using 224.Sq %s . 225An attacker can put format specifiers in the string to mangle the stack, 226leading to a possible security hole. 227This holds true even if the string has been built by hand using a function 228like 229.Xr snprintf 3C , 230as the resulting string can still contain user-supplied conversion specifiers 231for later interpolation by the 232.Fn err 233and 234.Fn warn 235functions. 236.Pp 237Always be sure to use the proper secure idiom: 238.Bd -literal -offset indent 239err(1, "%s", string); 240.Ed 241.Sh INTERFACE STABILITY 242.Sy Committed 243.Sh MT-LEVEL 244.Sy MT-Safe with Exceptions 245.Pp 246These functions are safe to use in multithreaded applications as long as 247.Xr setlocale 3C 248is not being called to change the locale. 249.Sh SEE ALSO 250.Xr exit 3C , 251.Xr getexecname 3C , 252.Xr setlocale 3C , 253.Xr strerror 3C , 254.Xr attributes 7 255.Sh STANDARDS 256The functions described in this man page are 257.Bx 258extensions and should not be used in portable code. 259