[PATCH 0/2] prctl.2 and kcmp.2 updated

[PATCH 0/2] prctl.2 and kcmp.2 updated

[Cyrill Gorcunov]

Hi Michael,

here is a slightly updated version of patches for prctl (PR_SET_MM)
and kcmp syscall. Please review.

[PATCH 0/2] prctl.2 and kcmp.2 updated

[Cyrill Gorcunov]

Hi Michael,

here is a slightly updated version of patches for prctl (PR_SET_MM)
and kcmp syscall. Please review.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

CC: Pavel Emelyanov <xemul@parallels.com>
Signed-off-by: Cyrill Gorcunov <gorcunov@openvz.org>
---
 man2/prctl.2 |  104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 104 insertions(+), 0 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index effad2a..7a50ac1 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -378,6 +378,110 @@ Return the current per-process machine check kill policy.
 All unused
 .BR prctl ()
 arguments must be zero.
+.TP
+.BR PR_SET_MM " (since Linux 3.3)"
+Allows a user to modify certain kernel memory map descriptor fields
+of the calling process.
+Usually these fields are set by the kernel and dynamic loader (see
+.BR ld.so (8)
+for more information) and a regular application should not use this feature.
+Still there are cases such as self-modifying programs, where a program might
+find it useful to change its own memory map.
+The kernel must be built with
+.BR CONFIG_CHECKPOINT_RESTORE
+option turned on, otherwise this feature will not be accessible
+from a user space level.
+The calling process must have
+.BR CAP_SYS_RESOURCE
+(see
+.BR capabilities (7)
+for details) capability granted.
+The value in
+.I arg2
+is one of the options below, while
+.I arg3
+provides a new value for this option.
+
+.BR PR_SET_MM_START_CODE
+to set the address above which program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or shareable (see
+.BR mprotect (2)
+and
+.BR mmap (2)
+for more information).
+
+.BR PR_SET_MM_END_CODE
+to set the address below which program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or shareable.
+
+.BR PR_SET_MM_START_DATA
+to set the address above which program data+bss is placed.
+The corresponding memory area must be readable and writable,
+but not executable or shareable.
+
+.B PR_SET_MM_END_DATA
+to set the address below which program data+bss is placed.
+The corresponding memory area must be readable and writable,
+but not executable or shareable.
+
+.BR PR_SET_MM_START_STACK
+to set the start address of the stack.
+The corresponding memory area must be readable and writable.
+
+.BR PR_SET_MM_START_BRK
+to set the address above which program heap can be expanded with
+.BR brk (2)
+call.
+The address must not be greater than ending address of
+the current program data segment, neither it may exceed
+resource limit for data (see
+.BR setrlimit (2)
+for more information).
+
+.BR PR_SET_MM_BRK
+to set the current
+.BR brk (2)
+value.
+The requirements for address are the same as for
+.BR PR_SET_MM_START_BRK
+option.
+
+.BR PR_SET_MM_ARG_START
+to set the address above which program command line is placed.
+
+.BR PR_SET_MM_ARG_END
+to set the address below which program command line is placed.
+
+.BR PR_SET_MM_ENV_START
+to set the address above which program environment is placed.
+
+.BR PR_SET_MM_ENV_END
+to set the address below which program environment is placed.
+
+The address passed with
+.BR PR_SET_MM_ARG_START ,
+.BR PR_SET_MM_ARG_END ,
+.BR PR_SET_MM_ENV_START ,
+.BR PR_SET_MM_ENV_END ,
+should belong to a process stack area, thus corresponding memory area
+must be readable, writable and (depending on the kernel
+configuration) has
+.BR MAP_GROWSDOWN
+attribute set (see
+.BR mmap (2)
+for details).
+
+.BR PR_SET_MM_AUXV
+to set a new auxiliary vector.
+The
+.I arg3
+argument should provide the address of the vector.
+The
+.I arg4
+is the size of the vector.
+.\"
 .SH "RETURN VALUE"
 On success,
 .BR PR_GET_DUMPABLE ,
-- 
1.7.7.6

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

Hello Cyrill,

The PR_SET_MM operation adds a number of new error cases to prctl(2).
Could you extend you patch to add these under ERRORS?

Thanks,

Michael


On Sat, Mar 10, 2012 at 9:47 AM, Cyrill Gorcunov <gorcunov@openvz.org> wrote:
> CC: Pavel Emelyanov <xemul@parallels.com>
> Signed-off-by: Cyrill Gorcunov <gorcunov@openvz.org>
> ---
>  man2/prctl.2 |  104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 104 insertions(+), 0 deletions(-)
>
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index effad2a..7a50ac1 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -378,6 +378,110 @@ Return the current per-process machine check kill policy.
>  All unused
>  .BR prctl ()
>  arguments must be zero.
> +.TP
> +.BR PR_SET_MM " (since Linux 3.3)"
> +Allows a user to modify certain kernel memory map descriptor fields
> +of the calling process.
> +Usually these fields are set by the kernel and dynamic loader (see
> +.BR ld.so (8)
> +for more information) and a regular application should not use this feature.
> +Still there are cases such as self-modifying programs, where a program might
> +find it useful to change its own memory map.
> +The kernel must be built with
> +.BR CONFIG_CHECKPOINT_RESTORE
> +option turned on, otherwise this feature will not be accessible
> +from a user space level.
> +The calling process must have
> +.BR CAP_SYS_RESOURCE
> +(see
> +.BR capabilities (7)
> +for details) capability granted.
> +The value in
> +.I arg2
> +is one of the options below, while
> +.I arg3
> +provides a new value for this option.
> +
> +.BR PR_SET_MM_START_CODE
> +to set the address above which program text can run.
> +The corresponding memory area must be readable and executable,
> +but not writable or shareable (see
> +.BR mprotect (2)
> +and
> +.BR mmap (2)
> +for more information).
> +
> +.BR PR_SET_MM_END_CODE
> +to set the address below which program text can run.
> +The corresponding memory area must be readable and executable,
> +but not writable or shareable.
> +
> +.BR PR_SET_MM_START_DATA
> +to set the address above which program data+bss is placed.
> +The corresponding memory area must be readable and writable,
> +but not executable or shareable.
> +
> +.B PR_SET_MM_END_DATA
> +to set the address below which program data+bss is placed.
> +The corresponding memory area must be readable and writable,
> +but not executable or shareable.
> +
> +.BR PR_SET_MM_START_STACK
> +to set the start address of the stack.
> +The corresponding memory area must be readable and writable.
> +
> +.BR PR_SET_MM_START_BRK
> +to set the address above which program heap can be expanded with
> +.BR brk (2)
> +call.
> +The address must not be greater than ending address of
> +the current program data segment, neither it may exceed
> +resource limit for data (see
> +.BR setrlimit (2)
> +for more information).
> +
> +.BR PR_SET_MM_BRK
> +to set the current
> +.BR brk (2)
> +value.
> +The requirements for address are the same as for
> +.BR PR_SET_MM_START_BRK
> +option.
> +
> +.BR PR_SET_MM_ARG_START
> +to set the address above which program command line is placed.
> +
> +.BR PR_SET_MM_ARG_END
> +to set the address below which program command line is placed.
> +
> +.BR PR_SET_MM_ENV_START
> +to set the address above which program environment is placed.
> +
> +.BR PR_SET_MM_ENV_END
> +to set the address below which program environment is placed.
> +
> +The address passed with
> +.BR PR_SET_MM_ARG_START ,
> +.BR PR_SET_MM_ARG_END ,
> +.BR PR_SET_MM_ENV_START ,
> +.BR PR_SET_MM_ENV_END ,
> +should belong to a process stack area, thus corresponding memory area
> +must be readable, writable and (depending on the kernel
> +configuration) has
> +.BR MAP_GROWSDOWN
> +attribute set (see
> +.BR mmap (2)
> +for details).
> +
> +.BR PR_SET_MM_AUXV
> +to set a new auxiliary vector.
> +The
> +.I arg3
> +argument should provide the address of the vector.
> +The
> +.I arg4
> +is the size of the vector.
> +.\"
>  .SH "RETURN VALUE"
>  On success,
>  .BR PR_GET_DUMPABLE ,
> --
> 1.7.7.6
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

Hello Cyrill,

The PR_SET_MM operation adds a number of new error cases to prctl(2).
Could you extend you patch to add these under ERRORS?

Thanks,

Michael


On Sat, Mar 10, 2012 at 9:47 AM, Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org> wrote:
> CC: Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org>
> Signed-off-by: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
> ---
>  man2/prctl.2 |  104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 104 insertions(+), 0 deletions(-)
>
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index effad2a..7a50ac1 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -378,6 +378,110 @@ Return the current per-process machine check kill policy.
>  All unused
>  .BR prctl ()
>  arguments must be zero.
> +.TP
> +.BR PR_SET_MM " (since Linux 3.3)"
> +Allows a user to modify certain kernel memory map descriptor fields
> +of the calling process.
> +Usually these fields are set by the kernel and dynamic loader (see
> +.BR ld.so (8)
> +for more information) and a regular application should not use this feature.
> +Still there are cases such as self-modifying programs, where a program might
> +find it useful to change its own memory map.
> +The kernel must be built with
> +.BR CONFIG_CHECKPOINT_RESTORE
> +option turned on, otherwise this feature will not be accessible
> +from a user space level.
> +The calling process must have
> +.BR CAP_SYS_RESOURCE
> +(see
> +.BR capabilities (7)
> +for details) capability granted.
> +The value in
> +.I arg2
> +is one of the options below, while
> +.I arg3
> +provides a new value for this option.
> +
> +.BR PR_SET_MM_START_CODE
> +to set the address above which program text can run.
> +The corresponding memory area must be readable and executable,
> +but not writable or shareable (see
> +.BR mprotect (2)
> +and
> +.BR mmap (2)
> +for more information).
> +
> +.BR PR_SET_MM_END_CODE
> +to set the address below which program text can run.
> +The corresponding memory area must be readable and executable,
> +but not writable or shareable.
> +
> +.BR PR_SET_MM_START_DATA
> +to set the address above which program data+bss is placed.
> +The corresponding memory area must be readable and writable,
> +but not executable or shareable.
> +
> +.B PR_SET_MM_END_DATA
> +to set the address below which program data+bss is placed.
> +The corresponding memory area must be readable and writable,
> +but not executable or shareable.
> +
> +.BR PR_SET_MM_START_STACK
> +to set the start address of the stack.
> +The corresponding memory area must be readable and writable.
> +
> +.BR PR_SET_MM_START_BRK
> +to set the address above which program heap can be expanded with
> +.BR brk (2)
> +call.
> +The address must not be greater than ending address of
> +the current program data segment, neither it may exceed
> +resource limit for data (see
> +.BR setrlimit (2)
> +for more information).
> +
> +.BR PR_SET_MM_BRK
> +to set the current
> +.BR brk (2)
> +value.
> +The requirements for address are the same as for
> +.BR PR_SET_MM_START_BRK
> +option.
> +
> +.BR PR_SET_MM_ARG_START
> +to set the address above which program command line is placed.
> +
> +.BR PR_SET_MM_ARG_END
> +to set the address below which program command line is placed.
> +
> +.BR PR_SET_MM_ENV_START
> +to set the address above which program environment is placed.
> +
> +.BR PR_SET_MM_ENV_END
> +to set the address below which program environment is placed.
> +
> +The address passed with
> +.BR PR_SET_MM_ARG_START ,
> +.BR PR_SET_MM_ARG_END ,
> +.BR PR_SET_MM_ENV_START ,
> +.BR PR_SET_MM_ENV_END ,
> +should belong to a process stack area, thus corresponding memory area
> +must be readable, writable and (depending on the kernel
> +configuration) has
> +.BR MAP_GROWSDOWN
> +attribute set (see
> +.BR mmap (2)
> +for details).
> +
> +.BR PR_SET_MM_AUXV
> +to set a new auxiliary vector.
> +The
> +.I arg3
> +argument should provide the address of the vector.
> +The
> +.I arg4
> +is the size of the vector.
> +.\"
>  .SH "RETURN VALUE"
>  On success,
>  .BR PR_GET_DUMPABLE ,
> --
> 1.7.7.6
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Wed, Mar 21, 2012 at 06:21:19AM +1300, Michael Kerrisk (man-pages) wrote:
> Hello Cyrill,
> 
> The PR_SET_MM operation adds a number of new error cases to prctl(2).
> Could you extend you patch to add these under ERRORS?
> 

Yeah, will try to implement today (gimme some time please).

	Cyrill

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Wed, Mar 21, 2012 at 06:21:19AM +1300, Michael Kerrisk (man-pages) wrote:
> Hello Cyrill,
> 
> The PR_SET_MM operation adds a number of new error cases to prctl(2).
> Could you extend you patch to add these under ERRORS?
> 

Yeah, will try to implement today (gimme some time please).

	Cyrill
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Wed, Mar 21, 2012 at 06:21:19AM +1300, Michael Kerrisk (man-pages) wrote:
> Hello Cyrill,
> 
> The PR_SET_MM operation adds a number of new error cases to prctl(2).
> Could you extend you patch to add these under ERRORS?
> 

Hi Michael,

here is an update on previous patch. Please take a look and
tell me what you think when you get time. Complains are welcome!

	Cyrill
---
>From 10dbf8dc2e40426c56a6d2a2414bcb9d3a0f5ff3 Mon Sep 17 00:00:00 2001
From: Cyrill Gorcunov <gorcunov@openvz.org>
Date: Wed, 21 Mar 2012 02:20:11 +0400
Subject: [PATCH] prctl.2: Update description for PR_SET_MM option

New feature PR_SET_MM_EXE_FILE added, also
error codes updated.

Signed-off-by: Cyrill Gorcunov <gorcunov@openvz.org>
---
 man2/prctl.2 |   70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 69 insertions(+), 1 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 7a50ac1..de15426 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -481,6 +481,30 @@ argument should provide the address of the vector.
 The
 .I arg4
 is the size of the vector.
+
+.BR PR_SET_MM_EXE_FILE
+to supersede
+.IR /proc/pid/exe
+symbolic link with a new one pointing to a new executable file
+which descriptor is provided provided in the
+.I arg3
+argument.
+The file descriptor should be obtaned with a regular
+.BR open (2)
+call.
+
+To change the symlink, one needs to unmap all existing
+executable memory areas being created by the kernel itself
+(for example the kernel usually creates at least one executable
+memory area for Elf file
+.IR \.text
+section).
+
+The second limitation is that such transition can be done once
+in a process life time.
+Any furter attempts will be rejected.
+This should help system administrators to monitor the unusual
+symlinks transitions over all process running in a system.
 .\"
 .SH "RETURN VALUE"
 On success,
@@ -515,7 +539,9 @@ is not recognized.
 is
 .BR PR_MCE_KILL
 or
-.BR PR_MCE_KILL_GET ,
+.BR PR_MCE_KILL_GET
+or
+.BR PR_SET_MM ,
 and unused
 .BR prctl ()
 arguments were not specified as zero.
@@ -563,6 +589,48 @@ is
 and the caller does not have the
 .B CAP_SETPCAP
 capability.
+.TP
+.B EPERM
+.I option
+is
+.BR PR_SET_MM ,
+and the caller does not have the
+.B CAP_SYS_RESOURCE
+capability.
+.TP
+.B EACCES
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the file is not executable one.
+.TP
+.B EBUSY
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the second attempt to change
+.I /proc/pid/exe
+symlink is prohibited.
+.TP
+.B EBADF
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the file descriptor passed in
+.I arg4
+is not found.
 .\" The following can't actually happen, because prctl() in
 .\" seccomp mode will cause SIGKILL.
 .\" .TP
-- 
1.7.7.6

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Wed, Mar 21, 2012 at 06:21:19AM +1300, Michael Kerrisk (man-pages) wrote:
> Hello Cyrill,
> 
> The PR_SET_MM operation adds a number of new error cases to prctl(2).
> Could you extend you patch to add these under ERRORS?
> 

Hi Michael,

here is an update on previous patch. Please take a look and
tell me what you think when you get time. Complains are welcome!

	Cyrill
---
>From 10dbf8dc2e40426c56a6d2a2414bcb9d3a0f5ff3 Mon Sep 17 00:00:00 2001
From: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
Date: Wed, 21 Mar 2012 02:20:11 +0400
Subject: [PATCH] prctl.2: Update description for PR_SET_MM option

New feature PR_SET_MM_EXE_FILE added, also
error codes updated.

Signed-off-by: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
---
 man2/prctl.2 |   70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 69 insertions(+), 1 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 7a50ac1..de15426 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -481,6 +481,30 @@ argument should provide the address of the vector.
 The
 .I arg4
 is the size of the vector.
+
+.BR PR_SET_MM_EXE_FILE
+to supersede
+.IR /proc/pid/exe
+symbolic link with a new one pointing to a new executable file
+which descriptor is provided provided in the
+.I arg3
+argument.
+The file descriptor should be obtaned with a regular
+.BR open (2)
+call.
+
+To change the symlink, one needs to unmap all existing
+executable memory areas being created by the kernel itself
+(for example the kernel usually creates at least one executable
+memory area for Elf file
+.IR \.text
+section).
+
+The second limitation is that such transition can be done once
+in a process life time.
+Any furter attempts will be rejected.
+This should help system administrators to monitor the unusual
+symlinks transitions over all process running in a system.
 .\"
 .SH "RETURN VALUE"
 On success,
@@ -515,7 +539,9 @@ is not recognized.
 is
 .BR PR_MCE_KILL
 or
-.BR PR_MCE_KILL_GET ,
+.BR PR_MCE_KILL_GET
+or
+.BR PR_SET_MM ,
 and unused
 .BR prctl ()
 arguments were not specified as zero.
@@ -563,6 +589,48 @@ is
 and the caller does not have the
 .B CAP_SETPCAP
 capability.
+.TP
+.B EPERM
+.I option
+is
+.BR PR_SET_MM ,
+and the caller does not have the
+.B CAP_SYS_RESOURCE
+capability.
+.TP
+.B EACCES
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the file is not executable one.
+.TP
+.B EBUSY
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the second attempt to change
+.I /proc/pid/exe
+symlink is prohibited.
+.TP
+.B EBADF
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the file descriptor passed in
+.I arg4
+is not found.
 .\" The following can't actually happen, because prctl() in
 .\" seccomp mode will cause SIGKILL.
 .\" .TP
-- 
1.7.7.6

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

On Wed, Mar 21, 2012 at 11:24 AM, Cyrill Gorcunov <gorcunov@openvz.org> wrote:
> On Wed, Mar 21, 2012 at 06:21:19AM +1300, Michael Kerrisk (man-pages) wrote:
>> Hello Cyrill,
>>
>> The PR_SET_MM operation adds a number of new error cases to prctl(2).
>> Could you extend you patch to add these under ERRORS?
>>
>
> Hi Michael,
>
> here is an update on previous patch. Please take a look and
> tell me what you think when you get time. Complains are welcome!

Hi Cyrill,

I only just had a chance to look at this now and realize that this is
a patch on a patch. Could you just send me a complete  patch with all
the changes?

Thanks,

Michael

> ---
> From 10dbf8dc2e40426c56a6d2a2414bcb9d3a0f5ff3 Mon Sep 17 00:00:00 2001
> From: Cyrill Gorcunov <gorcunov@openvz.org>
> Date: Wed, 21 Mar 2012 02:20:11 +0400
> Subject: [PATCH] prctl.2: Update description for PR_SET_MM option
>
> New feature PR_SET_MM_EXE_FILE added, also
> error codes updated.
>
> Signed-off-by: Cyrill Gorcunov <gorcunov@openvz.org>
> ---
>  man2/prctl.2 |   70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  1 files changed, 69 insertions(+), 1 deletions(-)
>
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 7a50ac1..de15426 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -481,6 +481,30 @@ argument should provide the address of the vector.
>  The
>  .I arg4
>  is the size of the vector.
> +
> +.BR PR_SET_MM_EXE_FILE
> +to supersede
> +.IR /proc/pid/exe
> +symbolic link with a new one pointing to a new executable file
> +which descriptor is provided provided in the
> +.I arg3
> +argument.
> +The file descriptor should be obtaned with a regular
> +.BR open (2)
> +call.
> +
> +To change the symlink, one needs to unmap all existing
> +executable memory areas being created by the kernel itself
> +(for example the kernel usually creates at least one executable
> +memory area for Elf file
> +.IR \.text
> +section).
> +
> +The second limitation is that such transition can be done once
> +in a process life time.
> +Any furter attempts will be rejected.
> +This should help system administrators to monitor the unusual
> +symlinks transitions over all process running in a system.
>  .\"
>  .SH "RETURN VALUE"
>  On success,
> @@ -515,7 +539,9 @@ is not recognized.
>  is
>  .BR PR_MCE_KILL
>  or
> -.BR PR_MCE_KILL_GET ,
> +.BR PR_MCE_KILL_GET
> +or
> +.BR PR_SET_MM ,
>  and unused
>  .BR prctl ()
>  arguments were not specified as zero.
> @@ -563,6 +589,48 @@ is
>  and the caller does not have the
>  .B CAP_SETPCAP
>  capability.
> +.TP
> +.B EPERM
> +.I option
> +is
> +.BR PR_SET_MM ,
> +and the caller does not have the
> +.B CAP_SYS_RESOURCE
> +capability.
> +.TP
> +.B EACCES
> +.I option
> +is
> +.BR PR_SET_MM ,
> +and the
> +.I arg3
> +is
> +.BR PR_SET_MM_EXE_FILE ,
> +the file is not executable one.
> +.TP
> +.B EBUSY
> +.I option
> +is
> +.BR PR_SET_MM ,
> +and the
> +.I arg3
> +is
> +.BR PR_SET_MM_EXE_FILE ,
> +the second attempt to change
> +.I /proc/pid/exe
> +symlink is prohibited.
> +.TP
> +.B EBADF
> +.I option
> +is
> +.BR PR_SET_MM ,
> +and the
> +.I arg3
> +is
> +.BR PR_SET_MM_EXE_FILE ,
> +the file descriptor passed in
> +.I arg4
> +is not found.
>  .\" The following can't actually happen, because prctl() in
>  .\" seccomp mode will cause SIGKILL.
>  .\" .TP
> --
> 1.7.7.6
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Sat, Mar 24, 2012 at 03:59:49PM +1300, Michael Kerrisk (man-pages) wrote:
> 
> Hi Cyrill,
> 
> I only just had a chance to look at this now and realize that this is
> a patch on a patch. Could you just send me a complete  patch with all
> the changes?
> 

