mmap.2: Add description of MAP_SHARED_VALIDATE and MAP_SYNC

Message ID 20171019125817.11580-19-jack@suse.cz
State New
Headers show
Series
  • mmap.2: Add description of MAP_SHARED_VALIDATE and MAP_SYNC
Related show

Commit Message

Jan Kara Oct. 19, 2017, 12:58 p.m.
Signed-off-by: Jan Kara <jack@suse.cz>
---
 man2/mmap.2 | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

Comments

Ross Zwisler Oct. 20, 2017, 9:47 p.m. | #1
On Thu, Oct 19, 2017 at 02:58:17PM +0200, Jan Kara wrote:
> Signed-off-by: Jan Kara <jack@suse.cz>
> ---
>  man2/mmap.2 | 30 ++++++++++++++++++++++++++++++
>  1 file changed, 30 insertions(+)
> 
> diff --git a/man2/mmap.2 b/man2/mmap.2
> index 47c3148653be..598ff0c64f7f 100644
> --- a/man2/mmap.2
> +++ b/man2/mmap.2
> @@ -125,6 +125,21 @@ are carried through to the underlying file.
>  to the underlying file requires the use of
>  .BR msync (2).)
>  .TP
> +.B MAP_SHARED_VALIDATE
> +The same as
> +.B MAP_SHARED
> +except that
> +.B MAP_SHARED
> +mappings ignore unknown flags in
> +.IR flags .
> +In contrast when creating mapping of
> +.B MAP_SHARED_VALIDATE
> +mapping type, the kernel verifies all passed flags are known and fails the
> +mapping with
> +.BR EOPNOTSUPP
> +otherwise. This mapping type is also required to be able to use some mapping
> +flags.
> +.TP

Some small nits:

I think you should maybe include a "(since Linux 4.15)" type note after the
MAP_SHARED_VALIDATE header.  You also need to update the following line:

       Both of these flags are described in POSIX.1-2001 and POSIX.1-2008.

Which used to refer to MAP_SYNC and MAP_PRIVATE.
Jan Kara Oct. 24, 2017, 1:27 p.m. | #2
On Fri 20-10-17 15:47:53, Ross Zwisler wrote:
> On Thu, Oct 19, 2017 at 02:58:17PM +0200, Jan Kara wrote:
> > Signed-off-by: Jan Kara <jack@suse.cz>
> > ---
> >  man2/mmap.2 | 30 ++++++++++++++++++++++++++++++
> >  1 file changed, 30 insertions(+)
> > 
> > diff --git a/man2/mmap.2 b/man2/mmap.2
> > index 47c3148653be..598ff0c64f7f 100644
> > --- a/man2/mmap.2
> > +++ b/man2/mmap.2
> > @@ -125,6 +125,21 @@ are carried through to the underlying file.
> >  to the underlying file requires the use of
> >  .BR msync (2).)
> >  .TP
> > +.B MAP_SHARED_VALIDATE
> > +The same as
> > +.B MAP_SHARED
> > +except that
> > +.B MAP_SHARED
> > +mappings ignore unknown flags in
> > +.IR flags .
> > +In contrast when creating mapping of
> > +.B MAP_SHARED_VALIDATE
> > +mapping type, the kernel verifies all passed flags are known and fails the
> > +mapping with
> > +.BR EOPNOTSUPP
> > +otherwise. This mapping type is also required to be able to use some mapping
> > +flags.
> > +.TP
> 
> Some small nits:
> 
> I think you should maybe include a "(since Linux 4.15)" type note after the
> MAP_SHARED_VALIDATE header.  You also need to update the following line:
> 
>        Both of these flags are described in POSIX.1-2001 and POSIX.1-2008.
> 
> Which used to refer to MAP_SYNC and MAP_PRIVATE.

Thanks, I've fixed these.

								Honza
