1.\" $NetBSD: err.3,v 1.21 2014/01/16 17:21:38 christos 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 16, 2014 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 errx , 128and 129.Fn verrx 130functions do not return, but instead cause the program to terminate 131with the status value given by the argument 132.Fa status . 133It is often appropriate to use the value 134.Dv EXIT_FAILURE , 135defined in 136.In stdlib.h , 137as the 138.Fa status 139argument given to these functions. 140.Sh EXAMPLES 141Display the current 142.Va errno 143information string and terminate with status indicating failure: 144.Bd -literal -offset indent 145if ((p = malloc(size)) == NULL) 146 err(EXIT_FAILURE, NULL); 147if ((fd = open(file_name, O_RDONLY, 0)) == -1) 148 err(EXIT_FAILURE, "%s", file_name); 149.Ed 150.Pp 151Display an error message and terminate with status indicating failure: 152.Bd -literal -offset indent 153if (tm.tm_hour \*[Lt] START_TIME) 154 errx(EXIT_FAILURE, "too early, wait until %s", 155 start_time_string); 156.Ed 157.Pp 158Warn of an error: 159.Bd -literal -offset indent 160if ((fd = open(raw_device, O_RDONLY, 0)) == -1) 161 warnx("%s: %s: trying the block device", 162 raw_device, strerror(errno)); 163if ((fd = open(block_device, O_RDONLY, 0)) == -1) 164 warn("%s", block_device); 165.Ed 166.Sh SEE ALSO 167.Xr exit 3 , 168.Xr getprogname 3 , 169.Xr strerror 3 170.Sh HISTORY 171The 172.Fn err 173and 174.Fn warn 175functions first appeared in 176.Bx 4.4 . 177The 178.Fn errc 179and 180.Fn warnc 181functions first appeared in 182.Fx 3.0 183and 184.Nx 7.0 . 185.Sh CAVEATS 186It is important never to pass a string with user-supplied data as a 187format without using 188.Ql %s . 189An attacker can put format specifiers in the string to mangle your stack, 190leading to a possible security hole. 191This holds true even if you have built the string 192.Dq by hand 193using a function like 194.Fn snprintf , 195as the resulting string may still contain user-supplied conversion specifiers 196for later interpolation by the 197.Fn err 198and 199.Fn warn 200functions. 201.Pp 202Always be sure to use the proper secure idiom: 203.Bd -literal -offset indent 204err(1, "%s", string); 205.Ed 206