Changeset View
Changeset View
Standalone View
Standalone View
share/man/man3/assert.3
Show All 22 Lines | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" @(#)assert.3 8.1 (Berkeley) 6/9/93 | .\" @(#)assert.3 8.1 (Berkeley) 6/9/93 | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd May 31, 2018 | .Dd April 19, 2021 | ||||
.Dt ASSERT 3 | .Dt ASSERT 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm assert | .Nm assert , | ||||
.Nm static_assert | |||||
.Nd expression verification macro | .Nd expression verification macro | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In assert.h | .In assert.h | ||||
.Fn assert expression | .Fn assert expression | ||||
.Fn static_assert expression | |||||
.Fn static_assert expression message | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn assert | .Fn assert | ||||
macro tests the given | macro tests the given | ||||
.Ar expression | .Ar expression | ||||
and if it is false, | and if it is false, | ||||
the calling process is terminated. | the calling process is terminated. | ||||
A diagnostic message is written to | A diagnostic message is written to | ||||
Show All 28 Lines | |||||
until the end of the unit or another include of | until the end of the unit or another include of | ||||
.In assert.h . | .In assert.h . | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn assert | .Fn assert | ||||
macro should only be used for ensuring the developer's expectations | macro should only be used for ensuring the developer's expectations | ||||
hold true. | hold true. | ||||
It is not appropriate for regular run-time error detection. | It is not appropriate for regular run-time error detection. | ||||
.Pp | |||||
The | |||||
.Fn static_assert | |||||
macro expands to | |||||
.Fn _Static_assert , | |||||
arichardson: Not sure if you also want to mention C++ here. This statement is only true for C, in C++11… | |||||
Not Done Inline ActionsCompletely true. _Static_assert does not exist in C++, and that's why using static_assert is mostly preferred. And this is indeed very good to educate the reader. But I think we predominantly discuss C topics, and since a lot of things differ in C++, I think this is not necessary to delve into such details. kfv_kfv.io: Completely true. `_Static_assert` does not exist in C++, and that's why using `static_assert`… | |||||
and contrarily to | |||||
.Fn assert , | |||||
makes assertions at compile-time. | |||||
Once the constraint is violated, the compiler produces a diagnostic | |||||
message including the string literal message, if provided. | |||||
The initial form of the | |||||
.Fn _Static_assert | |||||
containing a string literal message was introduced in C11 standard, and | |||||
the other form with no string literal is to be implemented by C2x and | |||||
some compiler may lack its adoption at present. | |||||
.Sh EXAMPLES | .Sh EXAMPLES | ||||
Done Inline ActionsI'd add an example too. static_assert(sizeof(int) == sizeof(void *), "ints and pointers are different sizes"); imp: I'd add an example too.
static_assert(sizeof(int) == sizeof(void *), "ints and pointers are… | |||||
Done Inline ActionsSure, I will update it shortly. Thanks. kfv_kfv.io: Sure, I will update it shortly. Thanks. | |||||
Done Inline ActionsI just added an example, please let me know if I should add more or change anything. Thanks! kfv_kfv.io: I just added an example, please let me know if I should add more or change anything. Thanks! | |||||
The assertion: | The assertion: | ||||
.Dl "assert(1 == 0);" | .Dl "assert(1 == 0);" | ||||
generates a diagnostic message similar to the following: | generates a diagnostic message similar to the following: | ||||
.Dl "Assertion failed: (1 == 0), function main, file main.c, line 100." | .Dl "Assertion failed: (1 == 0), function main, file main.c, line 100." | ||||
.Pp | .Pp | ||||
The following assert tries to assert there was no partial read: | The following assert tries to assert there was no partial read: | ||||
.Dl "assert(read(fd, buf, nbytes) == nbytes);" | .Dl "assert(read(fd, buf, nbytes) == nbytes);" | ||||
However, there are two problems. | However, there are two problems. | ||||
First, it checks for normal conditions, rather than conditions that | First, it checks for normal conditions, rather than conditions that | ||||
indicate a bug. | indicate a bug. | ||||
Second, the code will disappear if | Second, the code will disappear if | ||||
.Dv NDEBUG | .Dv NDEBUG | ||||
is defined, changing the semantics of the program. | is defined, changing the semantics of the program. | ||||
.Pp | |||||
The following asserts that the size of the S structure is 16. | |||||
Otherwise, it produces a diagnostic message which points at the | |||||
constraint and includes the provided string literal: | |||||
.D1 "static_assert(sizeof(struct S) == 16, ""size mismatch"");" | |||||
If none is provided, it only points at the constraint. | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr abort2 2 , | .Xr abort2 2 , | ||||
.Xr abort 3 | .Xr abort 3 | ||||
.Sh STANDARDS | .Sh STANDARDS | ||||
.Rs | |||||
The | The | ||||
.Fn assert | .Fn assert | ||||
macro conforms to | macro conforms to | ||||
.St -isoC-99 . | .St -isoC-99 . | ||||
.Re | |||||
.Pp | |||||
.Rs | |||||
The | |||||
.Fn static_assert | |||||
macro conforms to | |||||
.St -isoC-2011 . | |||||
.Re | |||||
.Sh HISTORY | .Sh HISTORY | ||||
An | An | ||||
.Nm | .Nm | ||||
macro appeared in | macro appeared in | ||||
.At v7 . | .At v7 . |
Not sure if you also want to mention C++ here. This statement is only true for C, in C++11 static_assert is a keyword and _Static_assert. GCC rejects _Static_assert in C++ mode while clang accepts it.