external/bsd/bind/dist/unit/atf-src/atf-sh/atf-check.1

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