Adding upstream version 1:9.11.5.P4+dfsg.upstream/1%9.11.5.P4+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 202 insertions, 0 deletions

diff --git a/unit/atf-src/tools/atf-run.1 b/unit/atf-src/tools/atf-run.1
new file mode 100644
index 0000000..d593f47
--- /dev/null
+++ b/unit/atf-src/tools/atf-run.1
@@ -0,0 +1,202 @@
+.\"
+.\" Automated Testing Framework (atf)
+.\"
+.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
+.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
+.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
+.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 1, 2010
+.Dt ATF-RUN 1
+.Os
+.Sh NAME
+.Nm atf-run
+.Nd executes a collection of test programs
+.Sh SYNOPSIS
+.Nm
+.Op Fl v Ar var1=value1 Op .. Fl v Ar varN=valueN
+.Op Ar test_program1 Op Ar .. test_programN
+.Nm
+.Fl h
+.Sh DESCRIPTION
+.Nm
+executes a collection of test programs or, in other words, a complete
+test suite.
+The results of each test program are collected by the tool, and are then
+multiplexed into a single machine-parseable report; see
+.Xr atf-formats 5
+for more details.
+This report can later be transformed into many different and saner formats
+using the
+.Nm atf-report
+tool.
+.Pp
+The list of test programs to execute is read from an
+.Pa Atffile
+present in the current directory.
+This file describes the test suite stored in the directory it lives in,
+which aside from the list of test programs also includes meta-data and
+configuration variables.
+.Pp
+.Nm
+is also in charge of reading the configuration files that tune the behavior
+of each test program and passing down the necessary variables to them.
+More details on how this is done are given in the
+.Sx Configuration
+section.
+.Pp
+In the first synopsis form,
+.Nm
+parses the
+.Pa Atffile
+in the current directory and runs all the test programs specified in it.
+If any test program names are given as part of the command line, those are
+the ones executed instead of the complete list.
+.Pp
+In the second synopsis form,
+.Nm
+will print information about all supported options and their purpose.
+.Pp
+The following options are available:
+.Bl -tag -width XvXvarXvalueXX
+.It Fl h
+Shows a short summary of all available options and their purpose.
+.It Fl v Ar var=value
+Sets the configuration variable
+.Ar var
+to the given value
+.Ar value .
+.El
+.Ss Configuration
+.Nm
+reads configuration data from multiple places.
+After all of these places have been analyzed, a list of variable-value
+pairs are passed to the test programs to be run.
+.Pp
+The following locations are scanned for configuration data, in order.
+Items down the list override values defined above them:
+.Bl -enum
+.It
+Configuration variables defined in the
+.Pa Atffile .
+.It
+Configuration variables defined in the system-wide configuration file
+shared among all test suites.
+This lives in
+.Pa ${ATF_CONFDIR}/common.conf .
+.It
+Configuration variables defined in the system-wide test-suite-specific
+configuration file.
+This lives in
+.Pa ${ATF_CONFDIR}/<test-suite>.conf .
+.It
+Configuration variables defined in the user-specific configuration file
+shared among all test suites.
+This lives in
+.Pa ${HOME}/.atf/common.conf .
+.It
+Configuration variables defined in the user-specific test-suite-specific
+configuration file.
+This lives in
+.Pa ${HOME}/.atf/<test-suite>.conf .
+.It
+Configuration variables provided as part of the command line through the
+.Fl v
+option.
+.El
+.Pp
+The value of
+.Va ATF_CONFDIR
+in the above list determined as detailed in
+.Xr atf-config 1 .
+.Pp
+The following configuration variables are globally recognized:
+.Bl -tag -width XunprivilegedXuserXX
+.It Va unprivileged-user
+The name of the system user that atf-run will drop root privileges into
+for test cases defining
+.Sq require.user=unprivileged .
+Note that this is
+.Em not provided for security purposes ;
+this feature is only for the convenience of the user.
+.El
+.Ss Hooks
+.Nm Ns 's
+internal behavior can be customized by the system administrator and the
+user by means of hooks.
+These hooks are written in the shell script language for simplicity and
+are stored in the following files, which are read in the order provided
+below:
+.Bl -enum
+.It
+${ATF_CONFDIR}/atf-run.hooks
+.It
+${HOME}/.atf/atf-run.hooks
+.El
+.Pp
+The following hooks are supported:
+.Bl -tag -width infoXstartXhookXX
+.It info_start_hook
+Called before
+.Nm
+executes any test program.
+The purpose of this hook is to write additional
+.Sq info
+stanzas to the top of the output report; these are defined by the
+.Sq application/X-atf-tps format
+described in
+.Xr atf-formats 5 .
+Always use the
+.Sq atf_tps_writer_info
+function to print these.
+.Pp
+This takes no parameters.
+.It info_end_hook
+Similar to
+.Sq info_start_hook
+but executed after all test programs have been run so that additional
+.Sq info
+stanzas can be added to the bottom of the output report.
+.Pp
+This takes no parameters.
+.El
+.Pp
+All hooks are accompanied by a function named
+.Sq default_<hook_name>
+that can be executed by them to invoke the default behavior built into
+.Nm .
+For example, in order to extend the default
+.Sq info_start_hook
+hook, we could write the following function:
+.Bd -literal -offset indent
+info_start_hook()
+{
+    default_info_start_hook "${@}"
+
+    atf_tps_writer_info "uptime" "$(uptime)"
+}
+.Ed
+.Sh SEE ALSO
+.Xr atf-report 1 ,
+.Xr atf-test-program 1 ,
+.Xr atf 7