1.\" $NetBSD: err.3,v 1.20 2010/03/22 19:30:53 joerg 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 March 21, 2001 33.Dt ERR 3 34.Os 35.Sh NAME 36.Nm err , 37.Nm verr , 38.Nm errx , 39.Nm verrx , 40.Nm warn , 41.Nm vwarn , 42.Nm warnx , 43.Nm vwarnx 44.Nd formatted error messages 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In err.h 49.Ft void 50.Fn err "int status" "const char *fmt" "..." 51.Ft void 52.Fn verr "int status" "const char *fmt" "va_list args" 53.Ft void 54.Fn errx "int status" "const char *fmt" "..." 55.Ft void 56.Fn verrx "int status" "const char *fmt" "va_list args" 57.Ft void 58.Fn warn "const char *fmt" "..." 59.Ft void 60.Fn vwarn "const char *fmt" "va_list args" 61.Ft void 62.Fn warnx "const char *fmt" "..." 63.Ft void 64.Fn vwarnx "const char *fmt" "va_list args" 65.Sh DESCRIPTION 66The 67.Fn err 68and 69.Fn warn 70family of functions display a formatted error message on the standard 71error output. 72In all cases, the last component of the program name, a colon character, 73and a space are output. 74If the 75.Fa fmt 76argument is not 77.Dv NULL , 78the formatted error message is output. 79In the case of the 80.Fn err , 81.Fn verr , 82.Fn warn , 83and 84.Fn vwarn 85functions, the error message string affiliated with the current value of 86the global variable 87.Va errno 88is output next, preceded by a colon character and a space if 89.Fa fmt 90is not 91.Dv NULL . 92In all cases, the output is followed by a newline character. 93The 94.Fn errx , 95.Fn verrx , 96.Fn warnx , 97and 98.Fn vwarnx 99functions will not output this error message string. 100.Pp 101The 102.Fn err , 103.Fn verr , 104.Fn errx , 105and 106.Fn verrx 107functions do not return, but instead cause the program to terminate 108with the status value given by the argument 109.Fa status . 110It is often appropriate to use the value 111.Dv EXIT_FAILURE , 112defined in 113.In stdlib.h , 114as the 115.Fa status 116argument given to these functions. 117.Sh EXAMPLES 118Display the current 119.Va errno 120information string and terminate with status indicating failure: 121.Bd -literal -offset indent 122if ((p = malloc(size)) == NULL) 123 err(EXIT_FAILURE, NULL); 124if ((fd = open(file_name, O_RDONLY, 0)) == -1) 125 err(EXIT_FAILURE, "%s", file_name); 126.Ed 127.Pp 128Display an error message and terminate with status indicating failure: 129.Bd -literal -offset indent 130if (tm.tm_hour \*[Lt] START_TIME) 131 errx(EXIT_FAILURE, "too early, wait until %s", 132 start_time_string); 133.Ed 134.Pp 135Warn of an error: 136.Bd -literal -offset indent 137if ((fd = open(raw_device, O_RDONLY, 0)) == -1) 138 warnx("%s: %s: trying the block device", 139 raw_device, strerror(errno)); 140if ((fd = open(block_device, O_RDONLY, 0)) == -1) 141 warn("%s", block_device); 142.Ed 143.Sh SEE ALSO 144.Xr exit 3 , 145.Xr getprogname 3 , 146.Xr strerror 3 147.Sh HISTORY 148The 149.Fn err 150and 151.Fn warn 152functions first appeared in 153.Bx 4.4 . 154.Sh CAVEATS 155It is important never to pass a string with user-supplied data as a 156format without using 157.Ql %s . 158An attacker can put format specifiers in the string to mangle your stack, 159leading to a possible security hole. 160This holds true even if you have built the string 161.Dq by hand 162using a function like 163.Fn snprintf , 164as the resulting string may still contain user-supplied conversion specifiers 165for later interpolation by the 166.Fn err 167and 168.Fn warn 169functions. 170.Pp 171Always be sure to use the proper secure idiom: 172.Bd -literal -offset indent 173err(1, "%s", string); 174.Ed 175