seccomp
Q: seccomp_syscall_resolve_name_arch(...) is confusing, docs arguably wrong
The seccomp_syscall_resolve_name(), seccomp_syscall_resolve_name_arch(), and seccomp_syscall_resolve_name_rewrite() functions resolve the commonly used syscall name to the syscall number used by the kernel and the rest of the libseccomp API
I've been down a bit of a rabbithole. This sentence fragment is wrong, impossible, or maybe just misleadingly incomplete. Correcting it might have helped me learn libseccomp quicker.
The numbers returned by resolve_name() and resolve_name_arch() are different. resolve_name_arch()'s result can be passed to resolve_num_arch(), using the same arch value. But it should not be passed to "the rest of the libseccomp API". (Unless you know arch is native - but then why are you using resolve_name_arch()? Or unless the return value was negative, but I'm not sure why you would ever rely on that).
Specifically, seccomp_rule_add() takes either a native or a pseudo syscall NR. So you should pass it the result of resolve_name(). You shouldn't need to use resolve_name_arch(), as seccomp_rule_add() will convert the NR to whatever arch(s) the filter is set to.
There's a second implication, which systemd got wrong and which is what put me on this journey :). seccomp_resolve_num_arch() should be passed SCMP_ARCH_NATIVE, unless the syscall number specifically came from seccomp_resolve_name_arch(). systemd got it wrong, but I didn't guess that line was wrong, and so my attempts to investigate the resulting problem led me to a wrong understanding of the libseccomp functions.
This gets a bit circular. It's not clear what you'd ever be doing with these non-native, non-pseudo syscall numbers... and hence why we don't have seccomp_resolve_num() instead of seccomp_resolve_num_arch().
The best solution might be to add seccomp_resolve_num(), and then move the documentation of the _arch() variants either in a separate page, or at least in a paragraph of their own. Including some little disclaimer about their obscurity.
While I'm a big proponent of documentation, I'm going to be honest and say that I'm definitely not a technical writer. I do my best, but there are plenty of times where the resulting message isn't very clear.
If you have suggestions - and it sounds like you do - on how to make the manpage more clear, or correct, I would strongly encourage you to submit a patch/PR, that's the quickest way to get it changed (and you earn my undying gratitude for a doc fix!).
Hi @sourcejedi, It's been a few years without any updates to this issue so I'm going to close this out, but my comment still stands: if you want to contribute any documentation/comment improvements we would be very happy to have them in the library!