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