1.\" Copyright (c) 2008 The NetBSD Foundation, Inc. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND 14.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 15.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY 18.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 20.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 22.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 24.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.Dd March 6, 2017 26.Dt ATF-CHECK 1 27.Os 28.Sh NAME 29.Nm atf-check 30.Nd executes a command and analyzes its results 31.Sh SYNOPSIS 32.Nm 33.Op Fl s Ar qual:value 34.Op Fl o Ar action:arg ... 35.Op Fl e Ar action:arg ... 36.Op Fl x 37.Ar command 38.Sh DESCRIPTION 39.Nm 40executes a given command and analyzes its results, including 41exit code, stdout and stderr. 42.Pp 43.Bf Em 44Test cases must use 45.Xr atf-sh 3 Ns ' Ns s 46.Nm atf_check 47builtin function instead of calling this utility directly. 48.Ef 49.Pp 50In the first synopsis form, 51.Nm 52will execute the provided command and apply checks specified 53by arguments. 54By default it will act as if it was run with 55.Fl s 56.Ar exit:0 57.Fl o 58.Ar empty 59.Fl e 60.Ar empty . 61Multiple checks for the same output channel are allowed and, if specified, 62their results will be combined as a logical and (meaning that the output must 63match all the provided checks). 64.Pp 65In the second synopsis form, 66.Nm 67will print information about all supported options and their purpose. 68.Pp 69The following options are available: 70.Bl -tag -width XqualXvalueXX 71.It Fl s Ar qual:value 72Analyzes termination status. 73Must be one of: 74.Bl -tag -width signal:<value> -compact 75.It Ar exit:<value> 76checks that the program exited cleanly and that its exit status is equal to 77.Va value . 78The exit code can be omitted altogether, in which case any clean exit is 79accepted. 80.It Ar ignore 81ignores the exit check. 82.It Ar signal:<value> 83checks that the program exited due to a signal and that the signal that 84terminated it is 85.Va value . 86The signal can be specified both as a number or as a name, or it can also 87be omitted altogether, in which case any signal is accepted. 88.El 89.Pp 90Most of these checkers can be prefixed by the 91.Sq not- 92string, which effectively reverses the check. 93.It Fl o Ar action:arg 94Analyzes standard output. 95Must be one of: 96.Bl -tag -width inline:<value> -compact 97.It Ar empty 98checks that stdout is empty 99.It Ar ignore 100ignores stdout 101.It Ar file:<path> 102compares stdout with given file 103.It Ar inline:<value> 104compares stdout with inline value 105.It Ar match:<regexp> 106looks for a regular expression in stdout 107.It Ar save:<path> 108saves stdout to given file 109.El 110.Pp 111Most of these checkers can be prefixed by the 112.Sq not- 113string, which effectively reverses the check. 114.It Fl e Ar action:arg 115Analyzes standard error (syntax identical to above) 116.It Fl x 117Executes 118.Ar command 119as a shell command line, executing it with the system shell defined by 120.Va ATF_SHELL . 121You should avoid using this flag if at all possible to prevent shell quoting 122issues. 123.El 124.Sh ENVIRONMENT 125.Bl -tag -width ATFXSHELLXX -compact 126.It Va ATF_SHELL 127Path to the system shell to be used when the 128.Fl x 129is given to run commands. 130.El 131.Sh EXIT STATUS 132.Nm 133exits 0 on success, and other (unspecified) value on failure. 134.Sh EXAMPLES 135The following are sample invocations from within a test case. 136Note that we use the 137.Nm atf_check 138function provided by 139.Xr atf-sh 3 140instead of executing 141.Nm 142directly: 143.Bd -literal -offset indent 144# Exit code 0, nothing on stdout/stderr 145atf_check 'true' 146 147# Typical usage if failure is expected 148atf_check -s not-exit:0 'false' 149 150# Checking stdout/stderr 151echo foobar >expout 152atf_check -o file:expout -e inline:"xx\etyy\en" \e 153 'echo foobar ; printf "xx\etyy\en" >&2' 154 155# Checking for a crash 156atf_check -s signal:sigsegv my_program 157 158# Combined checks 159atf_check -o match:foo -o not-match:bar echo foo baz 160.Ed 161.Sh SEE ALSO 162.Xr atf-sh 1 163