ls_name_value_rd - Man Page

ls_name_value_rd [--empty] [--help] --utf8] [--verbose] [--version] filename [num_bytes]

This utility is a helper for the ls_name_value bash script. This utility may be useful in its own right as it attempts to give an overview of the contents of the filename file. If filename  is regular, accessible and contains only 7 bit ASCII character (or perhaps only UTF-8 encoded sequences) then up to the first num_bytes are output to stdout. Otherwise some description of filename or its contents are output, usually between "<" and ">". For example if filename is a "character device" then "<char device>" is output.

The num_bytes command line argument is optional and is the maximum number of bytes to read from filename. Its default value is 80 .

When errors are detected, sending a description back via stdout is preferred over more traditional techniques (e.g. sending an error message to stderr and setting a non-zero exit code). For example if filename is not found then "<not found>" is output to stdout and the exit code is zero.

Any null characters (in C: '\0') found in the contents (value) are skipped (suppressed) while any ASCII control characters (less than space apart from the null character) and the 0x7f character are replaced by a space. Note that all output to stdout is not ended with a '\n' character.

Arguments to long options are mandatory for short options as well.

-e,  --empty

in many cases the value (contents) associated with filename is empty. By default, nothing will output to stdout. When this option is given, if the value is empty, the string '<empty>' is output to stdout.
Additionally, if this option is given twice, if filename is regular, accessible and only contains the '\n' character (i.e. a linefeed) then "<LF>" is output to stdout. Note that if this option is not given twice then that '\n' control character will be replaced by a space in the output to stdout.

-h,  --help

print out the usage message then exit.

-u,  --utf8

when examining the contents (value) of the filename file, once the top bit (MSB) of a byte has been detected, the default value output will be either "<contains non-ASCII chars>" or "<might be UTF-8>". If a non UTF-8 byte is detected then the whole "value" is considered non-ASCII. If a truncated UTF-8 code point is detected (e.g. truncated due to num_bytes) then if that is the only (partial) UTF-8 encoded sequence then the "value" is considered non-ASCII, otherwise it is consider UTF-8. When this option is given instead of outputting "<might be UTF-8>" the UTF-8 string itself is output to stdout. For the actual UTF-8 encoded sequences to be rendered the locale must be set appropriately. For example on the author's laptop 'env | grep LANG' yields "LANG=en_CA.UTF-8" and UTF-8 encoded sequences are rendered properly.

-v,  --verbose

increase level or verbosity.

-V,  --version

prints out the version string then exits.

The filename is opened read-only and with the O_NONBLOCK flag set. If the user does have permissions to open filename then "<cannot access>" is output to stdout. If the user does have permission but not read-only access but does have write-only access the "<write only>" is output to stdout.

Due to that O_NONBLOCK setting when a following read(2) tries to read from filename and it is not ready (but might be a bit later) then that read(2) yields an EAGAIN. This utility will then pause for 10 milliseconds and try again. After 100 retries with the same outcome (approximately 1 second) this utility will send "<timeout>" to stdout and exit. Note if any characters were read before that timeout, and they are 7 bit ASCII, then they may precede that "<timeout>" string.

This utility "looks through" symbolic links (symlinks). So if filename is to symlink to a directory then "<directory>" is output. In the way this utility works with the ls_name_value bash script, that script takes care of all the symlink handling. If a symlink is "dangling" then this utility outputs "<not found>" to stdout.

As a convenience (e.g. when calling this utility from inside a bash script) empty command line arguments are ignored. For example in a bash script calling this utility with a last argument like "${3}" when there is no third argument to the bash script, then that would invoke this utility with a "" (empty string) argument. And that would normally be a syntax error. This utility just ignores such empty arguments. The utility (like most from this author) uses the GNU getopt_long() library function, or from inside a bash script uses the getopt(1) command.

Written by D. Gilbert

Copyright © 2026 Douglas Gilbert
This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

ls_name_value(this package)