jail.2: Mention EPERM is returned on open directories

[olce]

Summary

The manual page does not directly mention this reason for getting EPERM,
instead referring the reader to chroot(2). We have had some questions
about it recently, in part due to a bug (fixed), and this case is not an
obvious permission/problem, so let's be more explicit.

PR: 280809
MFC after: 3 days
Sponsored by: The FreeBSD Foundation

[ziaee]

lib/libsys/jail.2

558

I don't understand, shouldn't this be in its own entry?

[olce]

lib/libsys/jail.2

558

The current manual page structure is that, in the ERRORS sections, there are multiple "sub-sections" that are exclusive (most concern one function, one concerns both jail_attach() and jail_remove()) except for the last paragraph, which explicitly is an addition concerning three functions that refers the reader to another manual page (chroot(2)).

A priori, I don't want to inline the errors from chroot(2) here, as the list is relatively long, and anyway is common to three of the described functions (repeating it for each one would be very verbose), and because that would open the risk of the lists here and there becoming inconsistent.

My goal, however, is to save readers from having to open chroot(2) for the in-diff-added particular reason of returning EPERM, as this one is very much unintuitive and as such deserves to be mentioned inline.

Are you saying you'd like the added mention be structured like the other "sub-sections", i.e., with .Bl? Or do you want a more profound reorganization?

[olce]

Friendly ping.

[jamie]

Yes, EPERM on open directories may be unexpected, but I don't see that is enough cause to change the long-standing tradition of referring to other manual pages when a function may return the set of errors produced by another function.

[olce]

In D52319#1197903, @jamie wrote:

Yes, EPERM on open directories may be unexpected, but I don't see that is enough cause to change the long-standing tradition of referring to other manual pages when a function may return the set of errors produced by another function.

I'm not proposing to change that tradition, the references to other pages are staying. But I do insist on adding a shortcurt for EPERM, as it is very unintuitive.

In the past year, EPERM occured to me once (and I followed the man page references) and IIRC I had two reports (one as a PR) on the topic of "why EPERM?" in this case. You might say that people who do not read every relevant material are on their own, and that has some truth in it, but why not just cater to them once and for all instead of spending time to respond to bugs or other inquiries? Quickly searching for EPERM in the manual page, although not ideal, is not an unreasonable way of searching for information. And there's not much risk of doc discrepancy at some point, as I don't think we will ever lift the restriction signaled by EPERM in that case.

[jamie]

Very well. I suppose it doesn't hurt.