From 5cc01e9c8830ce6b4e8664a0ac24e948a4900017 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 20 Mar 2006 21:29:29 +0000 Subject: [PATCH] Document unshare(2), new in 2.6.16. --- man2/clone.2 | 3 +- man2/fork.2 | 3 +- man2/unshare.2 | 163 +++++++++++++++++++++++++++++++++++++++++++++++++ man2/vfork.2 | 3 +- 4 files changed, 166 insertions(+), 6 deletions(-) create mode 100644 man2/unshare.2 diff --git a/man2/clone.2 b/man2/clone.2 index 94598ed905..6f4ddd58d3 100644 --- a/man2/clone.2 +++ b/man2/clone.2 @@ -674,8 +674,7 @@ To get the truth, it may be necessary to use code such as the following .BR set_thread_area (2), .BR set_tid_address (2), .BR tkill (2), -.\" FIXME . eventually add this: -.\" .BR unshare (2), +.BR unshare (2), .BR wait (2), .BR capabilities (7), .BR pthreads (7) diff --git a/man2/fork.2 b/man2/fork.2 index 55d805a564..37b91b78e7 100644 --- a/man2/fork.2 +++ b/man2/fork.2 @@ -91,8 +91,7 @@ and .BR clone (2), .BR execve (2), .BR setrlimit (2), -.\" FIXME . eventually add this: -.\" .BR unshare (2), +.BR unshare (2), .BR vfork (2), .BR wait (2), .BR capabilities (7) diff --git a/man2/unshare.2 b/man2/unshare.2 new file mode 100644 index 0000000000..00fe3f3d83 --- /dev/null +++ b/man2/unshare.2 @@ -0,0 +1,163 @@ +.\" (C) 2006, Janak Desai +.\" (C) 2006, Michael Kerrisk +.\" Licensed under the GPL +.\" +.TH UNSHARE 2 2005-03-10 "Linux 2.6.16" "Linux Programmer's Manual" +.SH NAME +unshare \- disassociate parts of the process execution context +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "int unshare(int " flags ); +.fi +.SH DESCRIPTION +.BR unshare () +allows a process to disassociate parts of its execution +context that are currently being shared with other processes. +Part of the execution context, such as the namespace, is shared +implicitly when a new process is created using +.BR fork (2) +or +.BR vfork (2), +while other parts, such as virtual memory, may be +shared by explicit request when creating a process using +.BR clone (2). + +The main use of +.BR unshare () +is to allow a process to control its +shared execution context without creating a new process. + +The +.I flags +argument is a bit mask that specifies which parts of +the execution context should be unshared. +This argument is specified by ORing together zero or more +of the following constants: +.TP +.B CLONE_FILES +Reverse the effect of the +.BR clone (2) +.B CLONE_FILES +flag. +Unshare the file descriptor table, so that the calling process +no longer shares its file descriptors with any other process. +.TP +.B CLONE_FS +Reverse the effect of the +.BR clone (2) +.B CLONE_FS +flag. +Unshare file system attributes, so that the calling process +no longer shares its root directory, current directory, +or umask attributes with any other process. +.BR chroot (2), +.BR chdir (2), +or +.BR umask (2) +.TP +.B CLONE_NEWNS +.\" These flag name are inconsistent: +.\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM, +.\" CLONE_FS, and CLONE_FILES reverse the action of the clone() +.\" flags of the same name. +This flag has the same effect as the +.BR clone (2) +.B CLONE_NEWNS +flag. +Unshare the namespace, so that the calling process has a private copy of +its namespace which is not shared with any other process. +Specifying this flag automatically implies +.B CLONE_FS +as well. +.\" As at 2.6.16, the following forced implications also apply, +.\" although CLONE_THREAD and CLONE_SIGHAND are not yet implemented. +.\" If CLONE_THREAD is set force CLONE_VM. +.\" If CLONE_VM is set, force CLONE_SIGHAND. +.\" If CLONE_SIGHAND is set and signals are also being shared +.\" (i.e., current->signal->count > 1), force CLONE_THREAD. +.TP +.B CLONE_VM +Reverse the effect of the +.BR clone (2) +.B CLONE_VM +flag. +.RB ( CLONE_VM +is also implicitly set by +.BR vfork (2), +and can be reversed using this +.BR unshare () +flag.) +Unshare virtual memory, so that the calling process no +longer shares its virtual address space with any other process. +.PP +If +.I flags +is specified as zero, then +.BR unshare () +is a no-op; +no changes are made to the calling process's execution context. +.SH RETURN VALUE +On success, zero returned. On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EPERM +.I flags +specified +.B CLONE_NEWNS +but the calling process was not privileged (did not have the +.B CAP_SYS_ADMIN +capability). +.TP +.B ENOMEM +Cannot allocate sufficient memory to copy parts of caller's +context that need to be unshared. +.TP +.B EINVAL +An invalid bit was specified in +.IR flags . +.SH CONFORMING TO +The +.BR unshare () +system call is Linux-specific. +.SH NOTES +The +.BR unshare () +system call was added to Linux in kernel 2.6.16. + +Not all of the process attributes that can be shared when +a new process is created using +.BR clone (2) +can be unshared using +.BR unshare (). +In particular, as at kernel 2.6.16, +.BR unshare () +does not implement flags that reverse the effects of +.BR CLONE_SIGHAND , +.\" However we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND +.\" was not specified when doing clone(); i.e., unsharing +.\" signal handlers is permitted if we are not actually +.\" sharing signal handlers. mtk +.BR CLONE_SYSVSEM , +or +.BR CLONE_THREAD . +Such functionality may be added in the future, if required. +.\" +.\"9) Future Work +.\"-------------- +.\"The current implementation of unshare does not allow unsharing of +.\"signals and signal handlers. Signals are complex to begin with and +.\"to unshare signals and/or signal handlers of a currently running +.\"process is even more complex. If in the future there is a specific +.\"need to allow unsharing of signals and/or signal handlers, it can +.\"be incrementally added to unshare without affecting legacy +.\"applications using unshare. +.\" +.SH SEE ALSO +.BR clone (2), +.BR fork (2), +.BR vfork (2), +Documentation/unshare.txt diff --git a/man2/vfork.2 b/man2/vfork.2 index 1fe43dc7fc..ea8ef87384 100644 --- a/man2/vfork.2 +++ b/man2/vfork.2 @@ -181,6 +181,5 @@ and cannot rely on any specific behaviour w.r.t. shared memory. .BR clone (2), .BR execve (2), .BR fork (2), -.\" FIXME . eventually add this: -.\" .BR unshare (2), +.BR unshare (2), .BR wait (2) -- 2.39.5