Sure, here is it

	Cyrill
---
From: Cyrill Gorcunov <gorcunov@openvz.org>
Date: Sat, 24 Mar 2012 10:15:28 +0400
Subject: [PATCH 2/2] prctl.2: Add PR_SET_MM option description

CC: Pavel Emelyanov <xemul@parallels.com>
Signed-off-by: Cyrill Gorcunov <gorcunov@openvz.org>
---
 man2/prctl.2 |  174 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 173 insertions(+), 1 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index effad2a..de15426 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -378,6 +378,134 @@ Return the current per-process machine check kill policy.
 All unused
 .BR prctl ()
 arguments must be zero.
+.TP
+.BR PR_SET_MM " (since Linux 3.3)"
+Allows a user to modify certain kernel memory map descriptor fields
+of the calling process.
+Usually these fields are set by the kernel and dynamic loader (see
+.BR ld.so (8)
+for more information) and a regular application should not use this feature.
+Still there are cases such as self-modifying programs, where a program might
+find it useful to change its own memory map.
+The kernel must be built with
+.BR CONFIG_CHECKPOINT_RESTORE
+option turned on, otherwise this feature will not be accessible
+from a user space level.
+The calling process must have
+.BR CAP_SYS_RESOURCE
+(see
+.BR capabilities (7)
+for details) capability granted.
+The value in
+.I arg2
+is one of the options below, while
+.I arg3
+provides a new value for this option.
+
+.BR PR_SET_MM_START_CODE
+to set the address above which program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or shareable (see
+.BR mprotect (2)
+and
+.BR mmap (2)
+for more information).
+
+.BR PR_SET_MM_END_CODE
+to set the address below which program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or shareable.
+
+.BR PR_SET_MM_START_DATA
+to set the address above which program data+bss is placed.
+The corresponding memory area must be readable and writable,
+but not executable or shareable.
+
+.B PR_SET_MM_END_DATA
+to set the address below which program data+bss is placed.
+The corresponding memory area must be readable and writable,
+but not executable or shareable.
+
+.BR PR_SET_MM_START_STACK
+to set the start address of the stack.
+The corresponding memory area must be readable and writable.
+
+.BR PR_SET_MM_START_BRK
+to set the address above which program heap can be expanded with
+.BR brk (2)
+call.
+The address must not be greater than ending address of
+the current program data segment, neither it may exceed
+resource limit for data (see
+.BR setrlimit (2)
+for more information).
+
+.BR PR_SET_MM_BRK
+to set the current
+.BR brk (2)
+value.
+The requirements for address are the same as for
+.BR PR_SET_MM_START_BRK
+option.
+
+.BR PR_SET_MM_ARG_START
+to set the address above which program command line is placed.
+
+.BR PR_SET_MM_ARG_END
+to set the address below which program command line is placed.
+
+.BR PR_SET_MM_ENV_START
+to set the address above which program environment is placed.
+
+.BR PR_SET_MM_ENV_END
+to set the address below which program environment is placed.
+
+The address passed with
+.BR PR_SET_MM_ARG_START ,
+.BR PR_SET_MM_ARG_END ,
+.BR PR_SET_MM_ENV_START ,
+.BR PR_SET_MM_ENV_END ,
+should belong to a process stack area, thus corresponding memory area
+must be readable, writable and (depending on the kernel
+configuration) has
+.BR MAP_GROWSDOWN
+attribute set (see
+.BR mmap (2)
+for details).
+
+.BR PR_SET_MM_AUXV
+to set a new auxiliary vector.
+The
+.I arg3
+argument should provide the address of the vector.
+The
+.I arg4
+is the size of the vector.
+
+.BR PR_SET_MM_EXE_FILE
+to supersede
+.IR /proc/pid/exe
+symbolic link with a new one pointing to a new executable file
+which descriptor is provided provided in the
+.I arg3
+argument.
+The file descriptor should be obtaned with a regular
+.BR open (2)
+call.
+
+To change the symlink, one needs to unmap all existing
+executable memory areas being created by the kernel itself
+(for example the kernel usually creates at least one executable
+memory area for Elf file
+.IR \.text
+section).
+
+The second limitation is that such transition can be done once
+in a process life time.
+Any furter attempts will be rejected.
+This should help system administrators to monitor the unusual
+symlinks transitions over all process running in a system.
+.\"
 .SH "RETURN VALUE"
 On success,
 .BR PR_GET_DUMPABLE ,
@@ -411,7 +539,9 @@ is not recognized.
 is
 .BR PR_MCE_KILL
 or
-.BR PR_MCE_KILL_GET ,
+.BR PR_MCE_KILL_GET
+or
+.BR PR_SET_MM ,
 and unused
 .BR prctl ()
 arguments were not specified as zero.
@@ -459,6 +589,48 @@ is
 and the caller does not have the
 .B CAP_SETPCAP
 capability.
+.TP
+.B EPERM
+.I option
+is
+.BR PR_SET_MM ,
+and the caller does not have the
+.B CAP_SYS_RESOURCE
+capability.
+.TP
+.B EACCES
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the file is not executable one.
+.TP
+.B EBUSY
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the second attempt to change
+.I /proc/pid/exe
+symlink is prohibited.
+.TP
+.B EBADF
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the file descriptor passed in
+.I arg4
+is not found.
 .\" The following can't actually happen, because prctl() in
 .\" seccomp mode will cause SIGKILL.
 .\" .TP
-- 
1.7.7.6

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Sat, Mar 24, 2012 at 03:59:49PM +1300, Michael Kerrisk (man-pages) wrote:
> 
> Hi Cyrill,
> 
> I only just had a chance to look at this now and realize that this is
> a patch on a patch. Could you just send me a complete  patch with all
> the changes?
> 

Sure, here is it

	Cyrill
---
From: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
Date: Sat, 24 Mar 2012 10:15:28 +0400
Subject: [PATCH 2/2] prctl.2: Add PR_SET_MM option description

CC: Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org>
Signed-off-by: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
---
 man2/prctl.2 |  174 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 173 insertions(+), 1 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index effad2a..de15426 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -378,6 +378,134 @@ Return the current per-process machine check kill policy.
 All unused
 .BR prctl ()
 arguments must be zero.
+.TP
+.BR PR_SET_MM " (since Linux 3.3)"
+Allows a user to modify certain kernel memory map descriptor fields
+of the calling process.
+Usually these fields are set by the kernel and dynamic loader (see
+.BR ld.so (8)
+for more information) and a regular application should not use this feature.
+Still there are cases such as self-modifying programs, where a program might
+find it useful to change its own memory map.
+The kernel must be built with
+.BR CONFIG_CHECKPOINT_RESTORE
+option turned on, otherwise this feature will not be accessible
+from a user space level.
+The calling process must have
+.BR CAP_SYS_RESOURCE
+(see
+.BR capabilities (7)
+for details) capability granted.
+The value in
+.I arg2
+is one of the options below, while
+.I arg3
+provides a new value for this option.
+
+.BR PR_SET_MM_START_CODE
+to set the address above which program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or shareable (see
+.BR mprotect (2)
+and
+.BR mmap (2)
+for more information).
+
+.BR PR_SET_MM_END_CODE
+to set the address below which program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or shareable.
+
+.BR PR_SET_MM_START_DATA
+to set the address above which program data+bss is placed.
+The corresponding memory area must be readable and writable,
+but not executable or shareable.
+
+.B PR_SET_MM_END_DATA
+to set the address below which program data+bss is placed.
+The corresponding memory area must be readable and writable,
+but not executable or shareable.
+
+.BR PR_SET_MM_START_STACK
+to set the start address of the stack.
+The corresponding memory area must be readable and writable.
+
+.BR PR_SET_MM_START_BRK
+to set the address above which program heap can be expanded with
+.BR brk (2)
+call.
+The address must not be greater than ending address of
+the current program data segment, neither it may exceed
+resource limit for data (see
+.BR setrlimit (2)
+for more information).
+
+.BR PR_SET_MM_BRK
+to set the current
+.BR brk (2)
+value.
+The requirements for address are the same as for
+.BR PR_SET_MM_START_BRK
+option.
+
+.BR PR_SET_MM_ARG_START
+to set the address above which program command line is placed.
+
+.BR PR_SET_MM_ARG_END
+to set the address below which program command line is placed.
+
+.BR PR_SET_MM_ENV_START
+to set the address above which program environment is placed.
+
+.BR PR_SET_MM_ENV_END
+to set the address below which program environment is placed.
+
+The address passed with
+.BR PR_SET_MM_ARG_START ,
+.BR PR_SET_MM_ARG_END ,
+.BR PR_SET_MM_ENV_START ,
+.BR PR_SET_MM_ENV_END ,
+should belong to a process stack area, thus corresponding memory area
+must be readable, writable and (depending on the kernel
+configuration) has
+.BR MAP_GROWSDOWN
+attribute set (see
+.BR mmap (2)
+for details).
+
+.BR PR_SET_MM_AUXV
+to set a new auxiliary vector.
+The
+.I arg3
+argument should provide the address of the vector.
+The
+.I arg4
+is the size of the vector.
+
+.BR PR_SET_MM_EXE_FILE
+to supersede
+.IR /proc/pid/exe
+symbolic link with a new one pointing to a new executable file
+which descriptor is provided provided in the
+.I arg3
+argument.
+The file descriptor should be obtaned with a regular
+.BR open (2)
+call.
+
+To change the symlink, one needs to unmap all existing
+executable memory areas being created by the kernel itself
+(for example the kernel usually creates at least one executable
+memory area for Elf file
+.IR \.text
+section).
+
+The second limitation is that such transition can be done once
+in a process life time.
+Any furter attempts will be rejected.
+This should help system administrators to monitor the unusual
+symlinks transitions over all process running in a system.
+.\"
 .SH "RETURN VALUE"
 On success,
 .BR PR_GET_DUMPABLE ,
@@ -411,7 +539,9 @@ is not recognized.
 is
 .BR PR_MCE_KILL
 or
-.BR PR_MCE_KILL_GET ,
+.BR PR_MCE_KILL_GET
+or
+.BR PR_SET_MM ,
 and unused
 .BR prctl ()
 arguments were not specified as zero.
@@ -459,6 +589,48 @@ is
 and the caller does not have the
 .B CAP_SETPCAP
 capability.
+.TP
+.B EPERM
+.I option
+is
+.BR PR_SET_MM ,
+and the caller does not have the
+.B CAP_SYS_RESOURCE
+capability.
+.TP
+.B EACCES
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the file is not executable one.
+.TP
+.B EBUSY
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the second attempt to change
+.I /proc/pid/exe
+symlink is prohibited.
+.TP
+.B EBADF
+.I option
+is
+.BR PR_SET_MM ,
+and the
+.I arg3
+is
+.BR PR_SET_MM_EXE_FILE ,
+the file descriptor passed in
+.I arg4
+is not found.
 .\" The following can't actually happen, because prctl() in
 .\" seccomp mode will cause SIGKILL.
 .\" .TP
-- 
1.7.7.6

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

Hi Cyrill,

I've had a look at your PR_SET_MM patch for the prctl.2 man page. I've
made various edits and added various FIXMEs relating to questions I
have.

At this stage, please do *not* send me a new patch, Just add your
responses to the FIXMES inline in a reply mail, and I'll further tune
my patch before sending it to you for further review.

Cheers,

Michael

diff --git a/man2/prctl.2 b/man2/prctl.2
index effad2a..d3294e2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -43,7 +43,7 @@
 .\" FIXME: Document PR_TASK_PERF_EVENTS_DISABLE and
 .\"        PR_TASK_PERF_EVENTS_ENABLE (new in 2.6.32)
 .\"
-.TH PRCTL 2 2011-09-17 "Linux" "Linux Programmer's Manual"
+.TH PRCTL 2 2012-04-14 "Linux" "Linux Programmer's Manual"
 .SH NAME
 prctl \- operations on a process
 .SH SYNOPSIS
@@ -378,6 +378,144 @@ Return the current per-process machine check kill policy.
 All unused
 .BR prctl ()
 arguments must be zero.
+.TP
+.BR PR_SET_MM " (since Linux 3.3)"
+Modify certain kernel memory map descriptor fields
+of the calling process.
+Usually these fields are set by the kernel and dynamic loader (see
+.BR ld.so (8)
+for more information) and a regular application should not use this feature.
+However, there are cases, such as self-modifying programs,
+where a program might find it useful to change its own memory map.
+This feature is available only if the kernel is built with the
+.BR CONFIG_CHECKPOINT_RESTORE
+option enabled.
+The calling process must have the
+.BR CAP_SYS_RESOURCE
+capability.
+The value in
+.I arg2
+is one of the options below, while
+.I arg3
+provides a new value for the option.
+.RS
+.TP
+.BR PR_SET_MM_START_CODE
+Set the address above which the program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or sharable (see
+.BR mprotect (2)
+and
+.BR mmap (2)
+for more information).
+.TP
+.BR PR_SET_MM_END_CODE
+Set the address below which the program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or sharable.
+.TP
+.BR PR_SET_MM_START_DATA
+Set the address above which initialized and
+uninitialized (bss) data are placed.
+The corresponding memory area must be readable and writable,
+but not executable or sharable.
+.TP
+.B PR_SET_MM_END_DATA
+Set the address below which initialized and
+uninitialized (bss) data are placed.
+The corresponding memory area must be readable and writable,
+but not executable or sharable.
+.TP
+.BR PR_SET_MM_START_STACK
+Set the start address of the stack.
+The corresponding memory area must be readable and writable.
+.TP
+.BR PR_SET_MM_START_BRK
+Set the address above which the program heap can be expanded with
+.BR brk (2)
+call.
+.\" FIXME In the next sentence, shouldn't "not be greater" be "be greater"?
+The address must not be greater than the ending address of
+the current program data segment.
+.\" FIXME I completely rewrote the following sentence. Is it okay?
+.\" FIXME Is the following error documented in ERRORS?
+In addition, the combined size of the resulting heap and
+the size of the data segment can't exceed the
+.BR RLIMIT_DATA
+resource limit (see
+.BR setrlimit (2)).
+.TP
+.BR PR_SET_MM_BRK
+Set the current
+.BR brk (2)
+value.
+The requirements for the address are the same as for the
+.BR PR_SET_MM_START_BRK
+option.
+.\" FIXME Delete or comment out the following? (until ========)
+.\" None of the following constants exist in current kernel source
+.\" What is the state of the kernel patches for these?
+.TP
+.BR PR_SET_MM_ARG_START
+Set the address above which the program command line is placed.
+.TP
+.BR PR_SET_MM_ARG_END
+Set the address below which the program command line is placed.
+.TP
+.BR PR_SET_MM_ENV_START
+Set the address above which the program environment is placed.
+.TP
+.BR PR_SET_MM_ENV_END
+Set the address below which the program environment is placed.
+.IP
+The address passed with
+.BR PR_SET_MM_ARG_START ,
+.BR PR_SET_MM_ARG_END ,
+.BR PR_SET_MM_ENV_START ,
+and
+.BR PR_SET_MM_ENV_END
+should belong to a process stack area.
+Thus, the corresponding memory area must be readable, writable, and
+(depending on the kernel configuration) have the
+.BR MAP_GROWSDOWN
+attribute set (see
+.BR mmap (2)).
+.TP
+.BR PR_SET_MM_AUXV
+Set a new auxiliary vector.
+The
+.I arg3
+argument should provide the address of the vector.
+The
+.I arg4
+is the size of the vector.
+.TP
+.BR PR_SET_MM_EXE_FILE
+Supersede the
+.IR /proc/pid/exe
+symbolic link with a new one pointing to a new executable file
+identified by the file descriptor provided in
+.I arg3
+argument.
+The file descriptor should be obtained with a regular
+.BR open (2)
+call.
+.IP
+To change the symbolic link, one needs to unmap all existing
+executable memory areas, including those created by the kernel itself
+(for example the kernel usually creates at least one executable
+memory area for the ELF
+.IR \.text
+section).
+.IP
+The second limitation is that such transitions can be done only once
+in a process life time.
+Any further attempts will be rejected.
+This should help system administrators to monitor the unusual
+symbolic-link transitions over all process running in a system.
+.\" ========== END FIXME
+.RE
+.\"
 .SH "RETURN VALUE"
 On success,
 .BR PR_GET_DUMPABLE ,
@@ -411,7 +549,9 @@ is not recognized.
 is
 .BR PR_MCE_KILL
 or
-.BR PR_MCE_KILL_GET ,
+.BR PR_MCE_KILL_GET
+or
+.BR PR_SET_MM ,
 and unused
 .BR prctl ()
 arguments were not specified as zero.
@@ -429,6 +569,48 @@ or
 .BR PR_SET_SECCOMP ,
 and the kernel was not configured with
 .BR CONFIG_SECCOMP .
+.\" FIXME I added the following lengthy EINVAL entry. Is it correct?
+.TP
+.B EINVAL
+.I option
+is
+.BR PR_SET_MM ,
+and one of the following is true
+.RS
+.IP * 3
+.I arg4
+or
+.I arg5
+is nonzero;
+.IP *
+.I arg3
+is greater than
+.B TASK_SIZE
+(the limit on the size of the user address space for this architecture);
+.IP *
+.I arg2
+is
+.BR PR_SET_MM_START_CODE ,
+.BR PR_SET_MM_END_CODE ,
+.BR PR_SET_MM_START_DATA ,
+.BR PR_SET_MM_END_DATA ,
+or
+.BR PR_SET_MM_START_STACK,
+and the permissions of the corresponding memory area are not as required;
+.IP *
+.I arg2
+is
+.BR PR_SET_MM_START_BRK
+or
+.BR PR_SET_MM_BRK ,
+and
+.I arg3
+.\" FIXME Is the following correct (see earlier comment)
+is less than or equal to the end of the data segment
+or specifies a value that would cause the
+.B RLIMIT_DATA
+resource limit to be exceeded.
+.RE
 .TP
 .B EPERM
 .I option
@@ -459,6 +641,49 @@ is
 and the caller does not have the
 .B CAP_SETPCAP
 capability.
+.TP
+.B EPERM
+.I option
+is
+.BR PR_SET_MM ,
+and the caller does not have the
+.B CAP_SYS_RESOURCE
+capability.
+.TP
+.B EACCES
+.I option
+is
+.BR PR_SET_MM ,
+and
+.I arg3
+is
+.\" FIXME PR_SET_MM_EXE_FILE is not in the kernel sources
+.BR PR_SET_MM_EXE_FILE ,
+the file is not executable.
+.TP
+.B EBUSY
+.I option
+is
+.BR PR_SET_MM ,
+.I arg3
+is
+.\" FIXME PR_SET_MM_EXE_FILE is not in the kernel sources
+.BR PR_SET_MM_EXE_FILE ,
+and this the second attempt to change the
+.I /proc/pid/exe
+symbolic link, which is prohibited.
+.TP
+.B EBADF
+.I option
+is
+.BR PR_SET_MM ,
+.I arg3
+is
+.\" FIXME PR_SET_MM_EXE_FILE is not in the kernel sources
+.BR PR_SET_MM_EXE_FILE ,
+and the file descriptor passed in
+.I arg4
+is not valid.
 .\" The following can't actually happen, because prctl() in
 .\" seccomp mode will cause SIGKILL.
 .\" .TP


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

Hi Cyrill,

I've had a look at your PR_SET_MM patch for the prctl.2 man page. I've
made various edits and added various FIXMEs relating to questions I
have.

At this stage, please do *not* send me a new patch, Just add your
responses to the FIXMES inline in a reply mail, and I'll further tune
my patch before sending it to you for further review.

Cheers,

Michael

diff --git a/man2/prctl.2 b/man2/prctl.2
index effad2a..d3294e2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -43,7 +43,7 @@
 .\" FIXME: Document PR_TASK_PERF_EVENTS_DISABLE and
 .\"        PR_TASK_PERF_EVENTS_ENABLE (new in 2.6.32)
 .\"
-.TH PRCTL 2 2011-09-17 "Linux" "Linux Programmer's Manual"
+.TH PRCTL 2 2012-04-14 "Linux" "Linux Programmer's Manual"
 .SH NAME
 prctl \- operations on a process
 .SH SYNOPSIS
@@ -378,6 +378,144 @@ Return the current per-process machine check kill policy.
 All unused
 .BR prctl ()
 arguments must be zero.
