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 October 5, 2014 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.Em Test cases must use 44.Em Xr atf-sh 3 Ns ' Ns s 45.Em Nm atf_check 46.Em builtin function instead of calling this utility directly. 47.Pp 48In the first synopsis form, 49.Nm 50will execute the provided command and apply checks specified 51by arguments. 52By default it will act as if it was run with 53.Fl s 54.Ar exit:0 55.Fl o 56.Ar empty 57.Fl e 58.Ar empty . 59Multiple checks for the same output channel are allowed and, if specified, 60their results will be combined as a logical and (meaning that the output must 61match all the provided checks). 62.Pp 63In the second synopsis form, 64.Nm 65will print information about all supported options and their purpose. 66.Pp 67The following options are available: 68.Bl -tag -width XqualXvalueXX 69.It Fl s Ar qual:value 70Analyzes termination status. 71Must be one of: 72.Bl -tag -width signal:<value> -compact 73.It Ar exit:<value> 74checks that the program exited cleanly and that its exit status is equal to 75.Va value . 76The exit code can be omitted altogether, in which case any clean exit is 77accepted. 78.It Ar ignore 79ignores the exit check. 80.It Ar signal:<value> 81checks that the program exited due to a signal and that the signal that 82terminated it is 83.Va value . 84The signal can be specified both as a number or as a name, or it can also 85be omitted altogether, in which case any signal is accepted. 86.El 87.Pp 88Most of these checkers can be prefixed by the 89.Sq not- 90string, which effectively reverses the check. 91.It Fl o Ar action:arg 92Analyzes standard output. 93Must be one of: 94.Bl -tag -width inline:<value> -compact 95.It Ar empty 96checks that stdout is empty 97.It Ar ignore 98ignores stdout 99.It Ar file:<path> 100compares stdout with given file 101.It Ar inline:<value> 102compares stdout with inline value 103.It Ar match:<regexp> 104looks for a regular expression in stdout 105.It Ar save:<path> 106saves stdout to given file 107.El 108.Pp 109Most of these checkers can be prefixed by the 110.Sq not- 111string, which effectively reverses the check. 112.It Fl e Ar action:arg 113Analyzes standard error (syntax identical to above) 114.It Fl x 115Executes 116.Ar command 117as a shell command line, executing it with the system shell defined by 118.Va ATF_SHELL . 119You should avoid using this flag if at all possible to prevent shell quoting 120issues. 121.El 122.Sh EXIT STATUS 123.Nm 124exits 0 on success, and other (unspecified) value on failure. 125.Sh ENVIRONMENT 126.Bl -tag -width ATFXSHELLXX -compact 127.It Va ATF_SHELL 128Path to the system shell to be used when the 129.Fl x 130is given to run commands. 131.El 132.Sh EXAMPLES 133The following are sample invocations from within a test case. 134Note that we use the 135.Nm atf_check 136function provided by 137.Xr atf-sh 3 138instead of executing 139.Nm 140directly: 141.Bd -literal -offset indent 142# Exit code 0, nothing on stdout/stderr 143atf_check 'true' 144 145# Typical usage if failure is expected 146atf_check -s not-exit:0 'false' 147 148# Checking stdout/stderr 149echo foobar >expout 150atf_check -o file:expout -e inline:"xx\etyy\en" \e 151 'echo foobar ; printf "xx\etyy\en" >&2' 152 153# Checking for a crash 154atf_check -s signal:sigsegv my_program 155 156# Combined checks 157atf_check -o match:foo -o not-match:bar echo foo baz 158.Ed 159.Sh SEE ALSO 160.Xr atf-sh 1 161