---
name: "atf-check"
section: "1"
platform: "linux"
package: "atf-sh"
version: "0.22-3"
release: "Debian 13 (Trixie)"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/atf-check"
---

# atf-check(1)

executes a command and analyzes its results

## NAME

**atf-check** – executes a command and analyzes its results

## SYNOPSIS

**atf-check** \[**-s** *qual:value*\] \[**-o** *action:arg* *...*\] \[**-e** *action:arg* *...*\] \[**-x**\] *command*

## DESCRIPTION

**atf-check** executes a given command and analyzes its results, including exit code, stdout and stderr.

Test cases must use [atf-sh(3)](/atf-sh/3.md)'s **atf\_check** builtin function instead of calling this utility directly.

In the first synopsis form, **atf-check** will execute the provided command and apply checks specified by arguments. By default it will act as if it was run with **-s** *exit:0* **-o** *empty* **-e** *empty*. Multiple checks for the same output channel are allowed and, if specified, their results will be combined as a logical and (meaning that the output must match all the provided checks).

In the second synopsis form, **atf-check** will print information about all supported options and their purpose.

The following options are available:

- **-s** *qual:value*

  Analyzes termination status. Must be one of:

  - *exit:\<value\>*

    checks that the program exited cleanly and that its exit status is equal to *value*. The exit code can be omitted altogether, in which case any clean exit is accepted.

  - *ignore*

    ignores the exit check.

  - *signal:\<value\>*

    checks that the program exited due to a signal and that the signal that terminated it is *value*. The signal can be specified both as a number or as a name, or it can also be omitted altogether, in which case any signal is accepted.

    Most of these checkers can be prefixed by the ‘not-’ string, which effectively reverses the check.

- **-o** *action:arg*

  Analyzes standard output. Must be one of:

  - *empty*

    checks that stdout is empty

  - *ignore*

    ignores stdout

  - *file:\<path\>*

    compares stdout with given file

  - *inline:\<value\>*

    compares stdout with inline value

  - *match:\<regexp\>*

    looks for a regular expression in stdout

  - *save:\<path\>*

    saves stdout to given file

    Most of these checkers can be prefixed by the ‘not-’ string, which effectively reverses the check.

- **-e** *action:arg*

  Analyzes standard error (syntax identical to above)

- **-x**

  Executes *command* as a shell command line, executing it with the system shell defined by *ATF\_SHELL*. You should avoid using this flag if at all possible to prevent shell quoting issues.

- **-r** *timeout\[:interval\]*

  Repeats failed checks until the *timeout* (in seconds) expires. If unspecified, the default *interval* (in milliseconds) is 50 ms. This can be used to wait for an expected update to the contents of a file.

## ENVIRONMENT

- *ATF\_SHELL*

  Path to the system shell to be used when the **-x** is given to run commands.

## EXIT STATUS

**atf-check** exits 0 on success, and other (unspecified) value on failure.

## EXAMPLES

The following are sample invocations from within a test case. Note that we use the **atf\_check** function provided by [atf-sh(3)](/atf-sh/3.md) instead of executing **atf-check** directly:

```
# Exit code 0, nothing on stdout/stderr
atf_check true
# Typical usage if failure is expected
atf_check -s not-exit:0 false
# Checking stdout/stderr
echo foobar >expout
atf_check -o file:expout -e inline:"xx\tyy\n" \
    -x 'echo foobar ; printf "xx\tyy\n" >&2'
# Checking for a crash
atf_check -s signal:sigsegv my_program
# Combined checks
atf_check -o match:foo -o not-match:bar echo foo baz
# Wait 5 seconds for a line to show up in a file
( sleep 2 ; echo "testing 123" > $test_path ) &
atf-check -o ignore -e ignore -s exit:0 -r 5 \
    grep "testing 123" $test_path
```

## SEE ALSO

[atf-sh(1)](/atf-sh/1.md)