+.TP
+.BR PR_SET_MM " (since Linux 3.3)"
+Modify certain kernel memory map descriptor fields
+of the calling process.
+Usually these fields are set by the kernel and dynamic loader (see
+.BR ld.so (8)
+for more information) and a regular application should not use this feature.
+However, there are cases, such as self-modifying programs,
+where a program might find it useful to change its own memory map.
+This feature is available only if the kernel is built with the
+.BR CONFIG_CHECKPOINT_RESTORE
+option enabled.
+The calling process must have the
+.BR CAP_SYS_RESOURCE
+capability.
+The value in
+.I arg2
+is one of the options below, while
+.I arg3
+provides a new value for the option.
+.RS
+.TP
+.BR PR_SET_MM_START_CODE
+Set the address above which the program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or sharable (see
+.BR mprotect (2)
+and
+.BR mmap (2)
+for more information).
+.TP
+.BR PR_SET_MM_END_CODE
+Set the address below which the program text can run.
+The corresponding memory area must be readable and executable,
+but not writable or sharable.
+.TP
+.BR PR_SET_MM_START_DATA
+Set the address above which initialized and
+uninitialized (bss) data are placed.
+The corresponding memory area must be readable and writable,
+but not executable or sharable.
+.TP
+.B PR_SET_MM_END_DATA
+Set the address below which initialized and
+uninitialized (bss) data are placed.
+The corresponding memory area must be readable and writable,
+but not executable or sharable.
+.TP
+.BR PR_SET_MM_START_STACK
+Set the start address of the stack.
+The corresponding memory area must be readable and writable.
+.TP
+.BR PR_SET_MM_START_BRK
+Set the address above which the program heap can be expanded with
+.BR brk (2)
+call.
+.\" FIXME In the next sentence, shouldn't "not be greater" be "be greater"?
+The address must not be greater than the ending address of
+the current program data segment.
+.\" FIXME I completely rewrote the following sentence. Is it okay?
+.\" FIXME Is the following error documented in ERRORS?
+In addition, the combined size of the resulting heap and
+the size of the data segment can't exceed the
+.BR RLIMIT_DATA
+resource limit (see
+.BR setrlimit (2)).
+.TP
+.BR PR_SET_MM_BRK
+Set the current
+.BR brk (2)
+value.
+The requirements for the address are the same as for the
+.BR PR_SET_MM_START_BRK
+option.
+.\" FIXME Delete or comment out the following? (until ========)
+.\" None of the following constants exist in current kernel source
+.\" What is the state of the kernel patches for these?
+.TP
+.BR PR_SET_MM_ARG_START
+Set the address above which the program command line is placed.
+.TP
+.BR PR_SET_MM_ARG_END
+Set the address below which the program command line is placed.
+.TP
+.BR PR_SET_MM_ENV_START
+Set the address above which the program environment is placed.
+.TP
+.BR PR_SET_MM_ENV_END
+Set the address below which the program environment is placed.
+.IP
+The address passed with
+.BR PR_SET_MM_ARG_START ,
+.BR PR_SET_MM_ARG_END ,
+.BR PR_SET_MM_ENV_START ,
+and
+.BR PR_SET_MM_ENV_END
+should belong to a process stack area.
+Thus, the corresponding memory area must be readable, writable, and
+(depending on the kernel configuration) have the
+.BR MAP_GROWSDOWN
+attribute set (see
+.BR mmap (2)).
+.TP
+.BR PR_SET_MM_AUXV
+Set a new auxiliary vector.
+The
+.I arg3
+argument should provide the address of the vector.
+The
+.I arg4
+is the size of the vector.
+.TP
+.BR PR_SET_MM_EXE_FILE
+Supersede the
+.IR /proc/pid/exe
+symbolic link with a new one pointing to a new executable file
+identified by the file descriptor provided in
+.I arg3
+argument.
+The file descriptor should be obtained with a regular
+.BR open (2)
+call.
+.IP
+To change the symbolic link, one needs to unmap all existing
+executable memory areas, including those created by the kernel itself
+(for example the kernel usually creates at least one executable
+memory area for the ELF
+.IR \.text
+section).
+.IP
+The second limitation is that such transitions can be done only once
+in a process life time.
+Any further attempts will be rejected.
+This should help system administrators to monitor the unusual
+symbolic-link transitions over all process running in a system.
+.\" ========== END FIXME
+.RE
+.\"
 .SH "RETURN VALUE"
 On success,
 .BR PR_GET_DUMPABLE ,
@@ -411,7 +549,9 @@ is not recognized.
 is
 .BR PR_MCE_KILL
 or
-.BR PR_MCE_KILL_GET ,
+.BR PR_MCE_KILL_GET
+or
+.BR PR_SET_MM ,
 and unused
 .BR prctl ()
 arguments were not specified as zero.
@@ -429,6 +569,48 @@ or
 .BR PR_SET_SECCOMP ,
 and the kernel was not configured with
 .BR CONFIG_SECCOMP .
+.\" FIXME I added the following lengthy EINVAL entry. Is it correct?
+.TP
+.B EINVAL
+.I option
+is
+.BR PR_SET_MM ,
+and one of the following is true
+.RS
+.IP * 3
+.I arg4
+or
+.I arg5
+is nonzero;
+.IP *
+.I arg3
+is greater than
+.B TASK_SIZE
+(the limit on the size of the user address space for this architecture);
+.IP *
+.I arg2
+is
+.BR PR_SET_MM_START_CODE ,
+.BR PR_SET_MM_END_CODE ,
+.BR PR_SET_MM_START_DATA ,
+.BR PR_SET_MM_END_DATA ,
+or
+.BR PR_SET_MM_START_STACK,
+and the permissions of the corresponding memory area are not as required;
+.IP *
+.I arg2
+is
+.BR PR_SET_MM_START_BRK
+or
+.BR PR_SET_MM_BRK ,
+and
+.I arg3
+.\" FIXME Is the following correct (see earlier comment)
+is less than or equal to the end of the data segment
+or specifies a value that would cause the
+.B RLIMIT_DATA
+resource limit to be exceeded.
+.RE
 .TP
 .B EPERM
 .I option
@@ -459,6 +641,49 @@ is
 and the caller does not have the
 .B CAP_SETPCAP
 capability.
+.TP
+.B EPERM
+.I option
+is
+.BR PR_SET_MM ,
+and the caller does not have the
+.B CAP_SYS_RESOURCE
+capability.
+.TP
+.B EACCES
+.I option
+is
+.BR PR_SET_MM ,
+and
+.I arg3
+is
+.\" FIXME PR_SET_MM_EXE_FILE is not in the kernel sources
+.BR PR_SET_MM_EXE_FILE ,
+the file is not executable.
+.TP
+.B EBUSY
+.I option
+is
+.BR PR_SET_MM ,
+.I arg3
+is
+.\" FIXME PR_SET_MM_EXE_FILE is not in the kernel sources
+.BR PR_SET_MM_EXE_FILE ,
+and this the second attempt to change the
+.I /proc/pid/exe
+symbolic link, which is prohibited.
+.TP
+.B EBADF
+.I option
+is
+.BR PR_SET_MM ,
+.I arg3
+is
+.\" FIXME PR_SET_MM_EXE_FILE is not in the kernel sources
+.BR PR_SET_MM_EXE_FILE ,
+and the file descriptor passed in
+.I arg4
+is not valid.
 .\" The following can't actually happen, because prctl() in
 .\" seccomp mode will cause SIGKILL.
 .\" .TP


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Sun, Apr 15, 2012 at 04:10:24PM +1200, Michael Kerrisk (man-pages) wrote:
> Hi Cyrill,
> 

Hi Michael,

> I've had a look at your PR_SET_MM patch for the prctl.2 man page. I've
> made various edits and added various FIXMEs relating to questions I
> have.
> 
> At this stage, please do *not* send me a new patch, Just add your
> responses to the FIXMES inline in a reply mail, and I'll further tune
> my patch before sending it to you for further review.
> 

