mprotect.2: Add information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}
PATCH 1/1 mprotect.2: Add information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}
The note regarding PROT_SEM is done based on observation that it is not actually used in mprotect code (as far as i understood it).
--- man2/mprotect.2 | 58 +++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 50 insertions(+), 8 deletions(-)
man2/mprotect.2 +50 -8
@@ -30,12 +30,6 @@ .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and .\" a much improved example program. .\" -.\" FIXME The following protection flags need documenting: -.\" PROT_SEM -.\" PROT_GROWSDOWN -.\" PROT_GROWSUP -.\" PROT_SAO (PowerPC) -.\" .TH MPROTECT 2 2015-07-23 "Linux" "Linux Programmer's Manual" .SH NAME mprotect, pkey_mprotect \- set protection on a region of memory
@@ -60,7 +54,7 @@ that violates the protection, then the kernel generates a signal for the process. .PP .I prot -is either +is a combination of the following access flags: .B PROT_NONE or a bitwise-or of the other values in the following list: .TP 1.1i
@@ -75,6 +69,38 @@ The memory can be modified. .TP .B PROT_EXEC The memory can be executed. +'\" 882ad449046cec136c484dd2b3659fb4c683e0a3 +.TP +.BR PROT_SEM " (since Linux 2.5.7)" +The memory can be used for atomic operations. It was introduced as part of +.BR futex (2) +implementation (in order), but not actually used in any currently supported +architecture so far. +'\" aba46c5027cb59d98052231b36efcbbde9c77a1d ef3d3246a0d06be622867d21af25f997aeeb105f +.TP +.BR PROT_SAO " (since Linux 2.6.26)" +The memory should have strong access ordering. This feature is specific to +PowerPC architecture (version 2.06 of architecture specification adds SAO CPU +feature, and is available on POWER 7 and newer, for example). +.PP +'\" c1dd59582e5b518983b0f4db66f0f8a969139c1b +Additionally (since Linux 2.6.0), +.I prot +can have one of the following flags set: +.TP 1.1i +.B PROT_GROWSUP +Apply protection mode to the whole VMA, which grows up (it should be mapped with +.B MAP_GROWSUP +flag set, which itself is available on IA-64 only, or be stack segment on +HP PARISC). +.TP +.B PROT_GROWSDOWN +Apply protection mode to the whole VMA, which grows down (it should be mapped +with +.B MAP_GROWSDOWN +flag set). +.PP +This is especially useful for stacks and other mappings which can grow. .PP Like .BR mprotect (),
@@ -122,7 +148,23 @@ or not a multiple of the system page size. .RB ( pkey_mprotect ()) \fIpkey\fP has not been allocated with .BR pkey_alloc (2) -.\" Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'. +.TP +.BR EINVAL +Both +.BR PROT_GROWSUP " and " PROT_GROWSDOWN +were specified in +.IR prot . +.TP +.BR EINVAL +Invalid flags specified in +.IR prot . +.TP +.BR EINVAL +(PowerPC architecture) +.B PROT_SAO +specified in +.IR prot , +but SAO hardware feature is no available. .TP .B ENOMEM Internal kernel structures could not be allocated.
Signature · 6 lines
2.10.2 -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
PATCH v2 1/1 mprotect.2: Added information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}
Changes since v1:
* Fixed description of PROT_GROWSUP/PROT_GROWSDOWN from "whole mapping" to "up to end/down to beginning".
* Clarified situation regarding obtaining VMA with VM_GROWSUP/VM_GROWSDOWN bit set.
* Clarified meaning of "invalid flag"
* Some rewording, typo fixes.
--- man2/mprotect.2 | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 57 insertions(+), 8 deletions(-)
man2/mprotect.2 +57 -8
@@ -30,12 +30,6 @@ .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and .\" a much improved example program. .\" -.\" FIXME The following protection flags need documenting: -.\" PROT_SEM -.\" PROT_GROWSDOWN -.\" PROT_GROWSUP -.\" PROT_SAO (PowerPC) -.\" .TH MPROTECT 2 2015-07-23 "Linux" "Linux Programmer's Manual" .SH NAME mprotect, pkey_mprotect \- set protection on a region of memory
@@ -60,7 +54,7 @@ that violates the protection, then the kernel generates a signal for the process. .PP .I prot -is either +is a combination of the following access flags: .B PROT_NONE or a bitwise-or of the other values in the following list: .TP 1.1i
@@ -75,6 +69,42 @@ The memory can be modified. .TP .B PROT_EXEC The memory can be executed. +'\" 882ad449046cec136c484dd2b3659fb4c683e0a3 +.TP +.BR PROT_SEM " (since Linux 2.5.7)" +The memory can be used for atomic operations. It was introduced as part of +.BR futex (2) +implementation (in order), but not actually used in any currently supported +architecture so far. +'\" aba46c5027cb59d98052231b36efcbbde9c77a1d ef3d3246a0d06be622867d21af25f997aeeb105f +.TP +.BR PROT_SAO " (since Linux 2.6.26)" +The memory should have strong access ordering. This feature is specific to +PowerPC architecture (version 2.06 of architecture specification adds SAO CPU +feature, and it is available on POWER 7 or PowerPC A2, for example). +.PP +'\" c1dd59582e5b518983b0f4db66f0f8a969139c1b +Additionally (since Linux 2.6.0), +.I prot +can have one of the following flags set: +.TP 1.1i +'\" mm/mmap.c: +'\" vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) | +'\" mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC; +'\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED. +.B PROT_GROWSUP +Apply protection mode up to the end of the VMA which grows up (it should be a +stack segment on HP PA-RISC, since there are no other ways to map a segment with +.B VM_GROWSUP +even if architecture has support for it.) +.TP +.B PROT_GROWSDOWN +Apply protection mode down to the beginning of the VMA which grows down (it +should be stack segment or mapped with +.B MAP_GROWSDOWN +flag set.) +.PP +This is especially useful for stacks and other mappings which can grow. .PP Like .BR mprotect (),
@@ -122,7 +152,26 @@ or not a multiple of the system page size. .RB ( pkey_mprotect ()) \fIpkey\fP has not been allocated with .BR pkey_alloc (2) -.\" Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'. +.TP +.BR EINVAL +Both +.BR PROT_GROWSUP " and " PROT_GROWSDOWN +were specified in +.IR prot . +.TP +.BR EINVAL +Invalid (other than +.BR PROT_READ ", " PROT_WRITE ", " PROT_EXEC ", " PROT_SEM ", " +.BR PROT_SAO " (on PowerPC only), " PROT_GROWSUP ", " PROT_GROWSDOWN ) +flags specified in +.IR prot . +.TP +.BR EINVAL +(PowerPC architecture) +.B PROT_SAO +specified in +.IR prot , +but SAO hardware feature is not available. .TP .B ENOMEM Internal kernel structures could not be allocated.
Signature · 6 lines
2.10.2 -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH v2] mprotect.2: Added information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}
Hello Eugene,
Thanks. Overall, this looks helpful, but I have some questions, below.
Quoted 39 lines · Eugene Syromyatnikov
Changes since v1:
* Fixed description of PROT_GROWSUP/PROT_GROWSDOWN from "whole mapping" to "up to end/down to beginning".
* Clarified situation regarding obtaining VMA with VM_GROWSUP/VM_GROWSDOWN bit set.
* Clarified meaning of "invalid flag"
* Some rewording, typo fixes.--- man2/mprotect.2 | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 57 insertions(+), 8 deletions(-)man2/mprotect.2 +1
-7@@ -30,12 +30,6 @@ .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and .\" a much improved example program. .\" -.\" FIXME The following protection flags need documenting: -.\" PROT_SEM -.\" PROT_GROWSDOWN -.\" PROT_GROWSUP -.\" PROT_SAO (PowerPC) -.\" .TH MPROTECT 2 2015-07-23 "Linux" "Linux Programmer's Manual" .SH NAME mprotect, pkey_mprotect \- set protection on a region of memory@@ -60,7 +54,7 @@ that violates the protection, then the kernel generates a signal for the process. .PP .I prot -is either +is a combination of the following access flags: .B PROT_NONE or a bitwise-or of the other values in the following list: .TP 1.1i
man2/mprotect.2 The memory can be modified. · line 72
Quoted 4 lines
man2/mprotect.2 +1
-0@@ -75,6 +69,42 @@ The memory can be modified. .TP .B PROT_EXEC The memory can be executed. +'\" 882ad449046cec136c484dd2b3659fb4c683e0a3
Presumably, this is a commit ID from a historical tree? I'd leave such IDs out, since most people probably don't have the histrorical git tree set up locally.
By the way, the usual convention use for comment lines is
.\"
rather than
'\"
man2/mprotect.2 The memory can be modified. · line 77
Quoted 5 lines
man2/mprotect.2 +5
-0+.TP +.BR PROT_SEM " (since Linux 2.5.7)" +The memory can be used for atomic operations. It was introduced as part of +.BR futex (2) +implementation (in order), but not actually used in any currently supported
What do the words "in order" here mean?
man2/mprotect.2 The memory can be modified. · line 86
Quoted 9 lines
man2/mprotect.2 +9
-0+architecture so far. +'\" aba46c5027cb59d98052231b36efcbbde9c77a1d ef3d3246a0d06be622867d21af25f997aeeb105f +.TP +.BR PROT_SAO " (since Linux 2.6.26)" +The memory should have strong access ordering. This feature is specific to +PowerPC architecture (version 2.06 of architecture specification adds SAO CPU +feature, and it is available on POWER 7 or PowerPC A2, for example). +.PP +'\" c1dd59582e5b518983b0f4db66f0f8a969139c1b
Drop previous line (historical git commit ID)
man2/mprotect.2 The memory can be modified. · line 96
Quoted 10 lines
man2/mprotect.2 +10
-0+Additionally (since Linux 2.6.0), +.I prot +can have one of the following flags set: +.TP 1.1i +'\" mm/mmap.c: +'\" vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) | +'\" mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC; +'\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED. +.B PROT_GROWSUP +Apply protection mode up to the end of the VMA which grows up (it should be a
We need to explain VMA in user-space terms. Do you have an idea here?
man2/mprotect.2 The memory can be modified. · line 107
Quoted 11 lines
man2/mprotect.2 +11
-0+stack segment on HP PA-RISC, since there are no other ways to map a segment with +.B VM_GROWSUP +even if architecture has support for it.) +.TP +.B PROT_GROWSDOWN +Apply protection mode down to the beginning of the VMA which grows down (it +should be stack segment or mapped with +.B MAP_GROWSDOWN +flag set.) +.PP +This is especially useful for stacks and other mappings which can grow.
Does "This" mean to PROT_GROWSUP, PROT_GROWSDOWN, or both? (This needs to be made clearer.)
Cheers,
Michael
Quoted 32 lines
man2/mprotect.2 +20
-1.PP Like .BR mprotect (),@@ -122,7 +152,26 @@ or not a multiple of the system page size. .RB ( pkey_mprotect ()) \fIpkey\fP has not been allocated with .BR pkey_alloc (2) -.\" Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'. +.TP +.BR EINVAL +Both +.BR PROT_GROWSUP " and " PROT_GROWSDOWN +were specified in +.IR prot . +.TP +.BR EINVAL +Invalid (other than +.BR PROT_READ ", " PROT_WRITE ", " PROT_EXEC ", " PROT_SEM ", " +.BR PROT_SAO " (on PowerPC only), " PROT_GROWSUP ", " PROT_GROWSDOWN ) +flags specified in +.IR prot . +.TP +.BR EINVAL +(PowerPC architecture) +.B PROT_SAO +specified in +.IR prot , +but SAO hardware feature is not available. .TP .B ENOMEM Internal kernel structures could not be allocated.
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): 0d7def2f-09b0-3790-af04-91393fc8ec58-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Re: [PATCH v2] mprotect.2: Added information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}
Quoted 44 lines · Michael Kerrisk (man-pages)
Hello Eugene,
Thanks. Overall, this looks helpful, but I have some questions, below.
Quoted 39 lines · Eugene Syromyatnikov
Changes since v1:
* Fixed description of PROT_GROWSUP/PROT_GROWSDOWN from "whole mapping" to "up to end/down to beginning".
* Clarified situation regarding obtaining VMA with VM_GROWSUP/VM_GROWSDOWN bit set.
* Clarified meaning of "invalid flag"
* Some rewording, typo fixes.--- man2/mprotect.2 | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 57 insertions(+), 8 deletions(-)man2/mprotect.2 +1
-7@@ -30,12 +30,6 @@ .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and .\" a much improved example program. .\" -.\" FIXME The following protection flags need documenting: -.\" PROT_SEM -.\" PROT_GROWSDOWN -.\" PROT_GROWSUP -.\" PROT_SAO (PowerPC) -.\" .TH MPROTECT 2 2015-07-23 "Linux" "Linux Programmer's Manual" .SH NAME mprotect, pkey_mprotect \- set protection on a region of memory@@ -60,7 +54,7 @@ that violates the protection, then the kernel generates a signal for the process. .PP .I prot -is either +is a combination of the following access flags: .B PROT_NONE or a bitwise-or of the other values in the following list: .TP 1.1i@@ -75,6 +69,42 @@ The memory can be modified.
Quoted 8 lines
man2/mprotect.2 The memory can be modified. · line 72
Quoted 4 lines
man2/mprotect.2 +1
-0.TP .B PROT_EXEC The memory can be executed. +'\" 882ad449046cec136c484dd2b3659fb4c683e0a3Presumably, this is a commit ID from a historical tree? I'd leave such IDs out, since most people probably don't have the histrorical git tree set up locally.
Yes. Ok, I'll remove it.
Quoted 7 lines
By the way, the usual convention use for comment lines is
.\"rather than
'\"
Got it.
Quoted 7 lines
man2/mprotect.2 The memory can be modified. · line 77
Quoted 5 lines
man2/mprotect.2 +5
-0+.TP +.BR PROT_SEM " (since Linux 2.5.7)" +The memory can be used for atomic operations. It was introduced as part of +.BR futex (2) +implementation (in order), but not actually used in any currently supportedWhat do the words "in order" here mean?
Oh, it should be "(in order to guarantee ability to perform atomic operations required by its commands such as FUTEX_WAIT)".
Quoted 12 lines
man2/mprotect.2 The memory can be modified. · line 86
Quoted 9 lines
man2/mprotect.2 +9
-0+architecture so far. +'\" aba46c5027cb59d98052231b36efcbbde9c77a1d ef3d3246a0d06be622867d21af25f997aeeb105f +.TP +.BR PROT_SAO " (since Linux 2.6.26)" +The memory should have strong access ordering. This feature is specific to +PowerPC architecture (version 2.06 of architecture specification adds SAO CPU +feature, and it is available on POWER 7 or PowerPC A2, for example). +.PP +'\" c1dd59582e5b518983b0f4db66f0f8a969139c1bDrop previous line (historical git commit ID)
Quoted 12 lines
man2/mprotect.2 The memory can be modified. · line 96
Quoted 10 lines
man2/mprotect.2 +10
-0+Additionally (since Linux 2.6.0), +.I prot +can have one of the following flags set: +.TP 1.1i +'\" mm/mmap.c: +'\" vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) | +'\" mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC; +'\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED. +.B PROT_GROWSUP +Apply protection mode up to the end of the VMA which grows up (it should be aWe need to explain VMA in user-space terms. Do you have an idea here?
"Mapping", maybe?
Quoted 6 lines
Quoted 6 lines
man2/mprotect.2 +6
-0+stack segment on HP PA-RISC, since there are no other ways to map a segment with +.B VM_GROWSUP +even if architecture has support for it.) +.TP +.B PROT_GROWSDOWN +Apply protection mode down to the beginning of the VMA which grows down (it
Quoted 8 lines
man2/mprotect.2 The memory can be modified. · line 107
Quoted 5 lines
man2/mprotect.2 +5
-0+should be stack segment or mapped with +.B MAP_GROWSDOWN +flag set.) +.PP +This is especially useful for stacks and other mappings which can grow.Does "This" mean to
PROT_GROWSUP,PROT_GROWSDOWN, or both? (This needs to be made clearer.)
I think, after all the additional notes in the flag descriptions themselves regarding their applicability, this note can be removed altogether.
Quoted 42 lines
Cheers,
Michael
Quoted 22 lines
man2/mprotect.2 +13
-1.PP Like .BR mprotect (),@@ -122,7 +152,26 @@ or not a multiple of the system page size. .RB ( pkey_mprotect ()) \fIpkey\fP has not been allocated with .BR pkey_alloc (2) -.\" Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'. +.TP +.BR EINVAL +Both +.BR PROT_GROWSUP " and " PROT_GROWSDOWN +were specified in +.IR prot . +.TP +.BR EINVAL +Invalid (other than +.BR PROT_READ ", " PROT_WRITE ", " PROT_EXEC ", " PROT_SEM ", " +.BR PROT_SAO " (on PowerPC only), " PROT_GROWSUP ", " PROT_GROWSDOWN ) +flags specified in +.IR prot .man2/mprotect.2 or not a multiple of the system page size. · line 177
Quoted 10 lines
man2/mprotect.2 +7
-0+.TP +.BR EINVAL +(PowerPC architecture) +.B PROT_SAO +specified in +.IR prot , +but SAO hardware feature is not available. .TP .B ENOMEM Internal kernel structures could not be allocated.--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Signature · 7 lines
Eugene "eSyr" Syromyatnikov mailto:[email protected] xmpp:eSyr@jabber.{ru|org} -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html