.\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com>
-.\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2006, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
.\" Licensed under the GPL
.\" by clone, which would require porting and maintaining all commands
.\" such as login, and su, that establish a user session.
.\"
-.TH UNSHARE 2 2013-04-17 "Linux" "Linux Programmer's Manual"
+.TH UNSHARE 2 2014-09-21 "Linux" "Linux Programmer's Manual"
.SH NAME
unshare \- disassociate parts of the process execution context
.SH SYNOPSIS
.BR CAP_SYS_ADMIN
capability.
.TP
-.BR CLONE_NEWUTS " (since Linux 2.6.19)
+.BR CLONE_NEWPID " (since Linux 3.8)"
+This flag has the same effect as the
+.BR clone (2)
+.B CLONE_NEWPID
+flag.
+Unshare the PID namespace,
+so that the calling process has a new PID namespace for its children
+which is not shared with any previously existing process.
+The calling process is
+.I not
+moved into the new namespace.
+The first child created by the calling process will have
+the process ID 1 and will assume the role of
+.BR init (1)
+in the new namespace.
+.BR CLONE_NEWPID
+automatically implies
+.BR CLONE_THREAD
+as well.
+Use of
+.BR CLONE_NEWPID
+requires the
+.BR CAP_SYS_ADMIN
+capability.
+For further information, see
+.BR pid_namespaces (7).
+.TP
+.BR CLONE_NEWUSER " (since Linux 3.8)"
+This flag has the same effect as the
+.BR clone (2)
+.B CLONE_NEWUSER
+flag.
+Unshare the user namespace,
+so that the calling process is moved into a new user namespace
+which is not shared with any previously existing process.
+As with the child process created by
+.BR clone (2)
+with the
+.B CLONE_NEWUSER
+flag, the caller obtains a full set of capabilities in the new namespace.
+.IP
+.BR CLONE_NEWUSER
+requires that the calling process is not threaded; specifying
+.BR CLONE_NEWUSER
+automatically implies
+.BR CLONE_THREAD .
+Since Linux 3.9,
+.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
+.\" https://lwn.net/Articles/543273/
+.BR CLONE_NEWUSER
+also automatically implies
+.BR CLONE_FS .
+.BR CLONE_NEWUSER
+requires that the user ID and group ID
+of the calling process are mapped to user IDs and group IDs in the
+user namespace of the calling process at the time of the call.
+
+For further information on user namespaces, see
+.BR user_namespaces (7).
+.TP
+.BR CLONE_NEWUTS " (since Linux 2.6.19)"
This flag has the same effect as the
.BR clone (2)
.B CLONE_NEWUTS
.BR clone (2)
.B CLONE_SYSVSEM
flag.
-Unshare System\ V semaphore undo values,
-so that the calling process has a private copy
-which is not shared with any other process.
-Use of
-.BR CLONE_SYSVSEM
-requires the
-.BR CAP_SYS_ADMIN
-capability.
-.\" As at 2.6.16, the following forced implications also apply,
+Unshare System\ V semaphore adjustment
+.RI ( semadj )
+values,
+so that the calling process has a new empty
+.I semadj
+list that is not shared with any other process.
+If this is the last process that has a reference to the process's current
+.I semadj
+list, then the adjustments in that list are applied
+to the corresponding semaphores, as described in
+.BR semop (2).
+.\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
+.\" (i.e., current->signal->count > 1), force CLONE_THREAD.
+.PP
+In addition,
+.BR CLONE_THREAD ,
+.BR CLONE_SIGHAND ,
+and
+.BR CLONE_VM
+can be specified in
+.I flags
+if the caller is single threaded (i.e., it is not sharing
+its address space with another process or thread).
+In this case, these flags have no effect.
+(Note also that specifying
+.BR CLONE_THREAD
+automatically implies
+.BR CLONE_VM ,
+and specifying
+.BR CLONE_VM
+automatically implies
+.BR CLONE_SIGHAND .)
+.\" As at 3.9, 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.
-.\" CLONE_NEWNSIf 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.
-.\" .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.
+If the process is multithreaded, then
+the use of these flags results in an error.
+.\" See kernel/fork.c::check_unshare_flags()
.PP
If
.I flags
An invalid bit was specified in
.IR flags .
.TP
+.B EINVAL
+.BR CLONE_THREAD ,
+.BR CLONE_SIGHAND ,
+or
+.BR CLONE_VM
+was specified in
+.IR flags ,
+and the caller is multithreaded.
+.TP
.B ENOMEM
Cannot allocate sufficient memory to copy parts of caller's
context that need to be unshared.
.TP
.B EPERM
The calling process did not have the required privileges for this operation.
+.TP
+.B EPERM
+.BR CLONE_NEWUSER
+was specified in
+.IR flags ,
+but either the effective user ID or the effective group ID of the caller
+does not have a mapping in the parent namespace (see
+.BR user_namespaces (7)).
+.TP
+.BR EPERM " (since Linux 3.9)"
+.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
+.B CLONE_NEWUSER was specified in
+.I flags
+and the caller is in a chroot environment
+.\" FIXME What is the rationale for this restriction?
+(i.e., the caller's root directory does not match the root directory
+of the mount namespace in which it resides).
+.TP
+.BR EUSERS " (since Linux 3.11)"
+.B CLONE_NEWUSER
+was specified in
+.IR flags ,
+and the call would cause the limit on the number of
+nested user namespaces to be exceeded.
+See
+.BR user_namespaces (7).
.SH VERSIONS
The
.BR unshare ()
.\"be incrementally added to unshare without affecting legacy
.\"applications using unshare.
.\"
+.SH EXAMPLE
+The program below provides a simple implementation of the
+.BR unshare (1)
+command, which unshares one or more namespaces and executes the
+command supplied in its command-line arguments.
+Here's an example of the use of this program,
+running a shell in a new mount namespace,
+and verifying that the original shell and the
+new shell are in separate mount namespaces:
+.in +4n
+.nf
+
+$ \fBreadlink /proc/$$/ns/mnt\fP
+mnt:[4026531840]
+$ \fBsudo ./unshare -m /bin/bash\fP
+[sudo] password for cecilia:
+# \fBreadlink /proc/$$/ns/mnt\fP
+mnt:[4026532325]
+.fi
+.in
+
+The differing output of the two
+.BR readlink (1)
+commands shows that the two shells are in different mount namespaces.
+.SS Program source
+\&
+.nf
+/* unshare.c
+
+ A simple implementation of the unshare(1) command: unshare
+ namespaces and execute a command.
+*/
+#define _GNU_SOURCE
+#include <sched.h>
+#include <unistd.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+/* A simple error\-handling function: print an error message based
+ on the value in \(aqerrno\(aq and terminate the calling process */
+
+#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
+ } while (0)
+
+static void
+usage(char *pname)
+{
+ fprintf(stderr, "Usage: %s [options] program [arg...]\\n", pname);
+ fprintf(stderr, "Options can be:\\n");
+ fprintf(stderr, " \-i unshare IPC namespace\\n");
+ fprintf(stderr, " \-m unshare mount namespace\\n");
+ fprintf(stderr, " \-n unshare network namespace\\n");
+ fprintf(stderr, " \-p unshare PID namespace\\n");
+ fprintf(stderr, " \-u unshare UTS namespace\\n");
+ fprintf(stderr, " \-U unshare user namespace\\n");
+ exit(EXIT_FAILURE);
+}
+
+int
+main(int argc, char *argv[])
+{
+ int flags, opt;
+
+ flags = 0;
+
+ while ((opt = getopt(argc, argv, "imnpuU")) != \-1) {
+ switch (opt) {
+ case \(aqi\(aq: flags |= CLONE_NEWIPC; break;
+ case \(aqm\(aq: flags |= CLONE_NEWNS; break;
+ case \(aqn\(aq: flags |= CLONE_NEWNET; break;
+ case \(aqp\(aq: flags |= CLONE_NEWPID; break;
+ case \(aqu\(aq: flags |= CLONE_NEWUTS; break;
+ case \(aqU\(aq: flags |= CLONE_NEWUSER; break;
+ default: usage(argv[0]);
+ }
+ }
+
+ if (optind >= argc)
+ usage(argv[0]);
+
+ if (unshare(flags) == \-1)
+ errExit("unshare");
+
+ execvp(argv[optind], &argv[optind]);
+ errExit("execvp");
+}
+.fi
.SH SEE ALSO
+.BR unshare (1),
.BR clone (2),
.BR fork (2),
.BR kcmp (2),
.BR setns (2),
-.BR vfork (2)
+.BR vfork (2),
+.BR namespaces (7)
.I Documentation/unshare.txt
in the Linux kernel source tree
.SH COLOPHON
-This page is part of release 3.68 of the Linux
+This page is part of release 3.75 of the Linux
.I man-pages
project.
A description of the project,
OSDN Git Service