OK (don't hesitate to poke me, if anything needed)
...
> +.TP
> +.BR PR_SET_MM_START_STACK
> +Set the start address of the stack.
> +The corresponding memory area must be readable and writable.
> +.TP
> +.BR PR_SET_MM_START_BRK
> +Set the address above which the program heap can be expanded with
> +.BR brk (2)
> +call.
> +.\" FIXME In the next sentence, shouldn't "not be greater" be "be greater"?
> +The address must not be greater than the ending address of
> +the current program data segment.

Yes, thanks!

> +.\" FIXME I completely rewrote the following sentence. Is it okay?

Looks great to me.

> +.\" FIXME Is the following error documented in ERRORS?
> +In addition, the combined size of the resulting heap and
> +the size of the data segment can't exceed the
> +.BR RLIMIT_DATA
> +resource limit (see
> +.BR setrlimit (2)).
> +.TP
> +.BR PR_SET_MM_BRK
> +Set the current
> +.BR brk (2)
> +value.
> +The requirements for the address are the same as for the
> +.BR PR_SET_MM_START_BRK
> +option.
> +.\" FIXME Delete or comment out the following? (until ========)
> +.\" None of the following constants exist in current kernel source
> +.\" What is the state of the kernel patches for these?

This should be in -mm tree, I think it could be commented out
until it hit mainline.

> +.TP
> +.BR PR_SET_MM_ARG_START
...
> +.RE
> +.\"
>  .SH "RETURN VALUE"
>  On success,
>  .BR PR_GET_DUMPABLE ,
> @@ -411,7 +549,9 @@ is not recognized.
>  is
>  .BR PR_MCE_KILL
>  or
> -.BR PR_MCE_KILL_GET ,
> +.BR PR_MCE_KILL_GET
> +or
> +.BR PR_SET_MM ,
>  and unused
>  .BR prctl ()
>  arguments were not specified as zero.
> @@ -429,6 +569,48 @@ or
>  .BR PR_SET_SECCOMP ,
>  and the kernel was not configured with
>  .BR CONFIG_SECCOMP .
> +.\" FIXME I added the following lengthy EINVAL entry. Is it correct?

Yes, looks good to me. Thanks! Btw, Michael, could you please send
me this page in plain text format please (may be provately to not
flood the list_? I'll re-check it.

	Cyrill

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Sun, Apr 15, 2012 at 04:10:24PM +1200, Michael Kerrisk (man-pages) wrote:
> Hi Cyrill,
> 

Hi Michael,

> I've had a look at your PR_SET_MM patch for the prctl.2 man page. I've
> made various edits and added various FIXMEs relating to questions I
> have.
> 
> At this stage, please do *not* send me a new patch, Just add your
> responses to the FIXMES inline in a reply mail, and I'll further tune
> my patch before sending it to you for further review.
> 

OK (don't hesitate to poke me, if anything needed)
...
> +.TP
> +.BR PR_SET_MM_START_STACK
> +Set the start address of the stack.
> +The corresponding memory area must be readable and writable.
> +.TP
> +.BR PR_SET_MM_START_BRK
> +Set the address above which the program heap can be expanded with
> +.BR brk (2)
> +call.
> +.\" FIXME In the next sentence, shouldn't "not be greater" be "be greater"?
> +The address must not be greater than the ending address of
> +the current program data segment.

Yes, thanks!

> +.\" FIXME I completely rewrote the following sentence. Is it okay?

Looks great to me.

> +.\" FIXME Is the following error documented in ERRORS?
> +In addition, the combined size of the resulting heap and
> +the size of the data segment can't exceed the
> +.BR RLIMIT_DATA
> +resource limit (see
> +.BR setrlimit (2)).
> +.TP
> +.BR PR_SET_MM_BRK
> +Set the current
> +.BR brk (2)
> +value.
> +The requirements for the address are the same as for the
> +.BR PR_SET_MM_START_BRK
> +option.
> +.\" FIXME Delete or comment out the following? (until ========)
> +.\" None of the following constants exist in current kernel source
> +.\" What is the state of the kernel patches for these?

This should be in -mm tree, I think it could be commented out
until it hit mainline.

> +.TP
> +.BR PR_SET_MM_ARG_START
...
> +.RE
> +.\"
>  .SH "RETURN VALUE"
>  On success,
>  .BR PR_GET_DUMPABLE ,
> @@ -411,7 +549,9 @@ is not recognized.
>  is
>  .BR PR_MCE_KILL
>  or
> -.BR PR_MCE_KILL_GET ,
> +.BR PR_MCE_KILL_GET
> +or
> +.BR PR_SET_MM ,
>  and unused
>  .BR prctl ()
>  arguments were not specified as zero.
> @@ -429,6 +569,48 @@ or
>  .BR PR_SET_SECCOMP ,
>  and the kernel was not configured with
>  .BR CONFIG_SECCOMP .
> +.\" FIXME I added the following lengthy EINVAL entry. Is it correct?

Yes, looks good to me. Thanks! Btw, Michael, could you please send
me this page in plain text format please (may be provately to not
flood the list_? I'll re-check it.

	Cyrill
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

On Mon, Apr 16, 2012 at 9:55 AM, Cyrill Gorcunov <gorcunov@openvz.org> wrote:
> On Sun, Apr 15, 2012 at 04:10:24PM +1200, Michael Kerrisk (man-pages) wrote:
>> Hi Cyrill,
>>
>
> Hi Michael,
>
>> I've had a look at your PR_SET_MM patch for the prctl.2 man page. I've
>> made various edits and added various FIXMEs relating to questions I
>> have.
>>
>> At this stage, please do *not* send me a new patch, Just add your
>> responses to the FIXMES inline in a reply mail, and I'll further tune
>> my patch before sending it to you for further review.
>>
>
> OK (don't hesitate to poke me, if anything needed)
> ...
>> +.TP
>> +.BR PR_SET_MM_START_STACK
>> +Set the start address of the stack.
>> +The corresponding memory area must be readable and writable.
>> +.TP
>> +.BR PR_SET_MM_START_BRK
>> +Set the address above which the program heap can be expanded with
>> +.BR brk (2)
>> +call.
>> +.\" FIXME In the next sentence, shouldn't "not be greater" be "be greater"?
>> +The address must not be greater than the ending address of
>> +the current program data segment.
>
> Yes, thanks!
>
>> +.\" FIXME I completely rewrote the following sentence. Is it okay?
>
> Looks great to me.
>
>> +.\" FIXME Is the following error documented in ERRORS?
>> +In addition, the combined size of the resulting heap and
>> +the size of the data segment can't exceed the
>> +.BR RLIMIT_DATA
>> +resource limit (see
>> +.BR setrlimit (2)).
>> +.TP
>> +.BR PR_SET_MM_BRK
>> +Set the current
>> +.BR brk (2)
>> +value.
>> +The requirements for the address are the same as for the
>> +.BR PR_SET_MM_START_BRK
>> +option.
>> +.\" FIXME Delete or comment out the following? (until ========)
>> +.\" None of the following constants exist in current kernel source
>> +.\" What is the state of the kernel patches for these?
>
> This should be in -mm tree, I think it could be commented out
> until it hit mainline.

Okay--commented out for now (as well as the corresponding ERRORS)

>> +.TP
>> +.BR PR_SET_MM_ARG_START
> ...
>> +.RE
>> +.\"
>>  .SH "RETURN VALUE"
>>  On success,
>>  .BR PR_GET_DUMPABLE ,
>> @@ -411,7 +549,9 @@ is not recognized.
>>  is
>>  .BR PR_MCE_KILL
>>  or
>> -.BR PR_MCE_KILL_GET ,
>> +.BR PR_MCE_KILL_GET
>> +or
>> +.BR PR_SET_MM ,
>>  and unused
>>  .BR prctl ()
>>  arguments were not specified as zero.
>> @@ -429,6 +569,48 @@ or
>>  .BR PR_SET_SECCOMP ,
>>  and the kernel was not configured with
>>  .BR CONFIG_SECCOMP .
>> +.\" FIXME I added the following lengthy EINVAL entry. Is it correct?
>
> Yes, looks good to me. Thanks! Btw, Michael, could you please send
> me this page in plain text format please (may be provately to not
> flood the list_? I'll re-check it.

I'll post a new version in a moment.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

On Mon, Apr 16, 2012 at 9:55 AM, Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org> wrote:
> On Sun, Apr 15, 2012 at 04:10:24PM +1200, Michael Kerrisk (man-pages) wrote:
>> Hi Cyrill,
>>
>
> Hi Michael,
>
>> I've had a look at your PR_SET_MM patch for the prctl.2 man page. I've
>> made various edits and added various FIXMEs relating to questions I
>> have.
>>
>> At this stage, please do *not* send me a new patch, Just add your
>> responses to the FIXMES inline in a reply mail, and I'll further tune
>> my patch before sending it to you for further review.
>>
>
> OK (don't hesitate to poke me, if anything needed)
> ...
>> +.TP
>> +.BR PR_SET_MM_START_STACK
>> +Set the start address of the stack.
>> +The corresponding memory area must be readable and writable.
>> +.TP
>> +.BR PR_SET_MM_START_BRK
>> +Set the address above which the program heap can be expanded with
>> +.BR brk (2)
>> +call.
>> +.\" FIXME In the next sentence, shouldn't "not be greater" be "be greater"?
>> +The address must not be greater than the ending address of
>> +the current program data segment.
>
> Yes, thanks!
>
>> +.\" FIXME I completely rewrote the following sentence. Is it okay?
>
> Looks great to me.
>
>> +.\" FIXME Is the following error documented in ERRORS?
>> +In addition, the combined size of the resulting heap and
>> +the size of the data segment can't exceed the
>> +.BR RLIMIT_DATA
>> +resource limit (see
>> +.BR setrlimit (2)).
>> +.TP
>> +.BR PR_SET_MM_BRK
>> +Set the current
>> +.BR brk (2)
>> +value.
>> +The requirements for the address are the same as for the
>> +.BR PR_SET_MM_START_BRK
>> +option.
>> +.\" FIXME Delete or comment out the following? (until ========)
>> +.\" None of the following constants exist in current kernel source
>> +.\" What is the state of the kernel patches for these?
>
> This should be in -mm tree, I think it could be commented out
> until it hit mainline.

Okay--commented out for now (as well as the corresponding ERRORS)

>> +.TP
>> +.BR PR_SET_MM_ARG_START
> ...
>> +.RE
>> +.\"
>>  .SH "RETURN VALUE"
>>  On success,
>>  .BR PR_GET_DUMPABLE ,
>> @@ -411,7 +549,9 @@ is not recognized.
>>  is
>>  .BR PR_MCE_KILL
>>  or
>> -.BR PR_MCE_KILL_GET ,
>> +.BR PR_MCE_KILL_GET
>> +or
>> +.BR PR_SET_MM ,
>>  and unused
>>  .BR prctl ()
>>  arguments were not specified as zero.
>> @@ -429,6 +569,48 @@ or
>>  .BR PR_SET_SECCOMP ,
>>  and the kernel was not configured with
>>  .BR CONFIG_SECCOMP .
>> +.\" FIXME I added the following lengthy EINVAL entry. Is it correct?
>
> Yes, looks good to me. Thanks! Btw, Michael, could you please send
> me this page in plain text format please (may be provately to not
> flood the list_? I'll re-check it.

I'll post a new version in a moment.

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

[-- Attachment #1: Type: text/plain, Size: 21378 bytes --]

Hi Cyrill,

Below (and also attached) is the current draft of the prctl.2 page
with your PR_SET_MM materials.

Cheers,

Michael

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl)
.\" and Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
.\" and Copyright Guillem Jover <guillem@hadrons.org>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG
.\" Modified 27 Jun 02, Michael Kerrisk
.\" 	Added PR_SET_DUMPABLE, PR_GET_DUMPABLE,
.\"	PR_SET_KEEPCAPS, PR_GET_KEEPCAPS
.\" Modified 2006-08-30 Guillem Jover <guillem@hadrons.org>
.\"	Updated Linux versions where the options where introduced.
.\"	Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME,
.\"	PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU,
.\"	PR_SET_FPEXC, PR_GET_FPEXC
.\" 2008-04-29 Serge Hallyn, Document PR_CAPBSET_READ and PR_CAPBSET_DROP
.\" 2008-06-13 Erik Bosman, <ejbosman@cs.vu.nl>
.\"     Document PR_GET_TSC and PR_SET_TSC.
.\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP
.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL_*
.\"
.\" FIXME: Document PR_SET_TIMERSLACK and PR_GET_TIMERSLACK (new in 2.6.28)
.\" FIXME: Document PR_TASK_PERF_EVENTS_DISABLE and
.\"        PR_TASK_PERF_EVENTS_ENABLE (new in 2.6.32)
.\"
.TH PRCTL 2 2012-04-14 "Linux" "Linux Programmer's Manual"
.SH NAME
prctl \- operations on a process
.SH SYNOPSIS
.nf
.B #include <sys/prctl.h>
.sp
.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 ,
.BI "          unsigned long " arg4 ", unsigned long " arg5 );
.fi
.SH DESCRIPTION
.BR prctl ()
is called with a first argument describing what to do
(with values defined in \fI<linux/prctl.h>\fP), and further
arguments with a significance depending on the first one.
The first argument can be:
.TP
.BR PR_CAPBSET_READ " (since Linux 2.6.25)"
Return (as the function result) 1 if the capability specified in
.I arg2
is in the calling thread's capability bounding set,
or 0 if it is not.
(The capability constants are defined in
.IR <linux/capability.h> .)
The capability bounding set dictates
whether the process can receive the capability through a
file's permitted capability set on a subsequent call to
.BR execve (2).

If the capability specified in
.I arg2
is not valid, then the call fails with the error
.BR EINVAL .
.TP
.BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
If the calling thread has the
.B CAP_SETPCAP
capability, then drop the capability specified by
.I arg2
from the calling thread's capability bounding set.
Any children of the calling thread will inherit the newly
reduced bounding set.

The call fails with the error:
.B EPERM
if the calling thread does not have the
.BR CAP_SETPCAP ;
.BR EINVAL
if
.I arg2
does not represent a valid capability; or
.BR EINVAL
if file capabilities are not enabled in the kernel,
in which case bounding sets are not supported.
.TP
.BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
Set the state of the flag determining whether core dumps are produced
for this process upon delivery of a signal whose default behavior is
to produce a core dump.
(Normally this flag is set for a process by default, but it is cleared
when a set-user-ID or set-group-ID program is executed and also by
various system calls that manipulate process UIDs and GIDs).
In kernels up to and including 2.6.12,
.I arg2
must be either 0 (process is not dumpable) or 1 (process is dumpable).
Between kernels 2.6.13 and 2.6.17, the value 2 was also permitted,
which caused any binary which normally would not be dumped
to be dumped readable by root only;
for security reasons, this feature has been removed.
.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2
.\" Subject:    Fix prctl privilege escalation (CVE-2006-2451)
.\" From:       Marcel Holtmann <marcel () holtmann ! org>
.\" Date:       2006-07-12 11:12:00
(See also the description of
.I /proc/sys/fs/suid_dumpable
in
.BR proc (5).)
Processes that are not dumpable can not be attached via
.BR ptrace(2)
.BR PTRACE_ATTACH .
.TP
.BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
Return (as the function result) the current state of the calling
process's dumpable flag.
.\" Since Linux 2.6.13, the dumpable flag can have the value 2,
.\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
.\" flags has a nonzero value.  This was fixed in 2.6.14.
.TP
.BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Set the endian-ness of the calling process to the value given
in \fIarg2\fP, which should be one of the following:
.\" Respectively 0, 1, 2
.BR PR_ENDIAN_BIG ,
.BR PR_ENDIAN_LITTLE ,
or
.B PR_ENDIAN_PPC_LITTLE
(PowerPC pseudo little endian).
.TP
.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Return the endian-ness of the calling process,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Set floating-point emulation control bits to \fIarg2\fP.
Pass \fBPR_FPEMU_NOPRINT\fP to silently emulate fp operations accesses, or
\fBPR_FPEMU_SIGFPE\fP to not emulate fp operations and send
.B SIGFPE
instead.
.TP
.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Return floating-point emulation control bits,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Set floating-point exception mode to \fIarg2\fP.
Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
\fBPR_FP_EXC_DIV\fP for floating-point divide by zero,
\fBPR_FP_EXC_OVF\fP for floating-point overflow,
\fBPR_FP_EXC_UND\fP for floating-point underflow,
\fBPR_FP_EXC_RES\fP for floating-point inexact result,
\fBPR_FP_EXC_INV\fP for floating-point invalid operation,
\fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled,
\fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
\fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
\fBPR_FP_EXC_PRECISE\fP for precise exception mode.
.TP
.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Return floating-point exception mode,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
Set the state of the thread's "keep capabilities" flag,
which determines whether the threads's permitted
capability set is cleared when a change is made to the threads's user IDs
such that the threads's real UID, effective UID, and saved set-user-ID
all become nonzero when at least one of them previously had the value 0.
By default, the permitted capability set is cleared when such a change is made;
setting the "keep capabilities" flag prevents it from being cleared.
.I arg2
must be either 0 (permitted capabilities are cleared)
or 1 (permitted capabilities are kept).
(A thread's
.I effective
capability set is always cleared when such a credential change is made,
regardless of the setting of the "keep capabilities" flag.)
The "keep capabilities" value will be reset to 0 on subsequent calls to
.BR execve (2).
.TP
.BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
Return (as the function result) the current state of the calling threads's
"keep capabilities" flag.
.TP
.BR PR_SET_NAME " (since Linux 2.6.9)"
Set the process name for the calling process,
using the value in the location pointed to by
.IR "(char\ *) arg2" .
The name can be up to 16 bytes long,
.\" TASK_COMM_LEN in include/linux/sched.h
and should be null-terminated if it contains fewer bytes.
.TP
.BR PR_GET_NAME " (since Linux 2.6.11)"
Return the process name for the calling process,
in the buffer pointed to by
.IR "(char\ *) arg2" .
The buffer should allow space for up to 16 bytes;
the returned string will be null-terminated if it is shorter than that.
.TP
.BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
Set the parent process death signal
of the calling process to \fIarg2\fP (either a signal value
in the range 1..maxsig, or 0 to clear).
This is the signal that the calling process will get when its
parent dies.
This value is cleared for the child of a
.BR fork (2).
.TP
.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
Return the current value of the parent process death signal,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_SECCOMP " (since Linux 2.6.23)"
.\" See http://thread.gmane.org/gmane.linux.kernel/542632
.\" [PATCH 0 of 2] seccomp updates
.\" andrea@cpushare.com
Set the secure computing mode for the calling thread.
In the current implementation,
.IR arg2
must be 1.
After the secure computing mode has been set to 1,
the only system calls that the thread is permitted to make are
.BR read (2),
.BR write (2),
.BR _exit (2),
and
.BR sigreturn (2).
Other system calls result in the delivery of a
.BR SIGKILL
signal.
Secure computing mode is useful for number-crunching applications
that may need to execute untrusted byte code,
perhaps obtained by reading from a pipe or socket.
This operation is only available
if the kernel is configured with CONFIG_SECCOMP enabled.
.TP
.BR PR_GET_SECCOMP " (since Linux 2.6.23)"
Return the secure computing mode of the calling thread.
Not very useful for the current implementation (mode equals 1),
but may be useful for other possible future modes:
if the caller is not in secure computing mode, this operation returns 0;
if the caller is in secure computing mode, then the
.BR prctl ()
call will cause a
.B SIGKILL
signal to be sent to the process.
This operation is only available
if the kernel is configured with CONFIG_SECCOMP enabled.
.TP
.BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
Set the "securebits" flags of the calling thread to the value supplied in
.IR arg2 .
See
.BR capabilities (7).
.TP
.BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
Return (as the function result)
the "securebits" flags of the calling thread.
See
.BR capabilities (7).
.TP
.BR PR_SET_TIMING " (since Linux 2.6.0-test4)"
Set whether to use (normal, traditional) statistical process timing or
accurate timestamp-based process timing, by passing
.B PR_TIMING_STATISTICAL
.\" 0
or
.B PR_TIMING_TIMESTAMP
.\" 1
to \fIarg2\fP.
.B PR_TIMING_TIMESTAMP
is not currently implemented
(attempting to set this mode will yield the error
.BR EINVAL ).
.\" PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8,
.\" and looking at the patch history, it appears
.\" that it never did anything.
.TP
.BR PR_GET_TIMING " (since Linux 2.6.0-test4)"
Return (as the function result) which process timing method is currently
in use.
.TP
.BR PR_SET_TSC " (since Linux 2.6.26, x86 only)"
Set the state of the flag determining whether the timestamp counter
can be read by the process.
Pass
.B PR_TSC_ENABLE
to
.I arg2
to allow it to be read, or
.B PR_TSC_SIGSEGV
to generate a
.B SIGSEGV
when the process tries to read the timestamp counter.
.TP
.BR PR_GET_TSC " (since Linux 2.6.26, x86 only)"
Return the state of the flag determining whether the timestamp counter
can be read,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.B PR_SET_UNALIGN
(Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22)
Set unaligned access control bits to \fIarg2\fP.
Pass
\fBPR_UNALIGN_NOPRINT\fP to silently fix up unaligned user accesses,
or \fBPR_UNALIGN_SIGBUS\fP to generate
.B SIGBUS
on unaligned user access.
.TP
.B PR_GET_UNALIGN
(see
.B PR_SET_UNALIGN
for information on versions and architectures)
Return unaligned access control bits, in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_MCE_KILL " (since Linux 2.6.32)"
Set the machine check memory corruption kill policy for the current thread.
If
.I arg2
is
.BR PR_MCE_KILL_CLEAR ,
clear the thread memory corruption kill policy and use the system-wide default.
(The system-wide default is defined by
.IR /proc/sys/vm/memory_failure_early_kill ;
see
.BR proc (5).)
If
.I arg2
is
.BR PR_MCE_KILL_SET ,
use a thread-specific memory corruption kill policy.
In this case,
.I arg3
defines whether the policy is
.I early kill
.RB ( PR_MCE_KILL_EARLY ),
.I late kill
.RB ( PR_MCE_KILL_LATE ),
or the system-wide default
.RB ( PR_MCE_KILL_DEFAULT ).
Early kill means that the thread receives a
.B SIGBUS
signal as soon as hardware memory corruption is detected inside
its address space.
In late kill mode, the process is only killed when it accesses a corrupted page.
See
.BR sigaction (2)
for more information on the
.BR SIGBUS
signal.
The policy is inherited by children.
The remaining unused
.BR prctl ()
arguments must be zero for future compatibility.
.TP
.BR PR_MCE_KILL_GET " (since Linux 2.6.32)"
Return the current per-process machine check kill policy.
All unused
.BR prctl ()
arguments must be zero.
.TP
.BR PR_SET_MM " (since Linux 3.3)"
Modify certain kernel memory map descriptor fields
of the calling process.
Usually these fields are set by the kernel and dynamic loader (see
.BR ld.so (8)
for more information) and a regular application should not use this feature.
However, there are cases, such as self-modifying programs,
where a program might find it useful to change its own memory map.
This feature is available only if the kernel is built with the
.BR CONFIG_CHECKPOINT_RESTORE
option enabled.
The calling process must have the
.BR CAP_SYS_RESOURCE
capability.
The value in
.I arg2
is one of the options below, while
.I arg3
provides a new value for the option.
.RS
.TP
.BR PR_SET_MM_START_CODE
Set the address above which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or sharable (see
.BR mprotect (2)
and
.BR mmap (2)
for more information).
.TP
.BR PR_SET_MM_END_CODE
Set the address below which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or sharable.
.TP
.BR PR_SET_MM_START_DATA
Set the address above which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
but not executable or sharable.
.TP
.B PR_SET_MM_END_DATA
Set the address below which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
but not executable or sharable.
.TP
.BR PR_SET_MM_START_STACK
Set the start address of the stack.
The corresponding memory area must be readable and writable.
.TP
.BR PR_SET_MM_START_BRK
Set the address above which the program heap can be expanded with
.BR brk (2)
call.
The address must be greater than the ending address of
the current program data segment.
In addition, the combined size of the resulting heap and
the size of the data segment can't exceed the
.BR RLIMIT_DATA
resource limit (see
.BR setrlimit (2)).
.TP
.BR PR_SET_MM_BRK
Set the current
.BR brk (2)
value.
The requirements for the address are the same as for the
.BR PR_SET_MM_START_BRK
option.
.\" FIXME The following (until ========) is not yet in mainline kernel,
.\" so commented out for the moment.
.\" .TP
.\" .BR PR_SET_MM_ARG_START
.\" Set the address above which the program command line is placed.
.\" .TP
.\" .BR PR_SET_MM_ARG_END
.\" Set the address below which the program command line is placed.
.\" .TP
.\" .BR PR_SET_MM_ENV_START
.\" Set the address above which the program environment is placed.
.\" .TP
.\" .BR PR_SET_MM_ENV_END
.\" Set the address below which the program environment is placed.
.\" .IP
.\" The address passed with
.\" .BR PR_SET_MM_ARG_START ,
.\" .BR PR_SET_MM_ARG_END ,
.\" .BR PR_SET_MM_ENV_START ,
.\" and
.\" .BR PR_SET_MM_ENV_END
.\" should belong to a process stack area.
.\" Thus, the corresponding memory area must be readable, writable, and
.\" (depending on the kernel configuration) have the
.\" .BR MAP_GROWSDOWN
.\" attribute set (see
.\" .BR mmap (2)).
.\" .TP
.\" .BR PR_SET_MM_AUXV
.\" Set a new auxiliary vector.
.\" The
.\" .I arg3
.\" argument should provide the address of the vector.
.\" The
.\" .I arg4
.\" is the size of the vector.
.\" .TP
.\" .BR PR_SET_MM_EXE_FILE
.\" Supersede the
.\" .IR /proc/pid/exe
.\" symbolic link with a new one pointing to a new executable file
.\" identified by the file descriptor provided in
.\" .I arg3
.\" argument.
.\" The file descriptor should be obtained with a regular
.\" .BR open (2)
.\" call.
.\" .IP
.\" To change the symbolic link, one needs to unmap all existing
.\" executable memory areas, including those created by the kernel itself
.\" (for example the kernel usually creates at least one executable
.\" memory area for the ELF
.\" .IR \.text
.\" section).
.\" .IP
.\" The second limitation is that such transitions can be done only once
.\" in a process life time.
.\" Any further attempts will be rejected.
.\" This should help system administrators to monitor unusual
.\" symbolic-link transitions over all process running in a system.
.\" ========== END FIXME
.RE
.\"
.SH "RETURN VALUE"
On success,
.BR PR_GET_DUMPABLE ,
.BR PR_GET_KEEPCAPS ,
.BR PR_CAPBSET_READ ,
.BR PR_GET_TIMING ,
.BR PR_GET_SECUREBITS ,
.BR PR_MCE_KILL_GET ,
and (if it returns)
.BR PR_GET_SECCOMP
return the nonnegative values described above.
All other
.I option
values return 0 on success.
On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B EFAULT
.I arg2
is an invalid address.
.TP
.B EINVAL
The value of
.I option
is not recognized.
.TP
.B EINVAL
.I option
is
.BR PR_MCE_KILL
or
.BR PR_MCE_KILL_GET
or
.BR PR_SET_MM ,
and unused
.BR prctl ()
arguments were not specified as zero.
.TP
.B EINVAL
.I arg2
is not valid value for this
.IR option .
.TP
.B EINVAL
.I option
is
.BR PR_SET_SECCOMP
or
.BR PR_SET_SECCOMP ,
and the kernel was not configured with
.BR CONFIG_SECCOMP .
.TP
.B EINVAL
.I option
is
.BR PR_SET_MM ,
and one of the following is true
.RS
.IP * 3
.I arg4
or
.I arg5
is nonzero;
.IP *
.I arg3
is greater than
.B TASK_SIZE
(the limit on the size of the user address space for this architecture);
.IP *
.I arg2
is
.BR PR_SET_MM_START_CODE ,
.BR PR_SET_MM_END_CODE ,
.BR PR_SET_MM_START_DATA ,
.BR PR_SET_MM_END_DATA ,
or
.BR PR_SET_MM_START_STACK,
and the permissions of the corresponding memory area are not as required;
.IP *
.I arg2
is
.BR PR_SET_MM_START_BRK
or
.BR PR_SET_MM_BRK ,
and
.I arg3
is less than or equal to the end of the data segment
or specifies a value that would cause the
.B RLIMIT_DATA
resource limit to be exceeded.
.RE
.TP
.B EPERM
.I option
is
.BR PR_SET_SECUREBITS ,
and the caller does not have the
.B CAP_SETPCAP
capability,
or tried to unset a "locked" flag,
or tried to set a flag whose corresponding locked flag was set
(see
.BR capabilities (7)).
.TP
.B EPERM
.I option
is
.BR PR_SET_KEEPCAPS ,
and the callers's
.B SECURE_KEEP_CAPS_LOCKED
flag is set
(see
.BR capabilities (7)).
.TP
.B EPERM
.I option
is
.BR PR_CAPBSET_DROP ,
and the caller does not have the
.B CAP_SETPCAP
capability.
.TP
.B EPERM
.I option
is
.BR PR_SET_MM ,
and the caller does not have the
.B CAP_SYS_RESOURCE
capability.
.\" FIXME The following (until ========) is not yet in mainline kernel,
.\" so commented out for the moment.
.\" .TP
.\" .B EACCES
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" and
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" the file is not executable.
.\" .TP
.\" .B EBUSY
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" and this the second attempt to change the
.\" .I /proc/pid/exe
.\" symbolic link, which is prohibited.
.\" .TP
.\" .B EBADF
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" and the file descriptor passed in
.\" .I arg4
.\" is not valid.
.\" ========== END FIXME
.\" The following can't actually happen, because prctl() in
.\" seccomp mode will cause SIGKILL.
.\" .TP
.\" .B EPERM
.\" .I option
.\" is
.\" .BR PR_SET_SECCOMP ,
.\" and secure computing mode is already 1.
.SH VERSIONS
The
.BR prctl ()
system call was introduced in Linux 2.1.57.
.\" The library interface was added in glibc 2.0.6
.SH "CONFORMING TO"
This call is Linux-specific.
IRIX has a
.BR prctl ()
system call (also introduced in Linux 2.1.44
as irix_prctl on the MIPS architecture),
with prototype
.sp
.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 );
.sp
and options to get the maximum number of processes per user,
get the maximum number of processors the calling process can use,
find out whether a specified process is currently blocked,
get or set the maximum stack size, etc.
.SH "SEE ALSO"
.BR signal (2),
.BR core (5)

[-- Attachment #2: prctl.2 --]
[-- Type: application/octet-stream, Size: 21250 bytes --]

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl)
.\" and Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
.\" and Copyright Guillem Jover <guillem@hadrons.org>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG
.\" Modified 27 Jun 02, Michael Kerrisk
.\" 	Added PR_SET_DUMPABLE, PR_GET_DUMPABLE,
.\"	PR_SET_KEEPCAPS, PR_GET_KEEPCAPS
.\" Modified 2006-08-30 Guillem Jover <guillem@hadrons.org>
.\"	Updated Linux versions where the options where introduced.
.\"	Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME,
.\"	PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU,
.\"	PR_SET_FPEXC, PR_GET_FPEXC
.\" 2008-04-29 Serge Hallyn, Document PR_CAPBSET_READ and PR_CAPBSET_DROP
.\" 2008-06-13 Erik Bosman, <ejbosman@cs.vu.nl>
.\"     Document PR_GET_TSC and PR_SET_TSC.
.\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP
.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL_*
.\"
.\" FIXME: Document PR_SET_TIMERSLACK and PR_GET_TIMERSLACK (new in 2.6.28)
.\" FIXME: Document PR_TASK_PERF_EVENTS_DISABLE and
.\"        PR_TASK_PERF_EVENTS_ENABLE (new in 2.6.32)
.\"
.TH PRCTL 2 2012-04-14 "Linux" "Linux Programmer's Manual"
.SH NAME
prctl \- operations on a process
.SH SYNOPSIS
.nf
.B #include <sys/prctl.h>
.sp
.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 ,
.BI "          unsigned long " arg4 ", unsigned long " arg5 );
.fi
.SH DESCRIPTION
.BR prctl ()
is called with a first argument describing what to do
(with values defined in \fI<linux/prctl.h>\fP), and further
arguments with a significance depending on the first one.
The first argument can be:
.TP
.BR PR_CAPBSET_READ " (since Linux 2.6.25)"
Return (as the function result) 1 if the capability specified in
.I arg2
is in the calling thread's capability bounding set,
or 0 if it is not.
(The capability constants are defined in
.IR <linux/capability.h> .)
The capability bounding set dictates
whether the process can receive the capability through a
file's permitted capability set on a subsequent call to
.BR execve (2).

If the capability specified in
.I arg2
is not valid, then the call fails with the error
.BR EINVAL .
.TP
.BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
If the calling thread has the
.B CAP_SETPCAP
capability, then drop the capability specified by
.I arg2
from the calling thread's capability bounding set.
Any children of the calling thread will inherit the newly
reduced bounding set.

The call fails with the error:
.B EPERM
if the calling thread does not have the
.BR CAP_SETPCAP ;
.BR EINVAL
if
.I arg2
does not represent a valid capability; or
.BR EINVAL
if file capabilities are not enabled in the kernel,
in which case bounding sets are not supported.
.TP
.BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
Set the state of the flag determining whether core dumps are produced
for this process upon delivery of a signal whose default behavior is
to produce a core dump.
(Normally this flag is set for a process by default, but it is cleared
when a set-user-ID or set-group-ID program is executed and also by
various system calls that manipulate process UIDs and GIDs).
In kernels up to and including 2.6.12,
.I arg2
must be either 0 (process is not dumpable) or 1 (process is dumpable).
Between kernels 2.6.13 and 2.6.17, the value 2 was also permitted,
which caused any binary which normally would not be dumped
to be dumped readable by root only;
for security reasons, this feature has been removed.
.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2
.\" Subject:    Fix prctl privilege escalation (CVE-2006-2451)
.\" From:       Marcel Holtmann <marcel () holtmann ! org>
.\" Date:       2006-07-12 11:12:00
(See also the description of
.I /proc/sys/fs/suid_dumpable
in
.BR proc (5).)
Processes that are not dumpable can not be attached via
.BR ptrace(2)
.BR PTRACE_ATTACH .
.TP
.BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
Return (as the function result) the current state of the calling
process's dumpable flag.
.\" Since Linux 2.6.13, the dumpable flag can have the value 2,
.\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
.\" flags has a nonzero value.  This was fixed in 2.6.14.
.TP
.BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Set the endian-ness of the calling process to the value given
in \fIarg2\fP, which should be one of the following:
.\" Respectively 0, 1, 2
.BR PR_ENDIAN_BIG ,
.BR PR_ENDIAN_LITTLE ,
or
.B PR_ENDIAN_PPC_LITTLE
(PowerPC pseudo little endian).
.TP
.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Return the endian-ness of the calling process,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Set floating-point emulation control bits to \fIarg2\fP.
Pass \fBPR_FPEMU_NOPRINT\fP to silently emulate fp operations accesses, or
\fBPR_FPEMU_SIGFPE\fP to not emulate fp operations and send
.B SIGFPE
instead.
.TP
.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Return floating-point emulation control bits,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Set floating-point exception mode to \fIarg2\fP.
Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
\fBPR_FP_EXC_DIV\fP for floating-point divide by zero,
\fBPR_FP_EXC_OVF\fP for floating-point overflow,
\fBPR_FP_EXC_UND\fP for floating-point underflow,
\fBPR_FP_EXC_RES\fP for floating-point inexact result,
\fBPR_FP_EXC_INV\fP for floating-point invalid operation,
\fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled,
\fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
\fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
\fBPR_FP_EXC_PRECISE\fP for precise exception mode.
.TP
.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Return floating-point exception mode,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
Set the state of the thread's "keep capabilities" flag,
which determines whether the threads's permitted
capability set is cleared when a change is made to the threads's user IDs
such that the threads's real UID, effective UID, and saved set-user-ID
all become nonzero when at least one of them previously had the value 0.
By default, the permitted capability set is cleared when such a change is made;
setting the "keep capabilities" flag prevents it from being cleared.
.I arg2
must be either 0 (permitted capabilities are cleared)
or 1 (permitted capabilities are kept).
(A thread's
.I effective
capability set is always cleared when such a credential change is made,
regardless of the setting of the "keep capabilities" flag.)
The "keep capabilities" value will be reset to 0 on subsequent calls to
.BR execve (2).
.TP
.BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
Return (as the function result) the current state of the calling threads's
"keep capabilities" flag.
.TP
.BR PR_SET_NAME " (since Linux 2.6.9)"
Set the process name for the calling process,
using the value in the location pointed to by
.IR "(char\ *) arg2" .
The name can be up to 16 bytes long,
.\" TASK_COMM_LEN in include/linux/sched.h
and should be null-terminated if it contains fewer bytes.
.TP
.BR PR_GET_NAME " (since Linux 2.6.11)"
Return the process name for the calling process,
in the buffer pointed to by
.IR "(char\ *) arg2" .
The buffer should allow space for up to 16 bytes;
the returned string will be null-terminated if it is shorter than that.
.TP
.BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
Set the parent process death signal
of the calling process to \fIarg2\fP (either a signal value
in the range 1..maxsig, or 0 to clear).
This is the signal that the calling process will get when its
parent dies.
This value is cleared for the child of a
.BR fork (2).
.TP
.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
Return the current value of the parent process death signal,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_SECCOMP " (since Linux 2.6.23)"
.\" See http://thread.gmane.org/gmane.linux.kernel/542632
.\" [PATCH 0 of 2] seccomp updates
.\" andrea@cpushare.com
Set the secure computing mode for the calling thread.
In the current implementation,
.IR arg2
must be 1.
After the secure computing mode has been set to 1,
the only system calls that the thread is permitted to make are
.BR read (2),
.BR write (2),
.BR _exit (2),
and
.BR sigreturn (2).
Other system calls result in the delivery of a
.BR SIGKILL
signal.
Secure computing mode is useful for number-crunching applications
that may need to execute untrusted byte code,
perhaps obtained by reading from a pipe or socket.
This operation is only available
if the kernel is configured with CONFIG_SECCOMP enabled.
.TP
.BR PR_GET_SECCOMP " (since Linux 2.6.23)"
Return the secure computing mode of the calling thread.
Not very useful for the current implementation (mode equals 1),
but may be useful for other possible future modes:
if the caller is not in secure computing mode, this operation returns 0;
if the caller is in secure computing mode, then the
.BR prctl ()
call will cause a
.B SIGKILL
signal to be sent to the process.
This operation is only available
if the kernel is configured with CONFIG_SECCOMP enabled.
.TP
.BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
Set the "securebits" flags of the calling thread to the value supplied in
.IR arg2 .
See
.BR capabilities (7).
.TP
.BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
Return (as the function result)
the "securebits" flags of the calling thread.
See
.BR capabilities (7).
.TP
.BR PR_SET_TIMING " (since Linux 2.6.0-test4)"
Set whether to use (normal, traditional) statistical process timing or
accurate timestamp-based process timing, by passing
.B PR_TIMING_STATISTICAL
.\" 0
or
.B PR_TIMING_TIMESTAMP
.\" 1
to \fIarg2\fP.
.B PR_TIMING_TIMESTAMP
is not currently implemented
(attempting to set this mode will yield the error
.BR EINVAL ).
.\" PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8,
.\" and looking at the patch history, it appears
.\" that it never did anything.
.TP
.BR PR_GET_TIMING " (since Linux 2.6.0-test4)"
Return (as the function result) which process timing method is currently
in use.
.TP
.BR PR_SET_TSC " (since Linux 2.6.26, x86 only)"
Set the state of the flag determining whether the timestamp counter
can be read by the process.
Pass
.B PR_TSC_ENABLE
to
.I arg2
to allow it to be read, or
.B PR_TSC_SIGSEGV
to generate a
.B SIGSEGV
when the process tries to read the timestamp counter.
.TP
.BR PR_GET_TSC " (since Linux 2.6.26, x86 only)"
Return the state of the flag determining whether the timestamp counter
can be read,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.B PR_SET_UNALIGN
(Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22)
Set unaligned access control bits to \fIarg2\fP.
Pass
\fBPR_UNALIGN_NOPRINT\fP to silently fix up unaligned user accesses,
or \fBPR_UNALIGN_SIGBUS\fP to generate
.B SIGBUS
on unaligned user access.
.TP
.B PR_GET_UNALIGN
(see
.B PR_SET_UNALIGN
for information on versions and architectures)
Return unaligned access control bits, in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_MCE_KILL " (since Linux 2.6.32)"
Set the machine check memory corruption kill policy for the current thread.
If
.I arg2
is
.BR PR_MCE_KILL_CLEAR ,
clear the thread memory corruption kill policy and use the system-wide default.
(The system-wide default is defined by
.IR /proc/sys/vm/memory_failure_early_kill ;
see
.BR proc (5).)
If
.I arg2
is
.BR PR_MCE_KILL_SET ,
use a thread-specific memory corruption kill policy.
In this case,
.I arg3
defines whether the policy is
.I early kill
.RB ( PR_MCE_KILL_EARLY ),
.I late kill
.RB ( PR_MCE_KILL_LATE ),
or the system-wide default
.RB ( PR_MCE_KILL_DEFAULT ).
Early kill means that the thread receives a
.B SIGBUS
signal as soon as hardware memory corruption is detected inside
its address space.
In late kill mode, the process is only killed when it accesses a corrupted page.
See
.BR sigaction (2)
for more information on the
.BR SIGBUS
signal.
The policy is inherited by children.
The remaining unused
.BR prctl ()
arguments must be zero for future compatibility.
.TP
.BR PR_MCE_KILL_GET " (since Linux 2.6.32)"
Return the current per-process machine check kill policy.
All unused
.BR prctl ()
arguments must be zero.
.TP
.BR PR_SET_MM " (since Linux 3.3)"
Modify certain kernel memory map descriptor fields
of the calling process.
Usually these fields are set by the kernel and dynamic loader (see
.BR ld.so (8)
for more information) and a regular application should not use this feature.
However, there are cases, such as self-modifying programs,
where a program might find it useful to change its own memory map.
This feature is available only if the kernel is built with the 
.BR CONFIG_CHECKPOINT_RESTORE
option enabled.
The calling process must have the
.BR CAP_SYS_RESOURCE
capability.
The value in
.I arg2
is one of the options below, while
.I arg3
provides a new value for the option.
.RS
.TP
.BR PR_SET_MM_START_CODE
Set the address above which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or sharable (see
.BR mprotect (2)
and
.BR mmap (2)
for more information).
.TP
.BR PR_SET_MM_END_CODE
Set the address below which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or sharable.
.TP
.BR PR_SET_MM_START_DATA
Set the address above which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
but not executable or sharable.
.TP
.B PR_SET_MM_END_DATA
Set the address below which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
but not executable or sharable.
.TP
.BR PR_SET_MM_START_STACK
Set the start address of the stack.
The corresponding memory area must be readable and writable.
.TP
.BR PR_SET_MM_START_BRK
Set the address above which the program heap can be expanded with
.BR brk (2)
call.
The address must be greater than the ending address of
the current program data segment.
In addition, the combined size of the resulting heap and
the size of the data segment can't exceed the
.BR RLIMIT_DATA
resource limit (see
.BR setrlimit (2)).
.TP
.BR PR_SET_MM_BRK
Set the current
.BR brk (2)
value.
The requirements for the address are the same as for the
.BR PR_SET_MM_START_BRK
option.
.\" FIXME The following (until ========) is not yet in mainline kernel,
.\" so commented out for the moment.
.\" .TP
.\" .BR PR_SET_MM_ARG_START
.\" Set the address above which the program command line is placed.
.\" .TP
.\" .BR PR_SET_MM_ARG_END
.\" Set the address below which the program command line is placed.
.\" .TP
.\" .BR PR_SET_MM_ENV_START
.\" Set the address above which the program environment is placed.
.\" .TP
.\" .BR PR_SET_MM_ENV_END
.\" Set the address below which the program environment is placed.
.\" .IP
.\" The address passed with
.\" .BR PR_SET_MM_ARG_START ,
.\" .BR PR_SET_MM_ARG_END ,
.\" .BR PR_SET_MM_ENV_START ,
.\" and
.\" .BR PR_SET_MM_ENV_END
.\" should belong to a process stack area.
.\" Thus, the corresponding memory area must be readable, writable, and
.\" (depending on the kernel configuration) have the
.\" .BR MAP_GROWSDOWN
.\" attribute set (see
.\" .BR mmap (2)).
.\" .TP
.\" .BR PR_SET_MM_AUXV
.\" Set a new auxiliary vector.
.\" The
.\" .I arg3
.\" argument should provide the address of the vector.
.\" The
.\" .I arg4
.\" is the size of the vector.
.\" .TP
.\" .BR PR_SET_MM_EXE_FILE
.\" Supersede the
.\" .IR /proc/pid/exe
.\" symbolic link with a new one pointing to a new executable file
.\" identified by the file descriptor provided in
.\" .I arg3
.\" argument.
.\" The file descriptor should be obtained with a regular
.\" .BR open (2)
.\" call.
.\" .IP
.\" To change the symbolic link, one needs to unmap all existing
.\" executable memory areas, including those created by the kernel itself
.\" (for example the kernel usually creates at least one executable
.\" memory area for the ELF
.\" .IR \.text
.\" section).
.\" .IP
.\" The second limitation is that such transitions can be done only once
.\" in a process life time.
.\" Any further attempts will be rejected.
.\" This should help system administrators to monitor unusual
.\" symbolic-link transitions over all process running in a system.
.\" ========== END FIXME
.RE
.\"
.SH "RETURN VALUE"
On success,
.BR PR_GET_DUMPABLE ,
.BR PR_GET_KEEPCAPS ,
.BR PR_CAPBSET_READ ,
.BR PR_GET_TIMING ,
.BR PR_GET_SECUREBITS ,
.BR PR_MCE_KILL_GET ,
and (if it returns)
.BR PR_GET_SECCOMP
return the nonnegative values described above.
All other
.I option
values return 0 on success.
On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B EFAULT
.I arg2
is an invalid address.
.TP
.B EINVAL
The value of
.I option
is not recognized.
.TP
.B EINVAL
.I option
is
.BR PR_MCE_KILL
or
.BR PR_MCE_KILL_GET
or
.BR PR_SET_MM ,
and unused
.BR prctl ()
arguments were not specified as zero.
.TP
.B EINVAL
.I arg2
is not valid value for this
.IR option .
.TP
.B EINVAL
.I option
is
.BR PR_SET_SECCOMP
or
.BR PR_SET_SECCOMP ,
and the kernel was not configured with
.BR CONFIG_SECCOMP .
.TP
.B EINVAL
.I option
is
.BR PR_SET_MM ,
and one of the following is true
.RS
.IP * 3
.I arg4
or
.I arg5
is nonzero;
.IP *
.I arg3
is greater than
.B TASK_SIZE
(the limit on the size of the user address space for this architecture);
.IP *
.I arg2
is
.BR PR_SET_MM_START_CODE ,
.BR PR_SET_MM_END_CODE ,
.BR PR_SET_MM_START_DATA ,
.BR PR_SET_MM_END_DATA ,
or
.BR PR_SET_MM_START_STACK,
and the permissions of the corresponding memory area are not as required;
.IP *
.I arg2
is
.BR PR_SET_MM_START_BRK
or
.BR PR_SET_MM_BRK ,
and
.I arg3
is less than or equal to the end of the data segment
or specifies a value that would cause the
.B RLIMIT_DATA
resource limit to be exceeded.
.RE
.TP
.B EPERM
.I option
is
.BR PR_SET_SECUREBITS ,
and the caller does not have the
.B CAP_SETPCAP
capability,
or tried to unset a "locked" flag,
or tried to set a flag whose corresponding locked flag was set
(see
.BR capabilities (7)).
.TP
.B EPERM
.I option
is
.BR PR_SET_KEEPCAPS ,
and the callers's
.B SECURE_KEEP_CAPS_LOCKED
flag is set
(see
.BR capabilities (7)).
.TP
.B EPERM
.I option
is
.BR PR_CAPBSET_DROP ,
and the caller does not have the
.B CAP_SETPCAP
capability.
.TP
.B EPERM
.I option
is
.BR PR_SET_MM ,
and the caller does not have the
.B CAP_SYS_RESOURCE
capability.
.\" FIXME The following (until ========) is not yet in mainline kernel,
.\" so commented out for the moment.
.\" .TP
.\" .B EACCES
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" and
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" the file is not executable.
.\" .TP
.\" .B EBUSY
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" and this the second attempt to change the
.\" .I /proc/pid/exe
.\" symbolic link, which is prohibited.
.\" .TP
.\" .B EBADF
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" and the file descriptor passed in
.\" .I arg4
.\" is not valid.
.\" ========== END FIXME
.\" The following can't actually happen, because prctl() in
.\" seccomp mode will cause SIGKILL.
.\" .TP
.\" .B EPERM
.\" .I option
.\" is
.\" .BR PR_SET_SECCOMP ,
.\" and secure computing mode is already 1.
.SH VERSIONS
The
.BR prctl ()
system call was introduced in Linux 2.1.57.
.\" The library interface was added in glibc 2.0.6
.SH "CONFORMING TO"
This call is Linux-specific.
IRIX has a
.BR prctl ()
system call (also introduced in Linux 2.1.44
as irix_prctl on the MIPS architecture),
with prototype
.sp
.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 );
.sp
and options to get the maximum number of processes per user,
get the maximum number of processors the calling process can use,
find out whether a specified process is currently blocked,
get or set the maximum stack size, etc.
.SH "SEE ALSO"
.BR signal (2),
.BR core (5)

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

[-- Attachment #1: Type: text/plain, Size: 21533 bytes --]

Hi Cyrill,

Below (and also attached) is the current draft of the prctl.2 page
with your PR_SET_MM materials.

Cheers,

Michael

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 1998 Andries Brouwer (aeb-rh8NL+sEX9E@public.gmane.org)
.\" and Copyright (C) 2002 Michael Kerrisk <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
.\" and Copyright Guillem Jover <guillem-+FW4gsLVM0RAfugRpC6u6w@public.gmane.org>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG
.\" Modified 27 Jun 02, Michael Kerrisk
.\" 	Added PR_SET_DUMPABLE, PR_GET_DUMPABLE,
.\"	PR_SET_KEEPCAPS, PR_GET_KEEPCAPS
.\" Modified 2006-08-30 Guillem Jover <guillem-+FW4gsLVM0RAfugRpC6u6w@public.gmane.org>
.\"	Updated Linux versions where the options where introduced.
.\"	Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME,
.\"	PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU,
.\"	PR_SET_FPEXC, PR_GET_FPEXC
.\" 2008-04-29 Serge Hallyn, Document PR_CAPBSET_READ and PR_CAPBSET_DROP
.\" 2008-06-13 Erik Bosman, <ejbosman-FV+mU1CFjts@public.gmane.org>
.\"     Document PR_GET_TSC and PR_SET_TSC.
.\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP
.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL_*
.\"
.\" FIXME: Document PR_SET_TIMERSLACK and PR_GET_TIMERSLACK (new in 2.6.28)
.\" FIXME: Document PR_TASK_PERF_EVENTS_DISABLE and
.\"        PR_TASK_PERF_EVENTS_ENABLE (new in 2.6.32)
.\"
.TH PRCTL 2 2012-04-14 "Linux" "Linux Programmer's Manual"
.SH NAME
prctl \- operations on a process
.SH SYNOPSIS
.nf
.B #include <sys/prctl.h>
.sp
.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 ,
.BI "          unsigned long " arg4 ", unsigned long " arg5 );
.fi
.SH DESCRIPTION
.BR prctl ()
is called with a first argument describing what to do
(with values defined in \fI<linux/prctl.h>\fP), and further
arguments with a significance depending on the first one.
The first argument can be:
.TP
.BR PR_CAPBSET_READ " (since Linux 2.6.25)"
Return (as the function result) 1 if the capability specified in
.I arg2
is in the calling thread's capability bounding set,
or 0 if it is not.
(The capability constants are defined in
.IR <linux/capability.h> .)
The capability bounding set dictates
whether the process can receive the capability through a
file's permitted capability set on a subsequent call to
.BR execve (2).

If the capability specified in
.I arg2
is not valid, then the call fails with the error
.BR EINVAL .
.TP
.BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
If the calling thread has the
.B CAP_SETPCAP
capability, then drop the capability specified by
.I arg2
from the calling thread's capability bounding set.
Any children of the calling thread will inherit the newly
reduced bounding set.

The call fails with the error:
.B EPERM
if the calling thread does not have the
.BR CAP_SETPCAP ;
.BR EINVAL
if
.I arg2
does not represent a valid capability; or
.BR EINVAL
if file capabilities are not enabled in the kernel,
in which case bounding sets are not supported.
.TP
.BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
Set the state of the flag determining whether core dumps are produced
for this process upon delivery of a signal whose default behavior is
to produce a core dump.
(Normally this flag is set for a process by default, but it is cleared
when a set-user-ID or set-group-ID program is executed and also by
various system calls that manipulate process UIDs and GIDs).
In kernels up to and including 2.6.12,
.I arg2
must be either 0 (process is not dumpable) or 1 (process is dumpable).
Between kernels 2.6.13 and 2.6.17, the value 2 was also permitted,
which caused any binary which normally would not be dumped
to be dumped readable by root only;
for security reasons, this feature has been removed.
.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2
.\" Subject:    Fix prctl privilege escalation (CVE-2006-2451)
.\" From:       Marcel Holtmann <marcel () holtmann ! org>
.\" Date:       2006-07-12 11:12:00
(See also the description of
.I /proc/sys/fs/suid_dumpable
in
.BR proc (5).)
Processes that are not dumpable can not be attached via
.BR ptrace(2)
.BR PTRACE_ATTACH .
.TP
.BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
Return (as the function result) the current state of the calling
process's dumpable flag.
.\" Since Linux 2.6.13, the dumpable flag can have the value 2,
.\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
.\" flags has a nonzero value.  This was fixed in 2.6.14.
.TP
.BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Set the endian-ness of the calling process to the value given
in \fIarg2\fP, which should be one of the following:
.\" Respectively 0, 1, 2
.BR PR_ENDIAN_BIG ,
.BR PR_ENDIAN_LITTLE ,
or
.B PR_ENDIAN_PPC_LITTLE
(PowerPC pseudo little endian).
.TP
.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Return the endian-ness of the calling process,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Set floating-point emulation control bits to \fIarg2\fP.
Pass \fBPR_FPEMU_NOPRINT\fP to silently emulate fp operations accesses, or
\fBPR_FPEMU_SIGFPE\fP to not emulate fp operations and send
.B SIGFPE
instead.
.TP
.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Return floating-point emulation control bits,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Set floating-point exception mode to \fIarg2\fP.
Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
\fBPR_FP_EXC_DIV\fP for floating-point divide by zero,
\fBPR_FP_EXC_OVF\fP for floating-point overflow,
\fBPR_FP_EXC_UND\fP for floating-point underflow,
\fBPR_FP_EXC_RES\fP for floating-point inexact result,
\fBPR_FP_EXC_INV\fP for floating-point invalid operation,
\fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled,
\fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
\fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
\fBPR_FP_EXC_PRECISE\fP for precise exception mode.
.TP
.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Return floating-point exception mode,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
Set the state of the thread's "keep capabilities" flag,
which determines whether the threads's permitted
capability set is cleared when a change is made to the threads's user IDs
such that the threads's real UID, effective UID, and saved set-user-ID
all become nonzero when at least one of them previously had the value 0.
By default, the permitted capability set is cleared when such a change is made;
setting the "keep capabilities" flag prevents it from being cleared.
.I arg2
must be either 0 (permitted capabilities are cleared)
or 1 (permitted capabilities are kept).
(A thread's
.I effective
capability set is always cleared when such a credential change is made,
regardless of the setting of the "keep capabilities" flag.)
The "keep capabilities" value will be reset to 0 on subsequent calls to
.BR execve (2).
.TP
.BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
Return (as the function result) the current state of the calling threads's
"keep capabilities" flag.
.TP
.BR PR_SET_NAME " (since Linux 2.6.9)"
Set the process name for the calling process,
using the value in the location pointed to by
.IR "(char\ *) arg2" .
The name can be up to 16 bytes long,
.\" TASK_COMM_LEN in include/linux/sched.h
and should be null-terminated if it contains fewer bytes.
.TP
.BR PR_GET_NAME " (since Linux 2.6.11)"
Return the process name for the calling process,
in the buffer pointed to by
.IR "(char\ *) arg2" .
The buffer should allow space for up to 16 bytes;
the returned string will be null-terminated if it is shorter than that.
.TP
.BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
Set the parent process death signal
of the calling process to \fIarg2\fP (either a signal value
in the range 1..maxsig, or 0 to clear).
This is the signal that the calling process will get when its
parent dies.
This value is cleared for the child of a
.BR fork (2).
.TP
.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
Return the current value of the parent process death signal,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_SECCOMP " (since Linux 2.6.23)"
.\" See http://thread.gmane.org/gmane.linux.kernel/542632
.\" [PATCH 0 of 2] seccomp updates
.\" andrea-Vyt77T80VFVWk0Htik3J/w@public.gmane.org
Set the secure computing mode for the calling thread.
In the current implementation,
.IR arg2
must be 1.
After the secure computing mode has been set to 1,
the only system calls that the thread is permitted to make are
.BR read (2),
.BR write (2),
.BR _exit (2),
and
.BR sigreturn (2).
Other system calls result in the delivery of a
.BR SIGKILL
signal.
Secure computing mode is useful for number-crunching applications
that may need to execute untrusted byte code,
perhaps obtained by reading from a pipe or socket.
This operation is only available
if the kernel is configured with CONFIG_SECCOMP enabled.
.TP
.BR PR_GET_SECCOMP " (since Linux 2.6.23)"
Return the secure computing mode of the calling thread.
Not very useful for the current implementation (mode equals 1),
but may be useful for other possible future modes:
if the caller is not in secure computing mode, this operation returns 0;
if the caller is in secure computing mode, then the
.BR prctl ()
call will cause a
.B SIGKILL
signal to be sent to the process.
This operation is only available
if the kernel is configured with CONFIG_SECCOMP enabled.
.TP
.BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
Set the "securebits" flags of the calling thread to the value supplied in
.IR arg2 .
See
.BR capabilities (7).
.TP
.BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
Return (as the function result)
the "securebits" flags of the calling thread.
See
.BR capabilities (7).
.TP
.BR PR_SET_TIMING " (since Linux 2.6.0-test4)"
Set whether to use (normal, traditional) statistical process timing or
accurate timestamp-based process timing, by passing
.B PR_TIMING_STATISTICAL
.\" 0
or
.B PR_TIMING_TIMESTAMP
.\" 1
to \fIarg2\fP.
.B PR_TIMING_TIMESTAMP
is not currently implemented
(attempting to set this mode will yield the error
.BR EINVAL ).
.\" PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8,
.\" and looking at the patch history, it appears
.\" that it never did anything.
.TP
.BR PR_GET_TIMING " (since Linux 2.6.0-test4)"
Return (as the function result) which process timing method is currently
in use.
.TP
.BR PR_SET_TSC " (since Linux 2.6.26, x86 only)"
Set the state of the flag determining whether the timestamp counter
can be read by the process.
Pass
.B PR_TSC_ENABLE
to
.I arg2
to allow it to be read, or
.B PR_TSC_SIGSEGV
to generate a
.B SIGSEGV
when the process tries to read the timestamp counter.
.TP
.BR PR_GET_TSC " (since Linux 2.6.26, x86 only)"
Return the state of the flag determining whether the timestamp counter
can be read,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.B PR_SET_UNALIGN
(Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22)
Set unaligned access control bits to \fIarg2\fP.
Pass
\fBPR_UNALIGN_NOPRINT\fP to silently fix up unaligned user accesses,
or \fBPR_UNALIGN_SIGBUS\fP to generate
.B SIGBUS
on unaligned user access.
.TP
.B PR_GET_UNALIGN
(see
.B PR_SET_UNALIGN
for information on versions and architectures)
Return unaligned access control bits, in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_MCE_KILL " (since Linux 2.6.32)"
Set the machine check memory corruption kill policy for the current thread.
If
.I arg2
is
.BR PR_MCE_KILL_CLEAR ,
clear the thread memory corruption kill policy and use the system-wide default.
(The system-wide default is defined by
.IR /proc/sys/vm/memory_failure_early_kill ;
see
.BR proc (5).)
If
.I arg2
is
.BR PR_MCE_KILL_SET ,
use a thread-specific memory corruption kill policy.
In this case,
.I arg3
defines whether the policy is
.I early kill
.RB ( PR_MCE_KILL_EARLY ),
.I late kill
.RB ( PR_MCE_KILL_LATE ),
or the system-wide default
.RB ( PR_MCE_KILL_DEFAULT ).
Early kill means that the thread receives a
.B SIGBUS
signal as soon as hardware memory corruption is detected inside
its address space.
In late kill mode, the process is only killed when it accesses a corrupted page.
See
.BR sigaction (2)
for more information on the
.BR SIGBUS
signal.
The policy is inherited by children.
The remaining unused
.BR prctl ()
arguments must be zero for future compatibility.
.TP
.BR PR_MCE_KILL_GET " (since Linux 2.6.32)"
Return the current per-process machine check kill policy.
All unused
.BR prctl ()
arguments must be zero.
.TP
.BR PR_SET_MM " (since Linux 3.3)"
Modify certain kernel memory map descriptor fields
of the calling process.
Usually these fields are set by the kernel and dynamic loader (see
.BR ld.so (8)
for more information) and a regular application should not use this feature.
However, there are cases, such as self-modifying programs,
where a program might find it useful to change its own memory map.
This feature is available only if the kernel is built with the
.BR CONFIG_CHECKPOINT_RESTORE
option enabled.
The calling process must have the
.BR CAP_SYS_RESOURCE
capability.
The value in
.I arg2
is one of the options below, while
.I arg3
provides a new value for the option.
.RS
.TP
.BR PR_SET_MM_START_CODE
Set the address above which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or sharable (see
.BR mprotect (2)
and
.BR mmap (2)
for more information).
.TP
.BR PR_SET_MM_END_CODE
Set the address below which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or sharable.
.TP
.BR PR_SET_MM_START_DATA
Set the address above which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
but not executable or sharable.
.TP
.B PR_SET_MM_END_DATA
Set the address below which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
but not executable or sharable.
.TP
.BR PR_SET_MM_START_STACK
Set the start address of the stack.
The corresponding memory area must be readable and writable.
.TP
.BR PR_SET_MM_START_BRK
Set the address above which the program heap can be expanded with
.BR brk (2)
call.
The address must be greater than the ending address of
the current program data segment.
In addition, the combined size of the resulting heap and
the size of the data segment can't exceed the
.BR RLIMIT_DATA
resource limit (see
.BR setrlimit (2)).
.TP
.BR PR_SET_MM_BRK
Set the current
.BR brk (2)
value.
The requirements for the address are the same as for the
.BR PR_SET_MM_START_BRK
option.
.\" FIXME The following (until ========) is not yet in mainline kernel,
.\" so commented out for the moment.
.\" .TP
.\" .BR PR_SET_MM_ARG_START
.\" Set the address above which the program command line is placed.
.\" .TP
.\" .BR PR_SET_MM_ARG_END
.\" Set the address below which the program command line is placed.
.\" .TP
.\" .BR PR_SET_MM_ENV_START
.\" Set the address above which the program environment is placed.
.\" .TP
.\" .BR PR_SET_MM_ENV_END
.\" Set the address below which the program environment is placed.
.\" .IP
.\" The address passed with
.\" .BR PR_SET_MM_ARG_START ,
.\" .BR PR_SET_MM_ARG_END ,
.\" .BR PR_SET_MM_ENV_START ,
.\" and
.\" .BR PR_SET_MM_ENV_END
.\" should belong to a process stack area.
.\" Thus, the corresponding memory area must be readable, writable, and
.\" (depending on the kernel configuration) have the
.\" .BR MAP_GROWSDOWN
.\" attribute set (see
.\" .BR mmap (2)).
.\" .TP
.\" .BR PR_SET_MM_AUXV
.\" Set a new auxiliary vector.
.\" The
.\" .I arg3
.\" argument should provide the address of the vector.
.\" The
.\" .I arg4
.\" is the size of the vector.
.\" .TP
.\" .BR PR_SET_MM_EXE_FILE
.\" Supersede the
.\" .IR /proc/pid/exe
.\" symbolic link with a new one pointing to a new executable file
.\" identified by the file descriptor provided in
.\" .I arg3
.\" argument.
.\" The file descriptor should be obtained with a regular
.\" .BR open (2)
.\" call.
.\" .IP
.\" To change the symbolic link, one needs to unmap all existing
.\" executable memory areas, including those created by the kernel itself
.\" (for example the kernel usually creates at least one executable
.\" memory area for the ELF
.\" .IR \.text
.\" section).
.\" .IP
.\" The second limitation is that such transitions can be done only once
.\" in a process life time.
.\" Any further attempts will be rejected.
.\" This should help system administrators to monitor unusual
.\" symbolic-link transitions over all process running in a system.
.\" ========== END FIXME
.RE
.\"
.SH "RETURN VALUE"
On success,
.BR PR_GET_DUMPABLE ,
.BR PR_GET_KEEPCAPS ,
.BR PR_CAPBSET_READ ,
.BR PR_GET_TIMING ,
.BR PR_GET_SECUREBITS ,
.BR PR_MCE_KILL_GET ,
and (if it returns)
.BR PR_GET_SECCOMP
return the nonnegative values described above.
All other
.I option
values return 0 on success.
On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B EFAULT
.I arg2
is an invalid address.
.TP
.B EINVAL
The value of
.I option
is not recognized.
.TP
.B EINVAL
.I option
is
.BR PR_MCE_KILL
or
.BR PR_MCE_KILL_GET
or
.BR PR_SET_MM ,
and unused
.BR prctl ()
arguments were not specified as zero.
.TP
.B EINVAL
.I arg2
is not valid value for this
.IR option .
.TP
.B EINVAL
.I option
is
.BR PR_SET_SECCOMP
or
.BR PR_SET_SECCOMP ,
and the kernel was not configured with
.BR CONFIG_SECCOMP .
.TP
.B EINVAL
.I option
is
.BR PR_SET_MM ,
and one of the following is true
.RS
.IP * 3
.I arg4
or
.I arg5
is nonzero;
.IP *
.I arg3
is greater than
.B TASK_SIZE
(the limit on the size of the user address space for this architecture);
.IP *
.I arg2
is
.BR PR_SET_MM_START_CODE ,
.BR PR_SET_MM_END_CODE ,
.BR PR_SET_MM_START_DATA ,
.BR PR_SET_MM_END_DATA ,
or
.BR PR_SET_MM_START_STACK,
and the permissions of the corresponding memory area are not as required;
.IP *
.I arg2
is
.BR PR_SET_MM_START_BRK
or
.BR PR_SET_MM_BRK ,
and
.I arg3
is less than or equal to the end of the data segment
or specifies a value that would cause the
.B RLIMIT_DATA
resource limit to be exceeded.
.RE
.TP
.B EPERM
.I option
is
.BR PR_SET_SECUREBITS ,
and the caller does not have the
.B CAP_SETPCAP
capability,
or tried to unset a "locked" flag,
or tried to set a flag whose corresponding locked flag was set
(see
.BR capabilities (7)).
.TP
.B EPERM
.I option
is
.BR PR_SET_KEEPCAPS ,
and the callers's
.B SECURE_KEEP_CAPS_LOCKED
flag is set
(see
.BR capabilities (7)).
.TP
.B EPERM
.I option
is
.BR PR_CAPBSET_DROP ,
and the caller does not have the
.B CAP_SETPCAP
capability.
.TP
.B EPERM
.I option
is
.BR PR_SET_MM ,
and the caller does not have the
.B CAP_SYS_RESOURCE
capability.
.\" FIXME The following (until ========) is not yet in mainline kernel,
.\" so commented out for the moment.
.\" .TP
.\" .B EACCES
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" and
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" the file is not executable.
.\" .TP
.\" .B EBUSY
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" and this the second attempt to change the
.\" .I /proc/pid/exe
.\" symbolic link, which is prohibited.
.\" .TP
.\" .B EBADF
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" and the file descriptor passed in
.\" .I arg4
.\" is not valid.
.\" ========== END FIXME
.\" The following can't actually happen, because prctl() in
.\" seccomp mode will cause SIGKILL.
.\" .TP
.\" .B EPERM
.\" .I option
.\" is
.\" .BR PR_SET_SECCOMP ,
.\" and secure computing mode is already 1.
.SH VERSIONS
The
.BR prctl ()
system call was introduced in Linux 2.1.57.
.\" The library interface was added in glibc 2.0.6
.SH "CONFORMING TO"
This call is Linux-specific.
IRIX has a
.BR prctl ()
system call (also introduced in Linux 2.1.44
as irix_prctl on the MIPS architecture),
with prototype
.sp
.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 );
.sp
and options to get the maximum number of processes per user,
get the maximum number of processors the calling process can use,
find out whether a specified process is currently blocked,
get or set the maximum stack size, etc.
.SH "SEE ALSO"
.BR signal (2),
.BR core (5)

[-- Attachment #2: prctl.2 --]
[-- Type: application/octet-stream, Size: 21250 bytes --]

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 1998 Andries Brouwer (aeb@cwi.nl)
.\" and Copyright (C) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
.\" and Copyright Guillem Jover <guillem@hadrons.org>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified Thu Nov 11 04:19:42 MET 1999, aeb: added PR_GET_PDEATHSIG
.\" Modified 27 Jun 02, Michael Kerrisk
.\" 	Added PR_SET_DUMPABLE, PR_GET_DUMPABLE,
.\"	PR_SET_KEEPCAPS, PR_GET_KEEPCAPS
.\" Modified 2006-08-30 Guillem Jover <guillem@hadrons.org>
.\"	Updated Linux versions where the options where introduced.
.\"	Added PR_SET_TIMING, PR_GET_TIMING, PR_SET_NAME, PR_GET_NAME,
.\"	PR_SET_UNALIGN, PR_GET_UNALIGN, PR_SET_FPEMU, PR_GET_FPEMU,
.\"	PR_SET_FPEXC, PR_GET_FPEXC
.\" 2008-04-29 Serge Hallyn, Document PR_CAPBSET_READ and PR_CAPBSET_DROP
.\" 2008-06-13 Erik Bosman, <ejbosman@cs.vu.nl>
.\"     Document PR_GET_TSC and PR_SET_TSC.
.\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP
.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL_*
.\"
.\" FIXME: Document PR_SET_TIMERSLACK and PR_GET_TIMERSLACK (new in 2.6.28)
.\" FIXME: Document PR_TASK_PERF_EVENTS_DISABLE and
.\"        PR_TASK_PERF_EVENTS_ENABLE (new in 2.6.32)
.\"
.TH PRCTL 2 2012-04-14 "Linux" "Linux Programmer's Manual"
.SH NAME
prctl \- operations on a process
.SH SYNOPSIS
.nf
.B #include <sys/prctl.h>
.sp
.BI "int prctl(int " option ", unsigned long " arg2 ", unsigned long " arg3 ,
.BI "          unsigned long " arg4 ", unsigned long " arg5 );
.fi
.SH DESCRIPTION
.BR prctl ()
is called with a first argument describing what to do
(with values defined in \fI<linux/prctl.h>\fP), and further
arguments with a significance depending on the first one.
The first argument can be:
.TP
.BR PR_CAPBSET_READ " (since Linux 2.6.25)"
Return (as the function result) 1 if the capability specified in
.I arg2
is in the calling thread's capability bounding set,
or 0 if it is not.
(The capability constants are defined in
.IR <linux/capability.h> .)
The capability bounding set dictates
whether the process can receive the capability through a
file's permitted capability set on a subsequent call to
.BR execve (2).

If the capability specified in
.I arg2
is not valid, then the call fails with the error
.BR EINVAL .
.TP
.BR PR_CAPBSET_DROP " (since Linux 2.6.25)"
If the calling thread has the
.B CAP_SETPCAP
capability, then drop the capability specified by
.I arg2
from the calling thread's capability bounding set.
Any children of the calling thread will inherit the newly
reduced bounding set.

The call fails with the error:
.B EPERM
if the calling thread does not have the
.BR CAP_SETPCAP ;
.BR EINVAL
if
.I arg2
does not represent a valid capability; or
.BR EINVAL
if file capabilities are not enabled in the kernel,
in which case bounding sets are not supported.
.TP
.BR PR_SET_DUMPABLE " (since Linux 2.3.20)"
Set the state of the flag determining whether core dumps are produced
for this process upon delivery of a signal whose default behavior is
to produce a core dump.
(Normally this flag is set for a process by default, but it is cleared
when a set-user-ID or set-group-ID program is executed and also by
various system calls that manipulate process UIDs and GIDs).
In kernels up to and including 2.6.12,
.I arg2
must be either 0 (process is not dumpable) or 1 (process is dumpable).
Between kernels 2.6.13 and 2.6.17, the value 2 was also permitted,
which caused any binary which normally would not be dumped
to be dumped readable by root only;
for security reasons, this feature has been removed.
.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=115270289030630&w=2
.\" Subject:    Fix prctl privilege escalation (CVE-2006-2451)
.\" From:       Marcel Holtmann <marcel () holtmann ! org>
.\" Date:       2006-07-12 11:12:00
(See also the description of
.I /proc/sys/fs/suid_dumpable
in
.BR proc (5).)
Processes that are not dumpable can not be attached via
.BR ptrace(2)
.BR PTRACE_ATTACH .
.TP
.BR PR_GET_DUMPABLE " (since Linux 2.3.20)"
Return (as the function result) the current state of the calling
process's dumpable flag.
.\" Since Linux 2.6.13, the dumpable flag can have the value 2,
.\" but in 2.6.13 PR_GET_DUMPABLE simply returns 1 if the dumpable
.\" flags has a nonzero value.  This was fixed in 2.6.14.
.TP
.BR PR_SET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Set the endian-ness of the calling process to the value given
in \fIarg2\fP, which should be one of the following:
.\" Respectively 0, 1, 2
.BR PR_ENDIAN_BIG ,
.BR PR_ENDIAN_LITTLE ,
or
.B PR_ENDIAN_PPC_LITTLE
(PowerPC pseudo little endian).
.TP
.BR PR_GET_ENDIAN " (since Linux 2.6.18, PowerPC only)"
Return the endian-ness of the calling process,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Set floating-point emulation control bits to \fIarg2\fP.
Pass \fBPR_FPEMU_NOPRINT\fP to silently emulate fp operations accesses, or
\fBPR_FPEMU_SIGFPE\fP to not emulate fp operations and send
.B SIGFPE
instead.
.TP
.BR PR_GET_FPEMU " (since Linux 2.4.18, 2.5.9, only on ia64)"
Return floating-point emulation control bits,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Set floating-point exception mode to \fIarg2\fP.
Pass \fBPR_FP_EXC_SW_ENABLE\fP to use FPEXC for FP exception enables,
\fBPR_FP_EXC_DIV\fP for floating-point divide by zero,
\fBPR_FP_EXC_OVF\fP for floating-point overflow,
\fBPR_FP_EXC_UND\fP for floating-point underflow,
\fBPR_FP_EXC_RES\fP for floating-point inexact result,
\fBPR_FP_EXC_INV\fP for floating-point invalid operation,
\fBPR_FP_EXC_DISABLED\fP for FP exceptions disabled,
\fBPR_FP_EXC_NONRECOV\fP for async nonrecoverable exception mode,
\fBPR_FP_EXC_ASYNC\fP for async recoverable exception mode,
\fBPR_FP_EXC_PRECISE\fP for precise exception mode.
.TP
.BR PR_GET_FPEXC " (since Linux 2.4.21, 2.5.32, only on PowerPC)"
Return floating-point exception mode,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_KEEPCAPS " (since Linux 2.2.18)"
Set the state of the thread's "keep capabilities" flag,
which determines whether the threads's permitted
capability set is cleared when a change is made to the threads's user IDs
such that the threads's real UID, effective UID, and saved set-user-ID
all become nonzero when at least one of them previously had the value 0.
By default, the permitted capability set is cleared when such a change is made;
setting the "keep capabilities" flag prevents it from being cleared.
.I arg2
must be either 0 (permitted capabilities are cleared)
or 1 (permitted capabilities are kept).
(A thread's
.I effective
capability set is always cleared when such a credential change is made,
regardless of the setting of the "keep capabilities" flag.)
The "keep capabilities" value will be reset to 0 on subsequent calls to
.BR execve (2).
.TP
.BR PR_GET_KEEPCAPS " (since Linux 2.2.18)"
Return (as the function result) the current state of the calling threads's
"keep capabilities" flag.
.TP
.BR PR_SET_NAME " (since Linux 2.6.9)"
Set the process name for the calling process,
using the value in the location pointed to by
.IR "(char\ *) arg2" .
The name can be up to 16 bytes long,
.\" TASK_COMM_LEN in include/linux/sched.h
and should be null-terminated if it contains fewer bytes.
.TP
.BR PR_GET_NAME " (since Linux 2.6.11)"
Return the process name for the calling process,
in the buffer pointed to by
.IR "(char\ *) arg2" .
The buffer should allow space for up to 16 bytes;
the returned string will be null-terminated if it is shorter than that.
.TP
.BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
Set the parent process death signal
of the calling process to \fIarg2\fP (either a signal value
in the range 1..maxsig, or 0 to clear).
This is the signal that the calling process will get when its
parent dies.
This value is cleared for the child of a
.BR fork (2).
.TP
.BR PR_GET_PDEATHSIG " (since Linux 2.3.15)"
Return the current value of the parent process death signal,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_SET_SECCOMP " (since Linux 2.6.23)"
.\" See http://thread.gmane.org/gmane.linux.kernel/542632
.\" [PATCH 0 of 2] seccomp updates
.\" andrea@cpushare.com
Set the secure computing mode for the calling thread.
In the current implementation,
.IR arg2
must be 1.
After the secure computing mode has been set to 1,
the only system calls that the thread is permitted to make are
.BR read (2),
.BR write (2),
.BR _exit (2),
and
.BR sigreturn (2).
Other system calls result in the delivery of a
.BR SIGKILL
signal.
Secure computing mode is useful for number-crunching applications
that may need to execute untrusted byte code,
perhaps obtained by reading from a pipe or socket.
This operation is only available
if the kernel is configured with CONFIG_SECCOMP enabled.
.TP
.BR PR_GET_SECCOMP " (since Linux 2.6.23)"
Return the secure computing mode of the calling thread.
Not very useful for the current implementation (mode equals 1),
but may be useful for other possible future modes:
if the caller is not in secure computing mode, this operation returns 0;
if the caller is in secure computing mode, then the
.BR prctl ()
call will cause a
.B SIGKILL
signal to be sent to the process.
This operation is only available
if the kernel is configured with CONFIG_SECCOMP enabled.
.TP
.BR PR_SET_SECUREBITS " (since Linux 2.6.26)"
Set the "securebits" flags of the calling thread to the value supplied in
.IR arg2 .
See
.BR capabilities (7).
.TP
.BR PR_GET_SECUREBITS " (since Linux 2.6.26)"
Return (as the function result)
the "securebits" flags of the calling thread.
See
.BR capabilities (7).
.TP
.BR PR_SET_TIMING " (since Linux 2.6.0-test4)"
Set whether to use (normal, traditional) statistical process timing or
accurate timestamp-based process timing, by passing
.B PR_TIMING_STATISTICAL
.\" 0
or
.B PR_TIMING_TIMESTAMP
.\" 1
to \fIarg2\fP.
.B PR_TIMING_TIMESTAMP
is not currently implemented
(attempting to set this mode will yield the error
.BR EINVAL ).
.\" PR_TIMING_TIMESTAMP doesn't do anything in 2.6.26-rc8,
.\" and looking at the patch history, it appears
.\" that it never did anything.
.TP
.BR PR_GET_TIMING " (since Linux 2.6.0-test4)"
Return (as the function result) which process timing method is currently
in use.
.TP
.BR PR_SET_TSC " (since Linux 2.6.26, x86 only)"
Set the state of the flag determining whether the timestamp counter
can be read by the process.
Pass
.B PR_TSC_ENABLE
to
.I arg2
to allow it to be read, or
.B PR_TSC_SIGSEGV
to generate a
.B SIGSEGV
when the process tries to read the timestamp counter.
.TP
.BR PR_GET_TSC " (since Linux 2.6.26, x86 only)"
Return the state of the flag determining whether the timestamp counter
can be read,
in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.B PR_SET_UNALIGN
(Only on: ia64, since Linux 2.3.48; parisc, since Linux 2.6.15;
PowerPC, since Linux 2.6.18; Alpha, since Linux 2.6.22)
Set unaligned access control bits to \fIarg2\fP.
Pass
\fBPR_UNALIGN_NOPRINT\fP to silently fix up unaligned user accesses,
or \fBPR_UNALIGN_SIGBUS\fP to generate
.B SIGBUS
on unaligned user access.
.TP
.B PR_GET_UNALIGN
(see
.B PR_SET_UNALIGN
for information on versions and architectures)
Return unaligned access control bits, in the location pointed to by
.IR "(int\ *) arg2" .
.TP
.BR PR_MCE_KILL " (since Linux 2.6.32)"
Set the machine check memory corruption kill policy for the current thread.
If
.I arg2
is
.BR PR_MCE_KILL_CLEAR ,
clear the thread memory corruption kill policy and use the system-wide default.
(The system-wide default is defined by
.IR /proc/sys/vm/memory_failure_early_kill ;
see
.BR proc (5).)
If
.I arg2
is
.BR PR_MCE_KILL_SET ,
use a thread-specific memory corruption kill policy.
In this case,
.I arg3
defines whether the policy is
.I early kill
.RB ( PR_MCE_KILL_EARLY ),
.I late kill
.RB ( PR_MCE_KILL_LATE ),
or the system-wide default
.RB ( PR_MCE_KILL_DEFAULT ).
Early kill means that the thread receives a
.B SIGBUS
signal as soon as hardware memory corruption is detected inside
its address space.
In late kill mode, the process is only killed when it accesses a corrupted page.
See
.BR sigaction (2)
for more information on the
.BR SIGBUS
signal.
The policy is inherited by children.
The remaining unused
.BR prctl ()
arguments must be zero for future compatibility.
.TP
.BR PR_MCE_KILL_GET " (since Linux 2.6.32)"
Return the current per-process machine check kill policy.
All unused
.BR prctl ()
arguments must be zero.
.TP
.BR PR_SET_MM " (since Linux 3.3)"
Modify certain kernel memory map descriptor fields
of the calling process.
Usually these fields are set by the kernel and dynamic loader (see
.BR ld.so (8)
for more information) and a regular application should not use this feature.
However, there are cases, such as self-modifying programs,
where a program might find it useful to change its own memory map.
This feature is available only if the kernel is built with the 
.BR CONFIG_CHECKPOINT_RESTORE
option enabled.
The calling process must have the
.BR CAP_SYS_RESOURCE
capability.
The value in
.I arg2
is one of the options below, while
.I arg3
provides a new value for the option.
.RS
.TP
.BR PR_SET_MM_START_CODE
Set the address above which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or sharable (see
.BR mprotect (2)
and
.BR mmap (2)
for more information).
.TP
.BR PR_SET_MM_END_CODE
Set the address below which the program text can run.
The corresponding memory area must be readable and executable,
but not writable or sharable.
.TP
.BR PR_SET_MM_START_DATA
Set the address above which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
but not executable or sharable.
.TP
.B PR_SET_MM_END_DATA
Set the address below which initialized and
uninitialized (bss) data are placed.
The corresponding memory area must be readable and writable,
but not executable or sharable.
.TP
.BR PR_SET_MM_START_STACK
Set the start address of the stack.
The corresponding memory area must be readable and writable.
.TP
.BR PR_SET_MM_START_BRK
Set the address above which the program heap can be expanded with
.BR brk (2)
call.
The address must be greater than the ending address of
the current program data segment.
In addition, the combined size of the resulting heap and
the size of the data segment can't exceed the
.BR RLIMIT_DATA
resource limit (see
.BR setrlimit (2)).
.TP
.BR PR_SET_MM_BRK
Set the current
.BR brk (2)
value.
The requirements for the address are the same as for the
.BR PR_SET_MM_START_BRK
option.
.\" FIXME The following (until ========) is not yet in mainline kernel,
.\" so commented out for the moment.
.\" .TP
.\" .BR PR_SET_MM_ARG_START
.\" Set the address above which the program command line is placed.
.\" .TP
.\" .BR PR_SET_MM_ARG_END
.\" Set the address below which the program command line is placed.
.\" .TP
.\" .BR PR_SET_MM_ENV_START
.\" Set the address above which the program environment is placed.
.\" .TP
.\" .BR PR_SET_MM_ENV_END
.\" Set the address below which the program environment is placed.
.\" .IP
.\" The address passed with
.\" .BR PR_SET_MM_ARG_START ,
.\" .BR PR_SET_MM_ARG_END ,
.\" .BR PR_SET_MM_ENV_START ,
.\" and
.\" .BR PR_SET_MM_ENV_END
.\" should belong to a process stack area.
.\" Thus, the corresponding memory area must be readable, writable, and
.\" (depending on the kernel configuration) have the
.\" .BR MAP_GROWSDOWN
.\" attribute set (see
.\" .BR mmap (2)).
.\" .TP
.\" .BR PR_SET_MM_AUXV
.\" Set a new auxiliary vector.
.\" The
.\" .I arg3
.\" argument should provide the address of the vector.
.\" The
.\" .I arg4
.\" is the size of the vector.
.\" .TP
.\" .BR PR_SET_MM_EXE_FILE
.\" Supersede the
.\" .IR /proc/pid/exe
.\" symbolic link with a new one pointing to a new executable file
.\" identified by the file descriptor provided in
.\" .I arg3
.\" argument.
.\" The file descriptor should be obtained with a regular
.\" .BR open (2)
.\" call.
.\" .IP
.\" To change the symbolic link, one needs to unmap all existing
.\" executable memory areas, including those created by the kernel itself
.\" (for example the kernel usually creates at least one executable
.\" memory area for the ELF
.\" .IR \.text
.\" section).
.\" .IP
.\" The second limitation is that such transitions can be done only once
.\" in a process life time.
.\" Any further attempts will be rejected.
.\" This should help system administrators to monitor unusual
.\" symbolic-link transitions over all process running in a system.
.\" ========== END FIXME
.RE
.\"
.SH "RETURN VALUE"
On success,
.BR PR_GET_DUMPABLE ,
.BR PR_GET_KEEPCAPS ,
.BR PR_CAPBSET_READ ,
.BR PR_GET_TIMING ,
.BR PR_GET_SECUREBITS ,
.BR PR_MCE_KILL_GET ,
and (if it returns)
.BR PR_GET_SECCOMP
return the nonnegative values described above.
All other
.I option
values return 0 on success.
On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B EFAULT
.I arg2
is an invalid address.
.TP
.B EINVAL
The value of
.I option
is not recognized.
.TP
.B EINVAL
.I option
is
.BR PR_MCE_KILL
or
.BR PR_MCE_KILL_GET
or
.BR PR_SET_MM ,
and unused
.BR prctl ()
arguments were not specified as zero.
.TP
.B EINVAL
.I arg2
is not valid value for this
.IR option .
.TP
.B EINVAL
.I option
is
.BR PR_SET_SECCOMP
or
.BR PR_SET_SECCOMP ,
and the kernel was not configured with
.BR CONFIG_SECCOMP .
.TP
.B EINVAL
.I option
is
.BR PR_SET_MM ,
and one of the following is true
.RS
.IP * 3
.I arg4
or
.I arg5
is nonzero;
.IP *
.I arg3
is greater than
.B TASK_SIZE
(the limit on the size of the user address space for this architecture);
.IP *
.I arg2
is
.BR PR_SET_MM_START_CODE ,
.BR PR_SET_MM_END_CODE ,
.BR PR_SET_MM_START_DATA ,
.BR PR_SET_MM_END_DATA ,
or
.BR PR_SET_MM_START_STACK,
and the permissions of the corresponding memory area are not as required;
.IP *
.I arg2
is
.BR PR_SET_MM_START_BRK
or
.BR PR_SET_MM_BRK ,
and
.I arg3
is less than or equal to the end of the data segment
or specifies a value that would cause the
.B RLIMIT_DATA
resource limit to be exceeded.
.RE
.TP
.B EPERM
.I option
is
.BR PR_SET_SECUREBITS ,
and the caller does not have the
.B CAP_SETPCAP
capability,
or tried to unset a "locked" flag,
or tried to set a flag whose corresponding locked flag was set
(see
.BR capabilities (7)).
.TP
.B EPERM
.I option
is
.BR PR_SET_KEEPCAPS ,
and the callers's
.B SECURE_KEEP_CAPS_LOCKED
flag is set
(see
.BR capabilities (7)).
.TP
.B EPERM
.I option
is
.BR PR_CAPBSET_DROP ,
and the caller does not have the
.B CAP_SETPCAP
capability.
.TP
.B EPERM
.I option
is
.BR PR_SET_MM ,
and the caller does not have the
.B CAP_SYS_RESOURCE
capability.
.\" FIXME The following (until ========) is not yet in mainline kernel,
.\" so commented out for the moment.
.\" .TP
.\" .B EACCES
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" and
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" the file is not executable.
.\" .TP
.\" .B EBUSY
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" and this the second attempt to change the
.\" .I /proc/pid/exe
.\" symbolic link, which is prohibited.
.\" .TP
.\" .B EBADF
.\" .I option
.\" is
.\" .BR PR_SET_MM ,
.\" .I arg3
.\" is
.\" .BR PR_SET_MM_EXE_FILE ,
.\" and the file descriptor passed in
.\" .I arg4
.\" is not valid.
.\" ========== END FIXME
.\" The following can't actually happen, because prctl() in
.\" seccomp mode will cause SIGKILL.
.\" .TP
.\" .B EPERM
.\" .I option
.\" is
.\" .BR PR_SET_SECCOMP ,
.\" and secure computing mode is already 1.
.SH VERSIONS
The
.BR prctl ()
system call was introduced in Linux 2.1.57.
.\" The library interface was added in glibc 2.0.6
.SH "CONFORMING TO"
This call is Linux-specific.
IRIX has a
.BR prctl ()
system call (also introduced in Linux 2.1.44
as irix_prctl on the MIPS architecture),
with prototype
.sp
.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 );
.sp
and options to get the maximum number of processes per user,
get the maximum number of processors the calling process can use,
find out whether a specified process is currently blocked,
get or set the maximum stack size, etc.
.SH "SEE ALSO"
.BR signal (2),
.BR core (5)

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Mon, Apr 16, 2012 at 10:34:53AM +1200, Michael Kerrisk (man-pages) wrote:
> Hi Cyrill,
> 
> Below (and also attached) is the current draft of the prctl.2 page
> with your PR_SET_MM materials.
> 

Hi Michael, looks good to me, thanks!

	Cyrill

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Cyrill Gorcunov]

On Mon, Apr 16, 2012 at 10:34:53AM +1200, Michael Kerrisk (man-pages) wrote:
> Hi Cyrill,
> 
> Below (and also attached) is the current draft of the prctl.2 page
> with your PR_SET_MM materials.
> 

Hi Michael, looks good to me, thanks!

	Cyrill
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

On Mon, Apr 16, 2012 at 6:13 PM, Cyrill Gorcunov <gorcunov@openvz.org> wrote:
> On Mon, Apr 16, 2012 at 10:34:53AM +1200, Michael Kerrisk (man-pages) wrote:
>> Hi Cyrill,
>>
>> Below (and also attached) is the current draft of the prctl.2 page
>> with your PR_SET_MM materials.
>>
>
> Hi Michael, looks good to me, thanks!

Okay -- merged for man-pages-3.39.

Thanks for your contribution!

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/

Re: [PATCH 1/2] prctl.2: Add PR_SET_MM option description

[Michael Kerrisk (man-pages)]

On Mon, Apr 16, 2012 at 6:13 PM, Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org> wrote:
> On Mon, Apr 16, 2012 at 10:34:53AM +1200, Michael Kerrisk (man-pages) wrote:
>> Hi Cyrill,
>>
>> Below (and also attached) is the current draft of the prctl.2 page
>> with your PR_SET_MM materials.
>>
>
> Hi Michael, looks good to me, thanks!

Okay -- merged for man-pages-3.39.

Thanks for your contribution!

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/2] Add kcmp.2 manpage

