.\" Licensed under the GPL
.\"
.\" Patch Justification:
-.\" unshare system call is needed to implement, using PAM,
-.\" per-security_context and/or per-user namespace to provide
-.\" polyinstantiated directories. Using unshare and bind mounts, a
-.\" PAM module can create private namespace with appropriate
-.\" directories(based on user's security context) bind mounted on
-.\" public directories such as /tmp, thus providing an instance of
-.\" /tmp that is based on user's security context. Without the
-.\" unshare system call, namespace separation can only be achieved
-.\" by clone, which would require porting and maintaining all commands
-.\" such as login, and su, that establish a user session.
+.\" unshare system call is needed to implement, using PAM,
+.\" per-security_context and/or per-user namespace to provide
+.\" polyinstantiated directories. Using unshare and bind mounts, a
+.\" PAM module can create private namespace with appropriate
+.\" directories(based on user's security context) bind mounted on
+.\" public directories such as /tmp, thus providing an instance of
+.\" /tmp that is based on user's security context. Without the
+.\" unshare system call, namespace separation can only be achieved
+.\" by clone, which would require porting and maintaining all commands
+.\" such as login, and su, that establish a user session.
.\"
.TH UNSHARE 2 2005-03-10 "Linux 2.6.16" "Linux Programmer's Manual"
.SH NAME
.BI "int unshare(int " flags );
.fi
.SH DESCRIPTION
-.BR unshare ()
+.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
+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),
+.BR vfork (2),
while other parts, such as virtual memory, may be
-shared by explicit request when creating a process using
+shared by explicit request when creating a process using
.BR clone (2).
-The main use of
+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.
+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
.BR clone (2)
.B CLONE_FILES
flag.
-Unshare the file descriptor table, so that the calling process
+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
+.B CLONE_FS
flag.
-Unshare file system attributes, so that the calling process
-no longer shares its root directory, current directory,
+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),
.TP
.B CLONE_NEWNS
.\" These flag name are inconsistent:
-.\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
+.\" 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
-.I same
+This flag has the
+.I same
effect as the
.BR clone (2)
.B CLONE_NEWNS
.\" As at 2.6.16, the following forced implications also apply,
.\" although the relevant flags 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
+.\" 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.
.\"
.\" FIXME . CLONE_VM is not (yet, as at 2.6.16) implemented.
.\" and can be reversed using this
.\" .BR unshare ()
.\" flag.)
-.\" Unshare virtual memory, so that the calling process no
+.\" Unshare virtual memory, so that the calling process no
.\" longer shares its virtual address space with any other process.
.PP
-If
+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
+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
+.B CLONE_NEWNS
but the calling process was not privileged (did not have the
.B CAP_SYS_ADMIN
capability).
.BR unshare ()
system call was added to Linux in kernel 2.6.16.
-Not all of the process attributes that can be shared when
+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 ()
+.BR unshare ()
does not implement flags that reverse the effects of
.BR CLONE_SIGHAND ,
.\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
.\"applications using unshare.
.\"
.SH SEE ALSO
-.BR clone (2),
-.BR fork (2),
-.BR vfork (2),
+.BR clone (2),
+.BR fork (2),
+.BR vfork (2),
Documentation/unshare.txt