21ef118596b6c4c967c9e39b438dcdc98ff33871
[xfstests-dev.git] / 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  - open_by_handle       -- open_by_handle_at syscall exercise
20  - stat_test            -- statx syscall exercise
21  - t_dir_type           -- print directory entries and their file type
22  - xfs_io               -- General I/O operation exercise
23
24
25 ==================
26 QUICK DESCRIPTIONS
27 ==================
28
29 af_unix
30
31         The af_unix program creates an AF_UNIX socket at the given location.
32
33 open_by_handle
34
35         The open_by_handle program exercises the open_by_handle_at() system
36         call.  It can check if file handles are valid or stale after certain
37         filesystem operations.
38
39         See also:
40                 _require_exportfs
41
42 stat_test
43
44         The stat_test program is primarily designed to exercise the statx()
45         system call.  It can check statx() against fstatat() and it can
46         compare and check various file attributes.
47
48         See also:
49                 _require_statx
50
51
52 t_dir_type
53
54         The t_dir_type program exercises the getdents64() system call.
55         It prints directory entry names returned from getdents64() and
56         thier d_type, optionally filtered by type or by inode number.
57
58 xfs_io
59
60         The xfs_io program can be found in the xfsprogs package and can be used
61         to perform sequences of I/O commands, though it is limited to what it
62         can do on open files.
63
64         xfs_io is a debugging tool that is aimed at examining regular file I/O
65         paths rather than a raw XFS volume itself.  These code paths include
66         not only the obvious read/write/mmap interfaces for manipulating files,
67         but also cover all of the XFS extensions (such as space preallocation,
68         additional inode flags, etc).
69
70         Most of its commands can also be used with other filesystems.
71
72         See also:
73                 _require_xfs_io_command