doc/auxiliary-programs.txt

   1                         ==============================
   2                         AUXILIARY PROGRAMS FOR TESTING
   3                         ==============================
   4
   5 Not everything a test script can do is easily done within a test script;
   6 sometimes it makes a lot more sense to write auxiliary program in C and have
   7 the test script call them.  Auxiliary commands can be found in the src/
   8 directory and in other packages.
   9
  10 Tests wanting to use an auxiliary program found in the src/ directory should
  11 note the dependency with:
  12
  13         _require_test_program "<program-name>"
  14
  15
  16 Contents:
  17
  18  - af_unix              -- Create an AF_UNIX socket
  19  - dmerror              -- fault injection block device control
  20  - fsync-err            -- tests fsync error reporting after failed writeback
  21  - open_by_handle       -- open_by_handle_at syscall exercise
  22  - stat_test            -- statx syscall exercise
  23  - t_dir_type           -- print directory entries and their file type
  24  - xfs_io               -- General I/O operation exercise
  25
  26
  27 ==================
  28 QUICK DESCRIPTIONS
  29 ==================
  30
  31 af_unix
  32
  33         The af_unix program creates an AF_UNIX socket at the given location.
  34
  35 dmerror
  36
  37         dmerror is a program for creating, destroying and controlling a
  38         fault injection device. The device can be set up as initially
  39         working and then flip to throwing errors for testing purposes.
  40
  41 fsync-err
  42
  43         Specialized program for testing how the kernel reports errors that
  44         occur during writeback. Works in conjunction with the dmerror script
  45         in tools/ to write data to a device, and then force it to fail
  46         writeback and test that errors are reported during fsync and cleared
  47         afterward.
  48
  49 open_by_handle
  50
  51         The open_by_handle program exercises the open_by_handle_at() system
  52         call.  It can check if file handles are valid or stale after certain
  53         filesystem operations.
  54
  55         See also:
  56                 _require_exportfs
  57
  58 stat_test
  59
  60         The stat_test program is primarily designed to exercise the statx()
  61         system call.  It can check statx() against fstatat() and it can
  62         compare and check various file attributes.
  63
  64         See also:
  65                 _require_statx
  66
  67
  68 t_dir_type
  69
  70         The t_dir_type program exercises the getdents64() system call.
  71         It prints directory entry names returned from getdents64() and
  72         thier d_type, optionally filtered by type or by inode number.
  73
  74 xfs_io
  75
  76         The xfs_io program can be found in the xfsprogs package and can be used
  77         to perform sequences of I/O commands, though it is limited to what it
  78         can do on open files.
  79
  80         xfs_io is a debugging tool that is aimed at examining regular file I/O
  81         paths rather than a raw XFS volume itself.  These code paths include
  82         not only the obvious read/write/mmap interfaces for manipulating files,
  83         but also cover all of the XFS extensions (such as space preallocation,
  84         additional inode flags, etc).
  85
  86         Most of its commands can also be used with other filesystems.
  87
  88         See also:
  89                 _require_xfs_io_command