Ross Zwisler Oct. 24, 2017, 2:55 p.m. | #3
On Tue, Oct 24, 2017 at 03:27:13PM +0200, Jan Kara wrote:
> On Fri 20-10-17 15:47:53, Ross Zwisler wrote:
> > On Thu, Oct 19, 2017 at 02:58:17PM +0200, Jan Kara wrote:
> > > Signed-off-by: Jan Kara <jack@suse.cz>
> > > ---
> > >  man2/mmap.2 | 30 ++++++++++++++++++++++++++++++
> > >  1 file changed, 30 insertions(+)
> > > 
> > > diff --git a/man2/mmap.2 b/man2/mmap.2
> > > index 47c3148653be..598ff0c64f7f 100644
> > > --- a/man2/mmap.2
> > > +++ b/man2/mmap.2
> > > @@ -125,6 +125,21 @@ are carried through to the underlying file.
> > >  to the underlying file requires the use of
> > >  .BR msync (2).)
> > >  .TP
> > > +.B MAP_SHARED_VALIDATE
> > > +The same as
> > > +.B MAP_SHARED
> > > +except that
> > > +.B MAP_SHARED
> > > +mappings ignore unknown flags in
> > > +.IR flags .
> > > +In contrast when creating mapping of
> > > +.B MAP_SHARED_VALIDATE
> > > +mapping type, the kernel verifies all passed flags are known and fails the
> > > +mapping with
> > > +.BR EOPNOTSUPP
> > > +otherwise. This mapping type is also required to be able to use some mapping
> > > +flags.
> > > +.TP
> > 
> > Some small nits:
> > 
> > I think you should maybe include a "(since Linux 4.15)" type note after the
> > MAP_SHARED_VALIDATE header.  You also need to update the following line:
> > 
> >        Both of these flags are described in POSIX.1-2001 and POSIX.1-2008.
> > 
> > Which used to refer to MAP_SYNC and MAP_PRIVATE.
> 
> Thanks, I've fixed these.

Cool, you can add my:

Reviewed-by: Ross Zwisler <ross.zwisler@linux.intel.com>

Patch

diff --git a/man2/mmap.2 b/man2/mmap.2
index 47c3148653be..598ff0c64f7f 100644
--- a/man2/mmap.2
+++ b/man2/mmap.2
@@ -125,6 +125,21 @@  are carried through to the underlying file.
 to the underlying file requires the use of
 .BR msync (2).)
 .TP
+.B MAP_SHARED_VALIDATE
+The same as
+.B MAP_SHARED
+except that
+.B MAP_SHARED
+mappings ignore unknown flags in
+.IR flags .
+In contrast when creating mapping of
+.B MAP_SHARED_VALIDATE
+mapping type, the kernel verifies all passed flags are known and fails the
+mapping with
+.BR EOPNOTSUPP
+otherwise. This mapping type is also required to be able to use some mapping
+flags.
+.TP
 .B MAP_PRIVATE
 Create a private copy-on-write mapping.
 Updates to the mapping are not visible to other processes
@@ -352,6 +367,21 @@  option.
 Because of the security implications,
 that option is normally enabled only on embedded devices
 (i.e., devices where one has complete control of the contents of user memory).
+.TP
+.BR MAP_SYNC " (since Linux 4.15)"
+This flags is available only with
+.B MAP_SHARED_VALIDATE
+mapping type. Mappings of
+.B MAP_SHARED
+type will silently ignore this flag.
+This flag is supported only for files supporting DAX (direct mapping of persistent
+memory). For other files, creating mapping with this flag results in
+.B EOPNOTSUPP
+error. Shared file mappings with this flag provide the guarantee that while
+some memory is writeably mapped in the address space of the process, it will
+be visible in the same file at the same offset even after the system crashes or
+is rebooted. This allows users of such mappings to make data modifications
+persistent in a more efficient way using appropriate CPU instructions.
 .PP
 Of the above flags, only
 .B MAP_FIXED