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 June 21, 2020 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.It Fl r Ar timeout[:interval] 124Repeats failed checks until the 125.Ar timeout 126(in seconds) expires. 127If unspecified, the default 128.Ar interval 129(in milliseconds) is 50 ms. 130This can be used to wait for an expected update to the contents of a file. 131.El 132.Sh ENVIRONMENT 133.Bl -tag -width ATFXSHELLXX -compact 134.It Va ATF_SHELL 135Path to the system shell to be used when the 136.Fl x 137is given to run commands. 138.El 139.Sh EXIT STATUS 140.Nm 141exits 0 on success, and other (unspecified) value on failure. 142.Sh EXAMPLES 143The following are sample invocations from within a test case. 144Note that we use the 145.Nm atf_check 146function provided by 147.Xr atf-sh 3 148instead of executing 149.Nm 150directly: 151.Bd -literal -offset indent 152# Exit code 0, nothing on stdout/stderr 153atf_check 'true' 154 155# Typical usage if failure is expected 156atf_check -s not-exit:0 'false' 157 158# Checking stdout/stderr 159echo foobar >expout 160atf_check -o file:expout -e inline:"xx\etyy\en" \e 161 'echo foobar ; printf "xx\etyy\en" >&2' 162 163# Checking for a crash 164atf_check -s signal:sigsegv my_program 165 166# Combined checks 167atf_check -o match:foo -o not-match:bar echo foo baz 168 169# Wait 5 seconds for a line to show up in a file 170( sleep 2 ; echo "testing 123" > $test_path ) & 171atf-check -o ignore -e ignore -s exit:0 -r 5 \e 172 grep "testing 123" $test_path 173.Ed 174.Sh SEE ALSO 175.Xr atf-sh 1 176