1.\" $OpenBSD: err.3,v 1.16 2007/05/31 19:19:28 jmc 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.Dd $Mdocdate: May 31 2007 $ 31.Dt ERR 3 32.Os 33.Sh NAME 34.Nm err , 35.Nm verr , 36.Nm errx , 37.Nm verrx , 38.Nm warn , 39.Nm vwarn , 40.Nm warnx , 41.Nm vwarnx 42.Nd formatted error messages 43.Sh SYNOPSIS 44.Fd #include <err.h> 45.Ft void 46.Fn err "int eval" "const char *fmt" "..." 47.Ft void 48.Fn verr "int eval" "const char *fmt" "va_list args" 49.Ft void 50.Fn errx "int eval" "const char *fmt" "..." 51.Ft void 52.Fn verrx "int eval" "const char *fmt" "va_list args" 53.Ft void 54.Fn warn "const char *fmt" "..." 55.Ft void 56.Fn vwarn "const char *fmt" "va_list args" 57.Ft void 58.Fn warnx "const char *fmt" "..." 59.Ft void 60.Fn vwarnx "const char *fmt" "va_list args" 61.Sh DESCRIPTION 62The 63.Fn err 64and 65.Fn warn 66family of functions display a formatted error message on the standard 67error output. 68In all cases, the last component of the program name, followed by 69a colon 70.Pq Sq \&: 71character and a space, are output. 72The text that follows depends on the function being called. 73The 74.Fa fmt 75specification (and associated arguments) may be any format allowed by 76.Xr printf 3 , 77a simple string, or 78.Dv NULL . 79If the 80.Fa fmt 81argument is not 82.Dv NULL , 83the formatted error message is output. 84.Pp 85In the case of the 86.Fn err , 87.Fn verr , 88.Fn warn , 89and 90.Fn vwarn 91functions only, the error message string affiliated with the current value of 92the global variable 93.Va errno 94is output (see 95.Xr strerror 3 ) , 96preceded by a colon character and a space if 97.Fa fmt 98is not 99.Dv NULL . 100That is, the output is as follows: 101.Bd -literal -offset indent 102progname: fmt: error message string 103.Ed 104.Pp 105if 106.Fa fmt 107is not 108.Dv NULL , 109or: 110.Bd -literal -offset indent 111progname: error message string 112.Ed 113.Pp 114if it is. 115.Pp 116The counterpart functions, 117.Fn errx , 118.Fn verrx , 119.Fn warnx , 120and 121.Fn vwarnx , 122do not output the error message string, so the output looks like the following: 123.Bd -literal -offset indent 124progname: fmt 125.Ed 126.Pp 127In all cases, the output is followed by a newline character. 128.Pp 129The 130.Fn err , 131.Fn verr , 132.Fn errx , 133and 134.Fn verrx 135functions do not return, but exit with the value of the argument 136.Fa eval . 137.Sh EXAMPLES 138Display the current 139.Va errno 140information string and exit: 141.Bd -literal -offset indent 142if ((p = malloc(size)) == NULL) 143 err(1, NULL); 144if ((fd = open(file_name, O_RDONLY, 0)) == -1) 145 err(1, "%s", file_name); 146.Ed 147.Pp 148Display an error message and exit: 149.Bd -literal -offset indent 150if (tm.tm_hour < START_TIME) 151 errx(1, "too early, wait until %s", start_time_string); 152.Ed 153.Pp 154Warn of an error: 155.Bd -literal -offset indent 156if ((fd = open(raw_device, O_RDONLY, 0)) == -1) 157 warnx("%s: %s: trying the block device", 158 raw_device, strerror(errno)); 159if ((fd = open(block_device, O_RDONLY, 0)) == -1) 160 err(1, "%s", block_device); 161.Ed 162.Sh SEE ALSO 163.Xr exit 3 , 164.Xr perror 3 , 165.Xr printf 3 , 166.Xr strerror 3 167.Sh HISTORY 168The 169.Fn err 170and 171.Fn warn 172functions first appeared in 173.Bx 4.4 . 174.Sh CAVEATS 175It is important never to pass a string with user-supplied data as a 176format without using 177.Ql %s . 178An attacker can put format specifiers in the string to mangle the stack, 179leading to a possible security hole. 180This holds true even if the string has been built 181.Dq by hand 182using a function like 183.Fn snprintf , 184as the resulting string may still contain user-supplied conversion specifiers 185for later interpolation by the 186.Fn err 187and 188.Fn warn 189functions. 190.Pp 191Always be sure to use the proper secure idiom: 192.Bd -literal -offset indent 193err(1, "%s", string); 194.Ed 195