[Cyrill Gorcunov]

NAME
       kcmp - compare if two processes do share a particular kernel resource

SYNOPSIS
       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>
       #include <linux/kcmp.h>
       #include <sys/syscall.h>   /* For SYS_xxx definitions */

       int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);

DESCRIPTION
       kcmp() allows to find out if two processes identified by pid1 and pid2
       share kernel resources such as virtual memory, file descriptors, file system etc.

       The comparison type is one of the following

       KCMP_FILE determines whether a file descriptor idx1 in the first process
       is the same as another descriptor idx2 in the second process

       KCMP_VM compares whether processes share address space

       KCMP_FILES compares the file descriptor arrays to see whether the processes
       share all files

       KCMP_FS compares whether processes share the file system information (the current
       umask, working directory, namespace root, etc)

       KCMP_SIGHAND compares whether processes share a signal handlers table

       KCMP_IO compares whether processes do share I/O context, used mainly for
       block I/O scheduling

       KCMP_SYSVSEM compares the list of undo operations associated with SYSV semaphores

RETURN VALUE
       kcmp was designed to return values suitable for sorting.  This is particularly handy
       when one have to compare a large number of file descriptors.

       The return value is merely a result of simple arithmetic comparison of kernel pointers
       (when kernel compares resources, it uses their memory addresses).

       The  easiest way to explain is to consider an example.  Lets say v1 and v2 are the
       addresses of appropriate resources, then the return value is one of the following

       0 - v1 is equal to v2 , in other words we have a shared resource here
       1 - v1 is less than v2
       2 - v1 is greater than v2
       3 - v1 is not equal to but ordering information is unavailble.

       On error, -1 is returned, and errno is set appropriately.

