Re: [PATCH] Implement the mlock2 function

[Rical Jasan <ricaljasan at pacific dot net>]

On 11/24/2017 08:59 AM, Florian Weimer wrote:
> diff --git a/manual/memory.texi b/manual/memory.texi
> index 3f5dd90260..1b431bf5da 100644
> --- a/manual/memory.texi
> +++ b/manual/memory.texi
> @@ -3337,6 +3337,36 @@ The calling process is not superuser.
>  The kernel does not provide @code{mlock} capability.
>  
>  @end table
> +@end deftypefun
> +
> +@deftypefun int mlock2 (const void *@var{addr}, size_t @var{len}, unsigned int @var{flags})
> +@standards{Linux, sys/mman.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +
> +This function is similar to @code{mlock}.  If @var{flags} is zero, a
> +call to @code{mlock2} behaves exactly as the equivalent call to @code{mlock}.

This is fine.  As a matter of form, I think it would be nice to say
something about how mlock2 is different from mlock, but I'm not sure
there is much to else to say than, "..., but it accepts a flags
argument", so I guess that's obvious enough.

> +
> +The @var{flags} argument must be a combination of zero or more of the
> +following flags:
> +
> +@vtable @code
> +@item MLOCK_ONFAULT
> +@standards{Linux, sys/mman.h}
> +Only those pages in the specified address range which are already in
> +memory are locked immediately.  Additional pages in the range are
> +automatically locked in case of a page fault and allocation of memory.
> +@end vtable
> +
> +Like @code{mlock}, @code{mlock2} returns zero on success and @code{-1}

I thought you were in the @math camp for return values.  :P

> +on failure, setting @code{errno} accordingly.  Additional @code{errno}
> +values defined for @code{mlock2} are:
> +
> +@table @code
> +@item EINVAL
> +The specified (non-zero) @var{flags} argument is not supported by this
> +system.
> +@end table
> +@end deftypefun
>  
>  You can lock @emph{all} a process' memory with @code{mlockall}.  You
>  unlock memory with @code{munlock} or @code{munlockall}.
> @@ -3346,8 +3376,6 @@ To avoid all page faults in a C program, you have to use
>  from the C code, e.g. the stack and automatic variables, and you
>  wouldn't know what address to tell @code{mlock}.
>  
> -@end deftypefun
> -

Good catch.

>  @deftypefun int munlock (const void *@var{addr}, size_t @var{len})
>  @standards{POSIX.1b, sys/mman.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The rest of the patch looked OK to me, but I'm not able to give an
authoritative ACK on it.  Seemed straightforward though.

Rical