On Sat, Jul 28, 2018 at 09:16:39AM +0200, Sebastien Marie wrote:
> 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
>
no objection from me, but i'm not the right person to decide if this is
where emphasis should lie.
jmc
> 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
>