Signed-off-by: Cyrill Gorcunov <gorcunov@openvz.org>
CC: "Eric W. Biederman" <ebiederm@xmission.com>
CC: "H. Peter Anvin" <hpa@zytor.com>
CC: Pavel Emelyanov <xemul@parallels.com>
---
 man2/kcmp.2 |  107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 107 insertions(+), 0 deletions(-)
 create mode 100644 man2/kcmp.2

diff --git a/man2/kcmp.2 b/man2/kcmp.2
new file mode 100644
index 0000000..73b89cf
--- /dev/null
+++ b/man2/kcmp.2
@@ -0,0 +1,107 @@
+.TH KCMP 2 2012-02-01 "Linux" "Linux Programmer's Manual"
+
+.SH NAME
+kcmp \- compare if two processes do share a particular kernel resource
+
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <unistd.h>
+.B #include <linux/kcmp.h>
+.BR "#include <sys/syscall.h>   "  "/* For SYS_xxx definitions */"
+
+.BI "int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);"
+.fi
+
+.SH DESCRIPTION
+
+.BR kcmp ()
+allows to find out if two processes identified by
+.I pid1
+and
+.I pid2
+share kernel resources such as virtual memory,
+file descriptors, file system etc.
+
+The comparison
+.I type
+is one of the following
+
+.BR KCMP_FILE
+determines whether a file descriptor
+.I idx1
+in the first process is the same as another descriptor
+.I idx2
+in the second process
+
+.BR KCMP_VM
+compares whether processes share address space
+
+.BR KCMP_FILES
+compares the file descriptor arrays to see whether the processes share all files
+
+.BR KCMP_FS
+compares whether processes share the file system information (the current umask,
+working directory, namespace root, etc)
+
+.BR KCMP_SIGHAND
+compares whether processes share a signal handlers table
+
+.BR KCMP_IO
+compares whether processes do share I/O context,
+used mainly for block I/O scheduling
+
+.BR KCMP_SYSVSEM
+compares the list of undo operations associated with SYSV semaphores
+
+.SH "RETURN VALUE"
+.B kcmp
+was designed to return values suitable for sorting.
+This is particularly handy when one have to compare
+a large number of file descriptors.
+
+The return value is merely a result of simple arithmetic comparison
+of kernel pointers (when kernel compares resources, it uses their
+memory addresses).
+
+The easiest way to explain is to consider an example.
+Lets say
+.I v1
+and
+.I v2
+are the addresses of appropriate resources, then the return value
+is one of the following
+
+.B 0
+\-
+.I v1
+is equal to
+.I v2
+, in other words we have a shared resource here
+
+.B 1
+\-
+.I v1
+is less than
+.I v2
+
+.B 2
+\-
+.I v1
+is greater than
+.I v2
+
+.B 3
+\-
+.I v1
+is not equal to
+.I v2
+, but ordering information is unavailble.
+
+On error, \-1 is returned, and errno is set appropriately.
+
+.SH "CONFORMING TO"
+.BR kcmp ()
+is Linux specific and should not be used in programs intended to be portable.
+.SH "SEE ALSO"
+.BR clone (2)
-- 
1.7.7.6

