Re: Un-sucking EINVAL (was: ip# on bridge members)

On Wed, May 21, 2025 at 07:22:29AM +0000, Poul-Henning Kamp wrote:
> The ip# on bridge member interfaces is yet another example of why
> "EINVAL" is the undisputedly least helpful errno of them all.
> 
> The laconic "Invalid argument" leaves both the userland programmer
> and the user to guess what might be wrong.
> 
> That's ok-ish for read(2) where the possibilities are so few that
> the manpage can tell you what you did wrong.
> 
> It breaks down totally for ioctl(2), setsockopt(2) and similar
> syscalls which can attempt very, complex operations with many
> parameters and subparameters.
> 
> Ifconfig(8) is ground zero for this and the manpage is not even trying:
> 
> 	DIAGNOSTICS
> 	     Messages indicating the specified interface does not exist, the requested
> 	     address is unknown, or the user is not privileged and tried to alter an
> 	     interface's configuration.
> 
> We should give errno a text-partner, so kernel code can:
> 
> 	if (p->n_mazel-vanes < 6 * p->n_dingle_arms) {
> 		error_text("Too few mazel-vanes per dingle-arm (min: 6)");
> 		return (EINVAL)
> 	}
> 
> The err(3) family of functions should retrieve the string, and when there
> is one, print it as part of the error message:
> 
> 	Invalid argument:  Too few mazel-vanes per dingle-arm (min: 6)

In CheriBSD we implemented a related system with a somewhat different
target audiance.  We had added half a dozen more EINVAL failures to mmap
and it was too hard to debug them.  Rather than extended the system call
error interface we added a new ktrace type KTR_SYSERRCAUSE.  Since we
were aiming to aid programmers having to run ktrace seemed sufficent.

FWIW, I found it useful that we made SYSERRCAUSE take a format string.
When debugging complicated mmap usage errors, I often found that a bit
of formatted output is the difference between having to pull out the
kernel debugger and not.  You can sometimes get a similar result if you
decompose the complex conditionals to have multiple error messages, but
it's quite disruptive and we've got enough diffs without having to break
them all apart.

You can see the implementation at:

https://github.com/search?q=repo%3ACTSRD-CHERI%2Fcheribsd%20SYSERRCAUSE&type=code

-- Brooks