I think this is usually done as:

The
.Nm
utility can be use to perform raw data transfers (read, write,

The longest option is "-f device", so this should be

.Bl -tag -width ".Fl f Ar device"

Hex numbers are not digits; perhaps "2-character", or "8-bit"?

thanks for all of this, I'm not that good at man pages, and although the markup 'works' it may not be the way you'd want it in the base distro. So I'll look over all of this and update it accordingly. Still learning how to use THIS system too, so if there is an easy way to 'patch the patch'...

optarg[1] == 0 (not '0') - oops

kept 'An' rather than 'A' [seems to read better].

I have no idea what this comment means. It wasn't until I saw how the array was used that I realized that this table is for reversing bits in a byte, the comment should just say that :) (and maybe be named something like reversebits)

strlcat() is better than strncat() for this sort of thing, easier to use.

But, make the logic something like:

if (optarg[0] == '/')
    strlcpy(dev_name, optarg, sizeof(dev_name);
else
    snprintf(dev_name, sizeof(dev_name), "/dev/%s", optarg);

So that it works with -f spigen0 and -f /dev/spigen0.

You can do better error checking with strtol() and strtoul(), something like:

opt.mode = strtol(optarg, &p, 0);
if (p == optarg || opt.mode < 0 || opt.mode > 3)
	/* report error */

the standard comment for this (recognized by code analysis tools to supress warnings) is

/* FALLTHROUGH */

variable names should be lowercase, and especially should not have hungarian prefixes.

if you're not going to send separate command and data, might as well put everything into the command array and leave data length zero.

I got rid of the more 'blatant' hungarian naming, but things like 'hdev' and 'popt' remain. I could change those too, I suppose, but at some point you have to say 'does it really matter?'

the 3 lines above this one need to be removed. it's a bug. I changed tactics while adding -C and forgot to remove them. Found during testing. the call to 'perform_read' should always be done regardless of the presence of command bytes (this is handled later on).

with the use of 'symlink' alias devices for https://reviews.freebsd.org/D15301 this function will need to be able to handle those symlinks. The implementation in this utility could follow the symlink and store the canonical device name and unit (from the name), or it could re-calculate it here on each call [which isn't very frequent]. Either one would be acceptable and compatible, so long as the canonical device naming is consistent with the sysctl variable naming; that is, the 'spigen0' device must have its sysctl vars in 'dev.spigen.0' (and so on).

may need to make this 'spigen0.0' depending on how things go with DS15301 and whether or not 11.x will be relevant.

listing the author is uncommon in other nearby makefiles (only bsnmpd does it). most have just the $FreeBSD:$ line followed by a blank line.

This needs a copyright block at the top.

And a .Dd line.

Recent consensus is that "all rights reserved" hasn't been necessary since 1989 and should be left off new files.

It's a good idea to exactly copy src/share/etc/bsd-style-copyright and edit in your info. That gets you the new SPDX id stuff and all.

This probably shouldn't be here

there should be a tab between #define and the symbol name (icky arbitrary style(9) rule)

popt for pointer-to-opt was in use long before hungarian came along. as long as we don't have camelcase and lpszStr (which I can only ever see as "lip-sized string") I think we're good. :)