[PATCH 2/2] Add kcmp.2 manpage

[Cyrill Gorcunov]

NAME
       kcmp - compare if two processes do share a particular kernel resource

SYNOPSIS
       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>
       #include <linux/kcmp.h>
       #include <sys/syscall.h>   /* For SYS_xxx definitions */

       int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);

DESCRIPTION
       kcmp() allows to find out if two processes identified by pid1 and pid2
       share kernel resources such as virtual memory, file descriptors, file system etc.

       The comparison type is one of the following

       KCMP_FILE determines whether a file descriptor idx1 in the first process
       is the same as another descriptor idx2 in the second process

       KCMP_VM compares whether processes share address space

       KCMP_FILES compares the file descriptor arrays to see whether the processes
       share all files

       KCMP_FS compares whether processes share the file system information (the current
       umask, working directory, namespace root, etc)

       KCMP_SIGHAND compares whether processes share a signal handlers table

       KCMP_IO compares whether processes do share I/O context, used mainly for
       block I/O scheduling

       KCMP_SYSVSEM compares the list of undo operations associated with SYSV semaphores

RETURN VALUE
       kcmp was designed to return values suitable for sorting.  This is particularly handy
       when one have to compare a large number of file descriptors.

       The return value is merely a result of simple arithmetic comparison of kernel pointers
       (when kernel compares resources, it uses their memory addresses).

       The  easiest way to explain is to consider an example.  Lets say v1 and v2 are the
       addresses of appropriate resources, then the return value is one of the following

       0 - v1 is equal to v2 , in other words we have a shared resource here
       1 - v1 is less than v2
       2 - v1 is greater than v2
       3 - v1 is not equal to but ordering information is unavailble.

       On error, -1 is returned, and errno is set appropriately.

Signed-off-by: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
CC: "Eric W. Biederman" <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
CC: "H. Peter Anvin" <hpa-YMNOUZJC4hwAvxtiuMwx3w@public.gmane.org>
CC: Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org>
---
 man2/kcmp.2 |  107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 107 insertions(+), 0 deletions(-)
 create mode 100644 man2/kcmp.2

diff --git a/man2/kcmp.2 b/man2/kcmp.2
new file mode 100644
index 0000000..73b89cf
--- /dev/null
+++ b/man2/kcmp.2
@@ -0,0 +1,107 @@
+.TH KCMP 2 2012-02-01 "Linux" "Linux Programmer's Manual"
+
+.SH NAME
+kcmp \- compare if two processes do share a particular kernel resource
+
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <unistd.h>
+.B #include <linux/kcmp.h>
+.BR "#include <sys/syscall.h>   "  "/* For SYS_xxx definitions */"
+
+.BI "int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);"
+.fi
+
+.SH DESCRIPTION
+
+.BR kcmp ()
+allows to find out if two processes identified by
+.I pid1
+and
+.I pid2
+share kernel resources such as virtual memory,
+file descriptors, file system etc.
+
+The comparison
+.I type
+is one of the following
+
+.BR KCMP_FILE
+determines whether a file descriptor
+.I idx1
+in the first process is the same as another descriptor
+.I idx2
+in the second process
+
+.BR KCMP_VM
+compares whether processes share address space
+
+.BR KCMP_FILES
+compares the file descriptor arrays to see whether the processes share all files
+
+.BR KCMP_FS
+compares whether processes share the file system information (the current umask,
+working directory, namespace root, etc)
+
+.BR KCMP_SIGHAND
+compares whether processes share a signal handlers table
+
+.BR KCMP_IO
+compares whether processes do share I/O context,
+used mainly for block I/O scheduling
+
+.BR KCMP_SYSVSEM
+compares the list of undo operations associated with SYSV semaphores
+
+.SH "RETURN VALUE"
+.B kcmp
+was designed to return values suitable for sorting.
+This is particularly handy when one have to compare
+a large number of file descriptors.
+
+The return value is merely a result of simple arithmetic comparison
+of kernel pointers (when kernel compares resources, it uses their
+memory addresses).
+
+The easiest way to explain is to consider an example.
+Lets say
+.I v1
+and
+.I v2
+are the addresses of appropriate resources, then the return value
+is one of the following
+
+.B 0
+\-
+.I v1
+is equal to
+.I v2
+, in other words we have a shared resource here
+
+.B 1
+\-
+.I v1
+is less than
+.I v2
+
+.B 2
+\-
+.I v1
+is greater than
+.I v2
+
+.B 3
+\-
+.I v1
+is not equal to
+.I v2
+, but ordering information is unavailble.
+
+On error, \-1 is returned, and errno is set appropriately.
+
+.SH "CONFORMING TO"
+.BR kcmp ()
+is Linux specific and should not be used in programs intended to be portable.
+.SH "SEE ALSO"
+.BR clone (2)
-- 
1.7.7.6

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] Add kcmp.2 manpage

[H. Peter Anvin]

On 03/09/2012 12:47 PM, Cyrill Gorcunov wrote:
> +.I v2
> +, but ordering information is unavailble.

Needs to be:

.IR v2 ,

... and fix the typo in "unavailable".

	-hpa


-- 
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.

Re: [PATCH 2/2] Add kcmp.2 manpage

[H. Peter Anvin]

On 03/09/2012 12:47 PM, Cyrill Gorcunov wrote:
> +.I v2
> +, but ordering information is unavailble.

Needs to be:

.IR v2 ,

... and fix the typo in "unavailable".

	-hpa


-- 
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] Add kcmp.2 manpage

[Cyrill Gorcunov]

On Fri, Mar 09, 2012 at 12:50:17PM -0800, H. Peter Anvin wrote:
> On 03/09/2012 12:47 PM, Cyrill Gorcunov wrote:
> > +.I v2
> > +, but ordering information is unavailble.
> 
> Needs to be:
> 
> .IR v2 ,
> 
> ... and fix the typo in "unavailable".
> 

here we go

	Cyrill
---
From: Cyrill Gorcunov <gorcunov@openvz.org>
Date: Sat, 10 Mar 2012 01:03:00 +0400
Subject: [PATCH] Add kcmp.2 manpage

NAME
       kcmp - compare if two processes do share a particular kernel resource

SYNOPSIS
       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>
       #include <linux/kcmp.h>
       #include <sys/syscall.h>   /* For SYS_xxx definitions */

       int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);

