doc/requirement-checking.txt

		   ========================================
		   TESTING FOR REQUIREMENTS IN TEST SCRIPTS
		   ========================================

Test scripts need to indicate to the infrastructure what sorts of requirements
they have.  This is done with _require_<xxx> macros, which may take parameters.

 (1) General requirements.

	_require_command "$<NAME_PROG>" <name>
	_require_test
	_require_test_program <name>
	_require_xfs_io_command <name> [<switch>]

 (2) Filesystem capability requirements.

	_require_chattr <letters>
	_require_exportfs
	_require_sgid_inheritance
	_require_use_local_uidgid
	_require_unix_perm_checking

 (3) System call requirements.

	_require_statx

 (4) Device mapper requirement.

	_require_dm_target
	_require_log_writes

====================
GENERAL REQUIREMENTS
====================

_require_command "$NAME_PROG" name

     The test requires an external command, called 'name' be present on the
     system and that '$VAR' should be set with the path to that command.  $VAR
     should then be used to refer to the command when executing it.  For
     example:

	_require_command "KILLALL_PROG" killall

     to locate the killall command and then:

	$KILLALL_PROG -q $FSSTRESS_PROG

     to make use of it.


_require_test

     The test requires that the block device specified by $TEST_DEV be mounted
     on $TEST_DIR.


_require_test_program <name>

     The test requires a program by the name of 'name' be present and built in
     the src/ directory.  For example:

	_require_test_program "stat_test"

     requires that src/stat_test be built.


_require_xfs_io_command <name> [<switch>]

     The test requires that the xfs_io command be available, that it supports
     command <name> and, optionally, that that command supports the specified
     switch.  For example:

	_require_xfs_io_command "falloc"
	_require_xfs_io_command "chattr" "x"

     The first requires that xfs_io support the falloc command and the second
     that it supports the chattr command and that the chattr command supports
     the +x and -x arguments (DAX attribute).


==================================
FILESYSTEM CAPABILITY REQUIREMENTS
==================================

_require_chattr <letters>

     The test requires that the filesystem attribute set by the chattr command
     with +<letters> as an argument be available and supported by the $TEST_DEV
     filesystem.  No check is made of the scratch filesystem.  For example:

	_require_chattr ai

     tests to see if setting the append-only and immutable attributes on a file
     (chattr +a +i) is supported.

_require_exportfs

     The test requires that the $TEST_DEV filesystem supports NFS export.
     The test also requires the use of the open_by_handle_at() system call and
     will be skipped if it isn't available in the kernel.

_require_sgid_inheritance

     The test required that the $TEST_DEV filesystem supports the inheritance
     of the SGID bit and the GID from a marked directory.  The test will be
     skipped if not supported.

_require_use_local_uidgid

     The test requires that the $TEST_DEV filesystem sets the uid and gid of a
     newly created file to the creating process's fsuid and fsgid.  Remote
     filesystems, for example, may choose other settings or not even have these
     concepts available.  The test will be skipped if not supported.

_require_unix_perm_checking

     The test requires that the $TEST_DEV filesystem performs traditional UNIX
     file permissions checking.  A remote filesystem, for example, might use
     some alternative distributed permissions model involving authentication
     tokens rather than the local fsuid/fsgid.


========================
SYSTEM CALL REQUIREMENTS
========================

_require_statx

     The test requires the use of the statx() system call and will be skipped
     if it isn't available in the kernel.


==========================
DEVICE MAPPER REQUIREMENTS
==========================

_require_dm_target <name>

     The test requires the use of the device mapper target and will be skipped
     if it isn't available in the kernel.

_require_log_writes

     The test requires the use of the device mapper target log-writes.
     The test also requires the test program log-writes/replay-log is built
     and will be skipped if either isn't available.

======================
PERF TEST REQUIREMENTS
======================

_require_fio_results

     This test requires the supporting tools for saving and comparing fio based
     perf test results.