1.\" $NetBSD: _DIAGASSERT.3,v 1.8 2008/04/30 13:10:53 martin Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Luke Mewburn. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd January 22, 2007 31.Dt _DIAGASSERT 3 32.Os 33.Sh NAME 34.Nm _DIAGASSERT 35.Nd expression verification macro 36.Sh SYNOPSIS 37.In assert.h 38.Fn _DIAGASSERT expression 39.Sh DESCRIPTION 40The 41.Fn _DIAGASSERT 42macro tests the given 43.Ar expression 44and if it is false, one or more of the following may occur: 45.Bl -bullet -offset indent 46.It 47a diagnostic message may be logged to the system logger with 48.Xr syslog 3 . 49This is default behaviour. 50.It 51a diagnostic message may be printed to the 52.Dv stderr 53stream. 54.It 55the calling process will be terminated by calling 56.Xr abort 3 . 57.El 58.Pp 59This behaviour may be changed by setting the 60.Ev LIBC_DIAGASSERT 61environment variable (see below). 62.Pp 63The diagnostic message consists of the text of the expression, 64the name of the source file, the line number and the enclosing 65function. 66.Pp 67If 68.Ar expression 69is true, 70the 71.Fn _DIAGASSERT 72macro does nothing. 73.Pp 74The 75.Fn _DIAGASSERT 76macro is not compiled in by default, and will only be compiled in with the 77.Xr cc 1 78option 79.Fl D_DIAGNOSTIC . 80.Pp 81This macro is used in the various system libraries such as the 82.Lb libc 83to ensure that various library calls are invoked with valid arguments. 84.Sh ENVIRONMENT 85The 86.Ev LIBC_DIAGASSERT 87environment variable can be used to modify the default behaviour of 88logging the assertion to the system logger. 89.Pp 90.Ev LIBC_DIAGASSERT 91may be set to one or more of the following characters: 92.Bl -tag -width xxx -offset indent 93.It a 94.Xr abort 3 95once any assertion messages have been logged and/or printed. 96.It A 97Opposite of 98.Dq a . 99.It e 100Print the assertion message to the 101.Dv stderr 102stream. 103.It E 104Opposite of 105.Dq e . 106.It l 107Log the assertion message with 108.Xr syslog 3 109to the facility 110.Dv user.debug . 111.It L 112Opposite of 113.Dq l . 114.El 115.Sh DIAGNOSTICS 116The diagnostic message has the following format: 117.Bd -literal -offset indent 118"assertion \e"%s\e" failed: file \e"%s\e", line %d, function \e"%s\e"\en", 119 "expression", __FILE__, __LINE__, __func__ 120.Ed 121.Sh SEE ALSO 122.Xr cc 1 , 123.Xr abort 3 , 124.Xr assert 3 , 125.Xr syslog 3 126.Sh HISTORY 127The 128.Nm _DIAGASSERT 129macro appeared in 130.Nx 1.5 . 131