DESCRIPTION
       kcmp() allows to find out if two processes identified by pid1 and pid2
       share kernel resources such as virtual memory, file descriptors, file system etc.

       The comparison type is one of the following

       KCMP_FILE determines whether a file descriptor idx1 in the first process
       is the same as another descriptor idx2 in the second process

       KCMP_VM compares whether processes share address space

       KCMP_FILES compares the file descriptor arrays to see whether the processes
       share all files

       KCMP_FS compares whether processes share the file system information (the current
       umask, working directory, namespace root, etc)

       KCMP_SIGHAND compares whether processes share a signal handlers table

       KCMP_IO compares whether processes do share I/O context, used mainly for
       block I/O scheduling

       KCMP_SYSVSEM compares the list of undo operations associated with SYSV semaphores

RETURN VALUE
       kcmp was designed to return values suitable for sorting.  This is particularly handy
       when one have to compare a large number of file descriptors.

       The return value is merely a result of simple arithmetic comparison of kernel pointers
       (when kernel compares resources, it uses their memory addresses).

       The  easiest way to explain is to consider an example.  Lets say v1 and v2 are the
       addresses of appropriate resources, then the return value is one of the following

       0 - v1 is equal to v2 , in other words we have a shared resource here
       1 - v1 is less than v2
       2 - v1 is greater than v2
       3 - v1 is not equal to but ordering information is unavailable.

       On error, -1 is returned, and errno is set appropriately.

Signed-off-by: Cyrill Gorcunov <gorcunov@openvz.org>
CC: "Eric W. Biederman" <ebiederm@xmission.com>
CC: "H. Peter Anvin" <hpa@zytor.com>
CC: Pavel Emelyanov <xemul@parallels.com>
---
 man2/kcmp.2 |  107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 107 insertions(+), 0 deletions(-)
 create mode 100644 man2/kcmp.2

diff --git a/man2/kcmp.2 b/man2/kcmp.2
new file mode 100644
index 0000000..a8615f1
--- /dev/null
+++ b/man2/kcmp.2
@@ -0,0 +1,107 @@
+.TH KCMP 2 2012-02-01 "Linux" "Linux Programmer's Manual"
+
+.SH NAME
+kcmp \- compare if two processes do share a particular kernel resource
+
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <unistd.h>
+.B #include <linux/kcmp.h>
+.BR "#include <sys/syscall.h>   "  "/* For SYS_xxx definitions */"
+
+.BI "int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);"
+.fi
+
+.SH DESCRIPTION
+
+.BR kcmp ()
+allows to find out if two processes identified by
+.IR pid1
+and
+.IR pid2
+share kernel resources such as virtual memory,
+file descriptors, file system etc.
+
+The comparison
+.IR type
+is one of the following
+
+.BR KCMP_FILE
+determines whether a file descriptor
+.IR idx1
+in the first process is the same as another descriptor
+.IR idx2
+in the second process
+
+.BR KCMP_VM
+compares whether processes share address space
+
+.BR KCMP_FILES
+compares the file descriptor arrays to see whether the processes share all files
+
+.BR KCMP_FS
+compares whether processes share the file system information (the current umask,
+working directory, namespace root, etc)
+
+.BR KCMP_SIGHAND
+compares whether processes share a signal handlers table
+
+.BR KCMP_IO
+compares whether processes do share I/O context,
+used mainly for block I/O scheduling
+
+.BR KCMP_SYSVSEM
+compares the list of undo operations associated with SYSV semaphores
+
+.SH "RETURN VALUE"
+.B kcmp
+was designed to return values suitable for sorting.
+This is particularly handy when one have to compare
+a large number of file descriptors.
+
+The return value is merely a result of simple arithmetic comparison
+of kernel pointers (when kernel compares resources, it uses their
+memory addresses).
+
+The easiest way to explain is to consider an example.
+Lets say
+.IR v1
+and
+.IR v2
+are the addresses of appropriate resources, then the return value
+is one of the following
+
+.B 0
+\-
+.IR v1
+is equal to
+.IR v2
+, in other words we have a shared resource here
+
+.B 1
+\-
+.IR v1
+is less than
+.IR v2
+
+.B 2
+\-
+.IR v1
+is greater than
+.IR v2
+
+.B 3
+\-
+.IR v1
+is not equal to
+.IR v2
+, but ordering information is unavailable.
+
+On error, \-1 is returned, and errno is set appropriately.
+
+.SH "CONFORMING TO"
+.BR kcmp ()
+is Linux specific and should not be used in programs intended to be portable.
+.SH "SEE ALSO"
+.BR clone (2)
-- 
1.7.7.6

Re: [PATCH 2/2] Add kcmp.2 manpage

[Cyrill Gorcunov]

On Fri, Mar 09, 2012 at 12:50:17PM -0800, H. Peter Anvin wrote:
> On 03/09/2012 12:47 PM, Cyrill Gorcunov wrote:
> > +.I v2
> > +, but ordering information is unavailble.
> 
> Needs to be:
> 
> .IR v2 ,
> 
> ... and fix the typo in "unavailable".
> 

here we go

	Cyrill
---
From: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
Date: Sat, 10 Mar 2012 01:03:00 +0400
Subject: [PATCH] Add kcmp.2 manpage

NAME
       kcmp - compare if two processes do share a particular kernel resource

SYNOPSIS
       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>
       #include <linux/kcmp.h>
       #include <sys/syscall.h>   /* For SYS_xxx definitions */

       int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);

DESCRIPTION
       kcmp() allows to find out if two processes identified by pid1 and pid2
       share kernel resources such as virtual memory, file descriptors, file system etc.

       The comparison type is one of the following

       KCMP_FILE determines whether a file descriptor idx1 in the first process
       is the same as another descriptor idx2 in the second process

       KCMP_VM compares whether processes share address space

       KCMP_FILES compares the file descriptor arrays to see whether the processes
       share all files

       KCMP_FS compares whether processes share the file system information (the current
       umask, working directory, namespace root, etc)

       KCMP_SIGHAND compares whether processes share a signal handlers table

       KCMP_IO compares whether processes do share I/O context, used mainly for
       block I/O scheduling

       KCMP_SYSVSEM compares the list of undo operations associated with SYSV semaphores

RETURN VALUE
       kcmp was designed to return values suitable for sorting.  This is particularly handy
       when one have to compare a large number of file descriptors.

       The return value is merely a result of simple arithmetic comparison of kernel pointers
       (when kernel compares resources, it uses their memory addresses).

       The  easiest way to explain is to consider an example.  Lets say v1 and v2 are the
       addresses of appropriate resources, then the return value is one of the following

       0 - v1 is equal to v2 , in other words we have a shared resource here
       1 - v1 is less than v2
       2 - v1 is greater than v2
       3 - v1 is not equal to but ordering information is unavailable.

       On error, -1 is returned, and errno is set appropriately.

Signed-off-by: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
CC: "Eric W. Biederman" <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
CC: "H. Peter Anvin" <hpa-YMNOUZJC4hwAvxtiuMwx3w@public.gmane.org>
CC: Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org>
---
 man2/kcmp.2 |  107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 107 insertions(+), 0 deletions(-)
 create mode 100644 man2/kcmp.2

diff --git a/man2/kcmp.2 b/man2/kcmp.2
new file mode 100644
index 0000000..a8615f1
--- /dev/null
+++ b/man2/kcmp.2
@@ -0,0 +1,107 @@
+.TH KCMP 2 2012-02-01 "Linux" "Linux Programmer's Manual"
+
+.SH NAME
+kcmp \- compare if two processes do share a particular kernel resource
+
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <unistd.h>
+.B #include <linux/kcmp.h>
+.BR "#include <sys/syscall.h>   "  "/* For SYS_xxx definitions */"
+
+.BI "int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);"
+.fi
+
+.SH DESCRIPTION
+
+.BR kcmp ()
+allows to find out if two processes identified by
+.IR pid1
+and
+.IR pid2
+share kernel resources such as virtual memory,
+file descriptors, file system etc.
+
+The comparison
+.IR type
+is one of the following
+
+.BR KCMP_FILE
+determines whether a file descriptor
+.IR idx1
+in the first process is the same as another descriptor
+.IR idx2
+in the second process
+
+.BR KCMP_VM
+compares whether processes share address space
+
+.BR KCMP_FILES
+compares the file descriptor arrays to see whether the processes share all files
+
+.BR KCMP_FS
+compares whether processes share the file system information (the current umask,
+working directory, namespace root, etc)
+
+.BR KCMP_SIGHAND
+compares whether processes share a signal handlers table
+
+.BR KCMP_IO
+compares whether processes do share I/O context,
+used mainly for block I/O scheduling
+
+.BR KCMP_SYSVSEM
+compares the list of undo operations associated with SYSV semaphores
+
+.SH "RETURN VALUE"
+.B kcmp
+was designed to return values suitable for sorting.
+This is particularly handy when one have to compare
+a large number of file descriptors.
+
+The return value is merely a result of simple arithmetic comparison
+of kernel pointers (when kernel compares resources, it uses their
+memory addresses).
+
+The easiest way to explain is to consider an example.
+Lets say
+.IR v1
+and
+.IR v2
+are the addresses of appropriate resources, then the return value
+is one of the following
+
+.B 0
+\-
+.IR v1
+is equal to
+.IR v2
+, in other words we have a shared resource here
+
+.B 1
+\-
+.IR v1
+is less than
+.IR v2
+
+.B 2
+\-
+.IR v1
+is greater than
+.IR v2
+
+.B 3
+\-
+.IR v1
+is not equal to
+.IR v2
+, but ordering information is unavailable.
+
+On error, \-1 is returned, and errno is set appropriately.
+
+.SH "CONFORMING TO"
+.BR kcmp ()
+is Linux specific and should not be used in programs intended to be portable.
+.SH "SEE ALSO"
+.BR clone (2)
-- 
1.7.7.6

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] Add kcmp.2 manpage

[H. Peter Anvin]

On 03/09/2012 01:03 PM, Cyrill Gorcunov wrote:
> On Fri, Mar 09, 2012 at 12:50:17PM -0800, H. Peter Anvin wrote:
>> On 03/09/2012 12:47 PM, Cyrill Gorcunov wrote:
>>> +.I v2
>>> +, but ordering information is unavailble.
>>
>> Needs to be:
>>
>> .IR v2 ,
>>
>> ... and fix the typo in "unavailable".
>>
> 
> here we go
> 
> 	Cyrill

No, you missed the point, which is that the comma moved to the .IR line.

.BR and .IR mean "alternate between bold/italic and regular", so

.IR foo bar

gives you "foobar" where only "foo" is italiziced.  It is equivalent to:

\fIfoo\fPbar

	-hpa


-- 
H. Peter Anvin, Intel Open Source Technology Center
I work for Intel.  I don't speak on their behalf.

Re: [PATCH 2/2] Add kcmp.2 manpage

[Cyrill Gorcunov]

On Fri, Mar 09, 2012 at 01:15:21PM -0800, H. Peter Anvin wrote:
> No, you missed the point, which is that the comma moved to the .IR line.
> 
> .BR and .IR mean "alternate between bold/italic and regular", so
> 
> .IR foo bar
> 
> gives you "foobar" where only "foo" is italiziced.  It is equivalent to:
> 
> \fIfoo\fPbar
> 

Ouch, sorry. Will update shortly.

	Cyrill

Re: [PATCH 2/2] Add kcmp.2 manpage

[Cyrill Gorcunov]

On Fri, Mar 09, 2012 at 01:15:21PM -0800, H. Peter Anvin wrote:
> No, you missed the point, which is that the comma moved to the .IR line.
> 
> .BR and .IR mean "alternate between bold/italic and regular", so
> 
> .IR foo bar
> 
> gives you "foobar" where only "foo" is italiziced.  It is equivalent to:
> 
> \fIfoo\fPbar
> 

Ouch, sorry. Will update shortly.

	Cyrill
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] Add kcmp.2 manpage

[Cyrill Gorcunov]

On Sat, Mar 10, 2012 at 01:18:13AM +0400, Cyrill Gorcunov wrote:
> 
> Ouch, sorry. Will update shortly.
> 

This one should do the trick.

	Cyrill
---
From: Cyrill Gorcunov <gorcunov@openvz.org>
Date: Sat, 10 Mar 2012 01:24:50 +0400
Subject: [PATCH] Add kcmp.2 manpage

NAME
       kcmp - compare if two processes do share a particular kernel resource

SYNOPSIS
       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>
       #include <linux/kcmp.h>
       #include <sys/syscall.h>   /* For SYS_xxx definitions */

       int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);

DESCRIPTION
       kcmp() allows to find out if two processes identified by pid1 and pid2
       share kernel resources such as virtual memory, file descriptors, file system etc.

       The comparison type is one of the following

       KCMP_FILE determines whether a file descriptor idx1 in the first process
       is the same as another descriptor idx2 in the second process

       KCMP_VM compares whether processes share address space

       KCMP_FILES compares the file descriptor arrays to see whether the processes
       share all files

       KCMP_FS compares whether processes share the file system information (the current
       umask, working directory, namespace root, etc)

       KCMP_SIGHAND compares whether processes share a signal handlers table

       KCMP_IO compares whether processes do share I/O context, used mainly for
       block I/O scheduling

       KCMP_SYSVSEM compares the list of undo operations associated with SYSV semaphores

RETURN VALUE
       kcmp was designed to return values suitable for sorting.  This is particularly handy
       when one have to compare a large number of file descriptors.

       The return value is merely a result of simple arithmetic comparison of kernel pointers
       (when kernel compares resources, it uses their memory addresses).

       The  easiest way to explain is to consider an example.  Lets say v1 and v2 are the
       addresses of appropriate resources, then the return value is one of the following

       0 - v1 is equal to v2 , in other words we have a shared resource here
       1 - v1 is less than v2
       2 - v1 is greater than v2
       3 - v1 is not equal to but ordering information is unavailble.

       On error, -1 is returned, and errno is set appropriately.

Signed-off-by: Cyrill Gorcunov <gorcunov@openvz.org>
CC: "Eric W. Biederman" <ebiederm@xmission.com>
CC: "H. Peter Anvin" <hpa@zytor.com>
CC: Pavel Emelyanov <xemul@parallels.com>
---
 man2/kcmp.2 |  107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 107 insertions(+), 0 deletions(-)
 create mode 100644 man2/kcmp.2

diff --git a/man2/kcmp.2 b/man2/kcmp.2
new file mode 100644
index 0000000..6c0d3a2
--- /dev/null
+++ b/man2/kcmp.2
@@ -0,0 +1,107 @@
+.TH KCMP 2 2012-02-01 "Linux" "Linux Programmer's Manual"
+
+.SH NAME
+kcmp \- compare if two processes do share a particular kernel resource
+
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <unistd.h>
+.B #include <linux/kcmp.h>
+.BR "#include <sys/syscall.h>   "  "/* For SYS_xxx definitions */"
+
+.BI "int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);"
+.fi
+
+.SH DESCRIPTION
+
+.BR kcmp ()
+allows to find out if two processes identified by
+.I pid1
+and
+.I pid2
+share kernel resources such as virtual memory,
+file descriptors, file system etc.
+
+The comparison
+.I type
+is one of the following
+
+.BR KCMP_FILE
+determines whether a file descriptor
+.I idx1
+in the first process is the same as another descriptor
+.I idx2
+in the second process
+
+.BR KCMP_VM
+compares whether processes share address space
+
+.BR KCMP_FILES
+compares the file descriptor arrays to see whether the processes share all files
+
+.BR KCMP_FS
+compares whether processes share the file system information (the current umask,
+working directory, namespace root, etc)
+
+.BR KCMP_SIGHAND
+compares whether processes share a signal handlers table
+
+.BR KCMP_IO
+compares whether processes do share I/O context,
+used mainly for block I/O scheduling
+
+.BR KCMP_SYSVSEM
+compares the list of undo operations associated with SYSV semaphores
+
+.SH "RETURN VALUE"
+.B kcmp
+was designed to return values suitable for sorting.
+This is particularly handy when one have to compare
+a large number of file descriptors.
+
+The return value is merely a result of simple arithmetic comparison
+of kernel pointers (when kernel compares resources, it uses their
+memory addresses).
+
+The easiest way to explain is to consider an example.
+Lets say
+.I v1
+and
+.I v2
+are the addresses of appropriate resources, then the return value
+is one of the following
+
+.B 0
+\-
+.I v1
+is equal to
+.IR v2 ,
+in other words we have a shared resource here
+
+.B 1
+\-
+.I v1
+is less than
+.I v2
+
+.B 2
+\-
+.I v1
+is greater than
+.I v2
+
+.B 3
+\-
+.I v1
+is not equal to
+.IR v2 ,
+but ordering information is unavailable.
+
+On error, \-1 is returned, and errno is set appropriately.
+
+.SH "CONFORMING TO"
+.BR kcmp ()
+is Linux specific and should not be used in programs intended to be portable.
+.SH "SEE ALSO"
+.BR clone (2)
-- 
1.7.7.6

Re: [PATCH 2/2] Add kcmp.2 manpage

[Cyrill Gorcunov]

On Sat, Mar 10, 2012 at 01:18:13AM +0400, Cyrill Gorcunov wrote:
> 
> Ouch, sorry. Will update shortly.
> 

This one should do the trick.

	Cyrill
---
From: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
Date: Sat, 10 Mar 2012 01:24:50 +0400
Subject: [PATCH] Add kcmp.2 manpage

NAME
       kcmp - compare if two processes do share a particular kernel resource

SYNOPSIS
       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <unistd.h>
       #include <linux/kcmp.h>
       #include <sys/syscall.h>   /* For SYS_xxx definitions */

       int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);

DESCRIPTION
       kcmp() allows to find out if two processes identified by pid1 and pid2
       share kernel resources such as virtual memory, file descriptors, file system etc.

       The comparison type is one of the following

       KCMP_FILE determines whether a file descriptor idx1 in the first process
       is the same as another descriptor idx2 in the second process

       KCMP_VM compares whether processes share address space

       KCMP_FILES compares the file descriptor arrays to see whether the processes
       share all files

       KCMP_FS compares whether processes share the file system information (the current
       umask, working directory, namespace root, etc)

       KCMP_SIGHAND compares whether processes share a signal handlers table

       KCMP_IO compares whether processes do share I/O context, used mainly for
       block I/O scheduling

       KCMP_SYSVSEM compares the list of undo operations associated with SYSV semaphores

RETURN VALUE
       kcmp was designed to return values suitable for sorting.  This is particularly handy
       when one have to compare a large number of file descriptors.

       The return value is merely a result of simple arithmetic comparison of kernel pointers
       (when kernel compares resources, it uses their memory addresses).

       The  easiest way to explain is to consider an example.  Lets say v1 and v2 are the
       addresses of appropriate resources, then the return value is one of the following

       0 - v1 is equal to v2 , in other words we have a shared resource here
       1 - v1 is less than v2
       2 - v1 is greater than v2
       3 - v1 is not equal to but ordering information is unavailble.

       On error, -1 is returned, and errno is set appropriately.

Signed-off-by: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
CC: "Eric W. Biederman" <ebiederm-aS9lmoZGLiVWk0Htik3J/w@public.gmane.org>
CC: "H. Peter Anvin" <hpa-YMNOUZJC4hwAvxtiuMwx3w@public.gmane.org>
CC: Pavel Emelyanov <xemul-bzQdu9zFT3WakBO8gow8eQ@public.gmane.org>
---
 man2/kcmp.2 |  107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 107 insertions(+), 0 deletions(-)
 create mode 100644 man2/kcmp.2

diff --git a/man2/kcmp.2 b/man2/kcmp.2
new file mode 100644
index 0000000..6c0d3a2
--- /dev/null
+++ b/man2/kcmp.2
@@ -0,0 +1,107 @@
+.TH KCMP 2 2012-02-01 "Linux" "Linux Programmer's Manual"
+
+.SH NAME
+kcmp \- compare if two processes do share a particular kernel resource
+
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <unistd.h>
+.B #include <linux/kcmp.h>
+.BR "#include <sys/syscall.h>   "  "/* For SYS_xxx definitions */"
+
+.BI "int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);"
+.fi
+
+.SH DESCRIPTION
+
+.BR kcmp ()
+allows to find out if two processes identified by
+.I pid1
+and
+.I pid2
+share kernel resources such as virtual memory,
+file descriptors, file system etc.
+
+The comparison
+.I type
+is one of the following
+
+.BR KCMP_FILE
+determines whether a file descriptor
+.I idx1
+in the first process is the same as another descriptor
+.I idx2
+in the second process
+
+.BR KCMP_VM
+compares whether processes share address space
+
+.BR KCMP_FILES
+compares the file descriptor arrays to see whether the processes share all files
+
+.BR KCMP_FS
+compares whether processes share the file system information (the current umask,
+working directory, namespace root, etc)
+
+.BR KCMP_SIGHAND
+compares whether processes share a signal handlers table
+
+.BR KCMP_IO
+compares whether processes do share I/O context,
+used mainly for block I/O scheduling
+
+.BR KCMP_SYSVSEM
+compares the list of undo operations associated with SYSV semaphores
+
+.SH "RETURN VALUE"
+.B kcmp
+was designed to return values suitable for sorting.
+This is particularly handy when one have to compare
+a large number of file descriptors.
+
+The return value is merely a result of simple arithmetic comparison
+of kernel pointers (when kernel compares resources, it uses their
+memory addresses).
+
+The easiest way to explain is to consider an example.
+Lets say
+.I v1
+and
+.I v2
+are the addresses of appropriate resources, then the return value
+is one of the following
+
+.B 0
+\-
+.I v1
+is equal to
+.IR v2 ,
+in other words we have a shared resource here
+
+.B 1
+\-
+.I v1
+is less than
+.I v2
+
+.B 2
+\-
+.I v1
+is greater than
+.I v2
+
+.B 3
+\-
+.I v1
+is not equal to
+.IR v2 ,
+but ordering information is unavailable.
+
+On error, \-1 is returned, and errno is set appropriately.
+
+.SH "CONFORMING TO"
+.BR kcmp ()
+is Linux specific and should not be used in programs intended to be portable.
+.SH "SEE ALSO"
+.BR clone (2)
-- 
1.7.7.6

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html