Hi,
I think some reorganisation in unveil(2) man page could be good for
comprehension.
The diff belows makes the man page follow the structure for paragraphs:
DESCRIPTION
§1. global description (unveil removes visibility of the entire filesystem...)
§2. unveil locking
§3. flags description ("rwxc")
§4. behavior when argument `path' is a directory (the directory is
remembered and implications with remove/recreate)
§5. behavior when argument `path' isn't a directory (the name in
directory is remembered and implications with remove/recreate)
§6. what when unveil violation occurs (EACCESS or ENOENT)
§7. general recommandation and best practice
my diff mostly moves sentences between §4, §5 and §7. §5 is a new
paragraph.
I think it makes more clear how unveil(2) behave regarding the kind of
`path' (is directory or not).
Before, some elements were "hidden" in the last paragraph about "general
recommandation, best practice, and implications for remove/recreate
depending if `path' is a directory or not".
While here, correct a typo in E2BIG error description: "The addition of
path would exceed the per-process limit for unveiled paths." instead of
"for pledged paths".
Thanks.
--
Sebastien Marie
Index: /home/semarie/repos/openbsd/src/lib/libc/sys/unveil.2
===================================================================
RCS file: /cvs/src/lib/libc/sys/unveil.2,v
retrieving revision 1.5
diff -u -p -r1.5 unveil.2
--- /home/semarie/repos/openbsd/src/lib/libc/sys/unveil.2 27 Jul 2018
19:14:45 -0000 1.5
+++ /home/semarie/repos/openbsd/src/lib/libc/sys/unveil.2 28 Jul 2018
07:04:54 -0000
@@ -98,6 +98,16 @@ using
if and only if no more specific matching
.Fn unveil
exists at a lower level.
+Directories are remembered at the time of a call to
+.Fn unveil .
+This means that a directory that is removed and recreated after a call to
+.Fn unveil
+will appear to not exist.
+.Pp
+Non directories are remembered by name within their containing directory,
+and so may be created, removed, or re-created after a call to
+.Fn unveil
+and still appear to exist.
.Pp
Attempts to access paths not allowed by
.Nm
@@ -119,16 +129,6 @@ in an application will require lots of s
of the interfaces called.
In most cases it is best practice to unveil the directories
in which an application makes use of files.
-It is important to consider that directory results are remembered at
-the time of a call to
-.Fn unveil .
-This means that a directory that is removed and recreated after a call to
-.Fn unveil
-will appear to not exist.
-Non directories are remembered by name within their containing directory,
-and so may be created, removed, or re-created after a call to
-.Fn unveil
-and still appear to exist.
.Sh RETURN VALUES
.Fn unveil
returns 0 on success or -1 on failure.
@@ -137,7 +137,7 @@ returns 0 on success or -1 on failure.
.It E2BIG
The addition of
.Ar path
-would exceed the per-process limit for pledged paths.
+would exceed the per-process limit for unveiled paths.
.It ENOENT
A directory in
.Ar path
