Document that Landlock exceptions are based on fd's

[mrcnski]

Hello again, really appreciate your work on Landlock. Some feedback:

One thing that wasn't clear to me until recently is that Landlock exceptions/whitelists are based on fd's and not paths.

In the sandboxing example and the path_beneath_rules example, paths are used for the exceptions, which can easily lead one to a false impression. It's partially my fault for not digging into the API to find out that it actually fundamentally accepts fd's. But even the add_rules methods do not make this clear, you have to click one more time into Rule.

Is it possible to document somewhere to make this a bit more explicit?

(This bit me recently. I wrote a design which assumed that another process can create new files at the whitelisted paths, and the sandboxed process could access them. Only after implementing it did I find out it didn't work.)

[mrcnski]

@l0kod I'm taking another look at path_beneath_rules as I'm adding the documentation. Do you think it makes sense to return an error on any path that doesn't correspond to a file, instead of silently ignoring it? Then the caller can decide if they want to ignore errors or not. I guess this would be breaking, but in a way that could identify logical errors that had gone unnoticed.

[l0kod]

The path_beneath_rules()'s documentation says "Silently ignores paths that cannot be opened", and this behavior makes it easier to quickly write a sandbox, so we should keep it. This is just an helper, and we should be free to implement stricter helpers for specific sandboxes.

However, it could be interesting to have a generic PathBeneathIterator type implementing Compatibility, and we could replace the current path_beneath_rules() implementation with a specific call to this iterator.