mmap.2: document new MAP_FIXED_NOREPLACE flag
Subsystems (2)
PATCH 1/1 mmap.2: document new MAP_FIXED_NOREPLACE flag
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new MAP_FIXED_NOREPLACE flag which allows the caller to atomicaly probe for a given address range.
---
Hi,
Andrew's sent the MAP_FIXED_NOREPLACE to Linus for the upcoming merge window. So here we go with the man page update.
man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)
man2/mmap.2 +27 -0
@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED. +.TP +.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" +Similar to MAP_FIXED with respect to the +.I +addr +enforcement, but different in that MAP_FIXED_NOREPLACE never clobbers a pre-existing +mapped range. If the requested range would collide with an existing +mapping, then this call fails with +.B EEXIST. +This flag can therefore be used as a way to atomically (with respect to other +threads) attempt to map an address range: one thread will succeed; all others +will report failure. Please note that older kernels which do not recognize this +flag will typically (upon detecting a collision with a pre-existing mapping) +fall back to a "non-MAP_FIXED" type of behavior: they will return an address that +is different than the requested one. Therefore, backward-compatible software +should check the returned address against the requested address. .TP .B MAP_GROWSDOWN This flag is used for stacks.
@@ -487,6 +508,12 @@ is not a valid file descriptor (and .B MAP_ANONYMOUS was not set). .TP +.B EEXIST +range covered by +.IR addr , +.IR length +is clashing with an existing mapping. +.TP .B EINVAL We don't like .IR addr ,
Signature · 1 line
2.16.3
Quoted 20 lines · On Wed, Apr 11, 2018 at 2:04 PM, <[email protected]> wrote:
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>---
Hi,
Andrew's sent theMAP_FIXED_NOREPLACEto Linus for the upcoming merge window. So here we go with the man page update.man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)man2/mmap.2 +0
-0
man2/mmap.2 Examples include · line 268
Quoted 8 lines
man2/mmap.2 +5
-0@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED.
This still looks wrong to me. There are legitimate uses for MAP_FIXED, and for most users of MAP_FIXED that I'm aware of, MAP_FIXED_NOREPLACE wouldn't work while MAP_FIXED works perfectly well.
MAP_FIXED is for when you have already reserved the targeted memory area using another VMA; MAP_FIXED_NOREPLACE is for when you haven't. Please don't make it sound as if MAP_FIXED is always wrong.
Quoted 20 lines
man2/mmap.2 +16
-0+.TP +.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" +Similar to MAP_FIXED with respect to the +.I +addr +enforcement, but different in that MAP_FIXED_NOREPLACE never clobbers a pre-existing +mapped range. If the requested range would collide with an existing +mapping, then this call fails with +.B EEXIST. +This flag can therefore be used as a way to atomically (with respect to other +threads) attempt to map an address range: one thread will succeed; all others +will report failure. Please note that older kernels which do not recognize this +flag will typically (upon detecting a collision with a pre-existing mapping) +fall back to a "non-MAP_FIXED" type of behavior: they will return an address that +is different than the requested one. Therefore, backward-compatible software +should check the returned address against the requested address. .TP .B MAP_GROWSDOWN This flag is used for stacks.
man2/mmap.2 is not a valid file descriptor (and · line 515
Quoted 8 lines
man2/mmap.2 +5
-0@@ -487,6 +508,12 @@ is not a valid file descriptor (and .B MAP_ANONYMOUS was not set). .TP +.B EEXIST +range covered by +.IR addr , +.IR length +is clashing with an existing mapping.
Maybe add something like ", and MAP_FIXED_NOREPLACE was specified"? I think most manpages explicitly document which error conditions can be triggered by which flags.
Quoted 34 lines · Jann Horn
Quoted 20 lines · On Wed, Apr 11, 2018 at 2:04 PM, <[email protected]> wrote:
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>---
Hi,
Andrew's sent theMAP_FIXED_NOREPLACEto Linus for the upcoming merge window. So here we go with the man page update.man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)man2/mmap.2 +0
-0man2/mmap.2 Examples include · line 268
Quoted 8 lines
man2/mmap.2 +5
-0@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED.This still looks wrong to me. There are legitimate uses for
MAP_FIXED, and for most users ofMAP_FIXEDthat I'm aware of,MAP_FIXED_NOREPLACEwouldn't work whileMAP_FIXEDworks perfectly well.
Quoted 3 lines
MAP_FIXEDis for when you have already reserved the targeted memory area using another VMA;MAP_FIXED_NOREPLACEis for when you haven't. Please don't make it sound as ifMAP_FIXEDis always wrong.
Well, this was suggested by John. I think, nobody is objecting that MAP_FIXED has legitimate usecases. The above text just follows up on the previous section which emphasises the potential memory corruption problems and it suggests that a new flag is safe with that regards.
If you have specific wording that would be better I am open for changes.
Quoted 24 lines
Quoted 24 lines
man2/mmap.2 +17
-0+.TP +.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" +Similar to MAP_FIXED with respect to the +.I +addr +enforcement, but different in that MAP_FIXED_NOREPLACE never clobbers a pre-existing +mapped range. If the requested range would collide with an existing +mapping, then this call fails with +.B EEXIST. +This flag can therefore be used as a way to atomically (with respect to other +threads) attempt to map an address range: one thread will succeed; all others +will report failure. Please note that older kernels which do not recognize this +flag will typically (upon detecting a collision with a pre-existing mapping) +fall back to a "non-MAP_FIXED" type of behavior: they will return an address that +is different than the requested one. Therefore, backward-compatible software +should check the returned address against the requested address. .TP .B MAP_GROWSDOWN This flag is used for stacks.@@ -487,6 +508,12 @@ is not a valid file descriptor (and .B MAP_ANONYMOUS was not set). .TP +.B EEXIST
Quoted 8 lines
man2/mmap.2 is not a valid file descriptor (and · line 515
Quoted 4 lines
man2/mmap.2 +4
-0+range covered by +.IR addr , +.IR length +is clashing with an existing mapping.Maybe add something like ", and
MAP_FIXED_NOREPLACEwas specified"? I think most manpages explicitly document which error conditions can be triggered by which flags.
sure, no objection from me.
Signature · 2 lines
Michal Hocko SUSE Labs
Quoted 39 lines · Michal Hocko
Quoted 34 lines · Jann Horn
Quoted 20 lines · On Wed, Apr 11, 2018 at 2:04 PM, <[email protected]> wrote:
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>---
Hi,
Andrew's sent theMAP_FIXED_NOREPLACEto Linus for the upcoming merge window. So here we go with the man page update.man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)man2/mmap.2 +0
-0man2/mmap.2 Examples include · line 268
Quoted 8 lines
man2/mmap.2 +5
-0@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED.This still looks wrong to me. There are legitimate uses for
MAP_FIXED, and for most users ofMAP_FIXEDthat I'm aware of,MAP_FIXED_NOREPLACEwouldn't work whileMAP_FIXEDworks perfectly well.Quoted 3 lines
MAP_FIXEDis for when you have already reserved the targeted memory area using another VMA;MAP_FIXED_NOREPLACEis for when you haven't. Please don't make it sound as ifMAP_FIXEDis always wrong.
Quoted 6 lines
Well, this was suggested by John. I think, nobody is objecting that
MAP_FIXEDhas legitimate usecases. The above text just follows up on the previous section which emphasises the potential memory corruption problems and it suggests that a new flag is safe with that regards.If you have specific wording that would be better I am open for changes.
I guess I'd probably also want to change the previous text; so I should probably send a followup patch once this one has landed.
Quoted 38 lines
Quoted 24 lines
Quoted 24 lines
man2/mmap.2 +17
-0+.TP +.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" +Similar to MAP_FIXED with respect to the +.I +addr +enforcement, but different in that MAP_FIXED_NOREPLACE never clobbers a pre-existing +mapped range. If the requested range would collide with an existing +mapping, then this call fails with +.B EEXIST. +This flag can therefore be used as a way to atomically (with respect to other +threads) attempt to map an address range: one thread will succeed; all others +will report failure. Please note that older kernels which do not recognize this +flag will typically (upon detecting a collision with a pre-existing mapping) +fall back to a "non-MAP_FIXED" type of behavior: they will return an address that +is different than the requested one. Therefore, backward-compatible software +should check the returned address against the requested address. .TP .B MAP_GROWSDOWN This flag is used for stacks.@@ -487,6 +508,12 @@ is not a valid file descriptor (and .B MAP_ANONYMOUS was not set). .TP +.B EEXISTQuoted 8 lines
man2/mmap.2 is not a valid file descriptor (and · line 515
Quoted 4 lines
man2/mmap.2 +4
-0+range covered by +.IR addr , +.IR length +is clashing with an existing mapping.Maybe add something like ", and
MAP_FIXED_NOREPLACEwas specified"? I think most manpages explicitly document which error conditions can be triggered by which flags.sure, no objection from me.
--
Michal Hocko
SUSE Labs
Quoted 45 lines · Jann Horn
Quoted 44 lines · Michal Hocko
Quoted 34 lines · Jann Horn
Quoted 20 lines · On Wed, Apr 11, 2018 at 2:04 PM, <[email protected]> wrote:
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>---
Hi,
Andrew's sent theMAP_FIXED_NOREPLACEto Linus for the upcoming merge window. So here we go with the man page update.man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)man2/mmap.2 +0
-0man2/mmap.2 Examples include · line 268
Quoted 8 lines
man2/mmap.2 +5
-0@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED.This still looks wrong to me. There are legitimate uses for
MAP_FIXED, and for most users ofMAP_FIXEDthat I'm aware of,MAP_FIXED_NOREPLACEwouldn't work whileMAP_FIXEDworks perfectly well.Quoted 3 lines
MAP_FIXEDis for when you have already reserved the targeted memory area using another VMA;MAP_FIXED_NOREPLACEis for when you haven't. Please don't make it sound as ifMAP_FIXEDis always wrong.Well, this was suggested by John. I think, nobody is objecting that
MAP_FIXEDhas legitimate usecases. The above text just follows up on the previous section which emphasises the potential memory corruption problems and it suggests that a new flag is safe with that regards.
Quoted 4 lines
Quoted 1 line
If you have specific wording that would be better I am open for changes.
I guess I'd probably also want to change the previous text; so I should probably send a followup patch once this one has landed.
yeah, that sounds like a better plan.
Signature · 2 lines
Michal Hocko SUSE Labs
Quoted 45 lines · Jann Horn
Quoted 44 lines · Michal Hocko
Quoted 34 lines · Jann Horn
Quoted 20 lines · On Wed, Apr 11, 2018 at 2:04 PM, <[email protected]> wrote:
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>---
Hi,
Andrew's sent theMAP_FIXED_NOREPLACEto Linus for the upcoming merge window. So here we go with the man page update.man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)man2/mmap.2 +0
-0man2/mmap.2 Examples include · line 268
Quoted 8 lines
man2/mmap.2 +5
-0@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED.This still looks wrong to me. There are legitimate uses for
MAP_FIXED, and for most users ofMAP_FIXEDthat I'm aware of,MAP_FIXED_NOREPLACEwouldn't work whileMAP_FIXEDworks perfectly well.Quoted 3 lines
MAP_FIXEDis for when you have already reserved the targeted memory area using another VMA;MAP_FIXED_NOREPLACEis for when you haven't. Please don't make it sound as ifMAP_FIXEDis always wrong.Well, this was suggested by John. I think, nobody is objecting that
MAP_FIXEDhas legitimate usecases. The above text just follows up on the previous section which emphasises the potential memory corruption problems and it suggests that a new flag is safe with that regards.
Quoted 39 lines
Quoted 1 line
If you have specific wording that would be better I am open for changes.
I guess I'd probably also want to change the previous text; so I should probably send a followup patch once this one has landed.
Quoted 34 lines
Quoted 24 lines
Quoted 24 lines
man2/mmap.2 +17
-0+.TP +.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" +Similar to MAP_FIXED with respect to the +.I +addr +enforcement, but different in that MAP_FIXED_NOREPLACE never clobbers a pre-existing +mapped range. If the requested range would collide with an existing +mapping, then this call fails with +.B EEXIST. +This flag can therefore be used as a way to atomically (with respect to other +threads) attempt to map an address range: one thread will succeed; all others +will report failure. Please note that older kernels which do not recognize this +flag will typically (upon detecting a collision with a pre-existing mapping) +fall back to a "non-MAP_FIXED" type of behavior: they will return an address that +is different than the requested one. Therefore, backward-compatible software +should check the returned address against the requested address. .TP .B MAP_GROWSDOWN This flag is used for stacks.@@ -487,6 +508,12 @@ is not a valid file descriptor (and .B MAP_ANONYMOUS was not set). .TP +.B EEXISTQuoted 8 lines
man2/mmap.2 is not a valid file descriptor (and · line 515
Quoted 4 lines
man2/mmap.2 +4
-0+range covered by +.IR addr , +.IR length +is clashing with an existing mapping.Maybe add something like ", and
MAP_FIXED_NOREPLACEwas specified"? I think most manpages explicitly document which error conditions can be triggered by which flags.sure, no objection from me.
I've added the suggested piece from Jann to the EEXIST error description.
Cheers,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Hi Jann,
Quoted 45 lines · Jann Horn
Quoted 44 lines · Michal Hocko
Quoted 34 lines · Jann Horn
Quoted 20 lines · On Wed, Apr 11, 2018 at 2:04 PM, <[email protected]> wrote:
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>---
Hi,
Andrew's sent theMAP_FIXED_NOREPLACEto Linus for the upcoming merge window. So here we go with the man page update.man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)man2/mmap.2 +0
-0man2/mmap.2 Examples include · line 268
Quoted 8 lines
man2/mmap.2 +5
-0@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED.This still looks wrong to me. There are legitimate uses for
MAP_FIXED, and for most users ofMAP_FIXEDthat I'm aware of,MAP_FIXED_NOREPLACEwouldn't work whileMAP_FIXEDworks perfectly well.Quoted 3 lines
MAP_FIXEDis for when you have already reserved the targeted memory area using another VMA;MAP_FIXED_NOREPLACEis for when you haven't. Please don't make it sound as ifMAP_FIXEDis always wrong.Well, this was suggested by John. I think, nobody is objecting that
MAP_FIXEDhas legitimate usecases. The above text just follows up on the previous section which emphasises the potential memory corruption problems and it suggests that a new flag is safe with that regards.
Quoted 4 lines
Quoted 1 line
If you have specific wording that would be better I am open for changes.
I guess I'd probably also want to change the previous text; so I should probably send a followup patch once this one has landed.
Okay -- I'm ready to take that piece now. Please send me a patch!
Cheers,
Michael
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 34 lines · Jann Horn
Quoted 20 lines · On Wed, Apr 11, 2018 at 2:04 PM, <[email protected]> wrote:
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>---
Hi,
Andrew's sent theMAP_FIXED_NOREPLACEto Linus for the upcoming merge window. So here we go with the man page update.man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)man2/mmap.2 +0
-0man2/mmap.2 Examples include · line 268
Quoted 8 lines
man2/mmap.2 +5
-0@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED.This still looks wrong to me. There are legitimate uses for
MAP_FIXED, and for most users ofMAP_FIXEDthat I'm aware of,MAP_FIXED_NOREPLACEwouldn't work whileMAP_FIXEDworks perfectly well.
Quoted 2 lines
MAP_FIXEDis for when you have already reserved the targeted memory area using another VMA;MAP_FIXED_NOREPLACEis for when you haven't.
That's a nice summary, I hope it shows up in your upcoming patch. I recall that we went back and forth, trying to find a balance of explaining this feature, without providing overly-elaborate examples (which I tend toward).
Quoted 2 lines
Please don't make it sound as if
MAP_FIXEDis always wrong.
Agreed.
thanks,
Signature · 2 lines
John Hubbard NVIDIA
Hello Michal,
Quoted 7 lines · On 04/11/2018 02:04 PM, [email protected] wrote:
From: Michal Hocko <[email protected]>
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>
Thanks! I've applied your patch, and done a little tweaking. The results have already been pushed.
Cheers
Michael
Quoted 54 lines
---
Hi,
Andrew's sent theMAP_FIXED_NOREPLACEto Linus for the upcoming merge window. So here we go with the man page update.man2/mmap.2 | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)man2/mmap.2 +27
-0@@ -261,6 +261,27 @@ Examples include and the PAM libraries .UR http://www.linux-pam.org .UE . +Newer kernels +(Linux 4.17 and later) have a +.B MAP_FIXED_NOREPLACE +option that avoids the corruption problem; if available, MAP_FIXED_NOREPLACE +should be preferred over MAP_FIXED. +.TP +.BR MAP_FIXED_NOREPLACE " (since Linux 4.17)" +Similar to MAP_FIXED with respect to the +.I +addr +enforcement, but different in that MAP_FIXED_NOREPLACE never clobbers a pre-existing +mapped range. If the requested range would collide with an existing +mapping, then this call fails with +.B EEXIST. +This flag can therefore be used as a way to atomically (with respect to other +threads) attempt to map an address range: one thread will succeed; all others +will report failure. Please note that older kernels which do not recognize this +flag will typically (upon detecting a collision with a pre-existing mapping) +fall back to a "non-MAP_FIXED" type of behavior: they will return an address that +is different than the requested one. Therefore, backward-compatible software +should check the returned address against the requested address. .TP .B MAP_GROWSDOWN This flag is used for stacks.@@ -487,6 +508,12 @@ is not a valid file descriptor (and .B MAP_ANONYMOUS was not set). .TP +.B EEXIST +range covered by +.IR addr , +.IR length +is clashing with an existing mapping. +.TP .B EINVAL We don't like .IR addr ,
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Quoted 5 lines · Michael Kerrisk
Hello Michal,
Quoted 2 lines · On 04/11/2018 02:04 PM, [email protected] wrote:
From: Michal Hocko <[email protected]>
Quoted 8 lines
Quoted 5 lines
4.17+ kernels offer a new
MAP_FIXED_NOREPLACEflag which allows the caller to atomicaly probe for a given address range.[wording heavily updated by John Hubbard <[email protected]>]Signed-off-by Michal Hocko <[email protected]>Thanks! I've applied your patch, and done a little tweaking. The results have already been pushed.
Thanks!
Signature · 2 lines
Michal Hocko SUSE Labs