LS\_NAME\_VALUE\_RD(8) LSSCSI LS\_NAME\_VALUE\_RD(8)

# [NAME](#NAME)

ls\_name\_value\_rd - get an overview of the contents of a file

# [SYNOPSIS](#SYNOPSIS)

**ls\_name\_value\_rd** \[*--empty*] \[*--help*] *--utf8*] \[*--verbose*] \[*--version*] *filename* \[*num\_bytes*]

# [DESCRIPTION](#DESCRIPTION)

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.

# [OPTIONS](#OPTIONS)

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

[**-e**, **--empty**](#e)

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**](#h)

print out the usage message then exit.

[**-u**, **--utf8**](#u)

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**](#v)

increase level or verbosity.

[**-V**, **--version**](#V)

prints out the version string then exits.

# [NOTES](#NOTES)

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)](/man/enterprise-packages/lsscsi/read.2) tries to read from *filename* and it is not ready (but might be a bit later) then that [read(2)](/man/enterprise-packages/lsscsi/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)](/man/enterprise-packages/lsscsi/getopt.1) command.

# [AUTHORS](#AUTHORS)

Written by D. Gilbert

# [COPYRIGHT](#COPYRIGHT)

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.

# [SEE ALSO](#SEE_ALSO)

**ls\_name\_value(this package)**

2026-09-13 lsscsi-0.33

---

Document: ls_name_value_rd(8) from lsscsi 0.33-r0 (Chainguard OS)
Source: https://github.com/doug-gilbert/lsscsi