User space FILEIO handler
=========================

Version 3.11.0-pre, 29 December 2025
------------------------------------

fileio_tgt is a user-space disk handler that demonstrates and exercises the
SCST scst_user interface. The interface is defined by
scst/include/scst_user.h and documented in doc/scst_user_spec.sgml.

Build
-----

From the repository root, "make usr" builds fileio_tgt and stpgd. To build
only this program, run "make -C usr/fileio". Installation is a separate,
privileged operation; use the corresponding install target only when system
installation is intended.

Usage
-----

The scst_user kernel module must be loaded before fileio_tgt is started.
Running fileio_tgt registers live SCST devices and opens every supplied
backing path. Unless read-only mode is selected, initiators can cause writes
to those paths. Do not use a real block device or valuable backing file
without an explicitly prepared test configuration.

fileio_tgt [OPTIONS] name path [name path] ...

Each name is the SCST device name used by later access-management operations.
Each path is the backing file or device from which the handler determines the
virtual device size. Up to the implementation limit, multiple name/path pairs
can be registered by one process.

The following options are supported:

 - -b, --block=size: block size; it must be a power of two and at least 512
 - -e, --threads=count: number of worker threads
 - -t, --write_through: write-through mode
 - -r, --read_only: read-only mode
 - -o, --direct: open the backing path with O_DIRECT for data I/O
 - -n, --nullio: NULLIO mode; see scst/README for its safety warning
 - -c, --nv_cache: NV_CACHE mode; see scst/README for its semantics
 - -p, --parse=type: "std" (default), "call", or "excpt"
 - -f, --on_free=type: "ignore" (default) or "call"
 - -m, --mem_reuse=type: "all" (default), "read", "write", or "none"
 - -l, --non_blocking: use nonblocking scst_user operations
 - -I, --vdisk_id=ID: virtual disk ID for multi-target setups
 - -F, --flush=n: flush the SGV cache every n seconds
 - -s, --sgv_shared: share the first device's SGV cache
 - -S, --sgv_single_cache=n: use a single-entry SGV cache with n pages
 - -P, --sgv_purge_interval=n: set the SGV purge interval in seconds
 - -u, --unreg_before_close: exercise the obsolete unregister ioctl
 - -D, --sgv_disable_clustered_pool: disable the clustered SGV pool
 - -R, --prealloc_buffers=n: preallocate n buffers
 - -Z, --prealloc_buffer_size=n: preallocated buffer size in KiB
 - -M, --multi_cmd=v: enable or disable multi-command processing (default 1)
 - -v, --version: print the program version
 - -h, --help: print usage information

The following options are present only when their corresponding tracing or
debug feature is compiled in:

 - -d, --debug=level: tracing level
 - -g, --debug_tm_ignore: enable the DEBUG_TM_IGNORE test feature

The current option parser and usage() output in usr/fileio/fileio.c are the
authoritative command-line reference.

Vladislav Bolkhovitin <vst@vlnb.net>, http://scst.sourceforge.net
