]>
Commit | Line | Data |
---|---|---|
f50f6cb5 MK |
1 | .\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com> |
2 | .\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com> | |
5cc01e9c MK |
3 | .\" Licensed under the GPL |
4 | .\" | |
d44c4bf3 | 5 | .\" Patch Justification: |
c13182ef MK |
6 | .\" unshare system call is needed to implement, using PAM, |
7 | .\" per-security_context and/or per-user namespace to provide | |
8 | .\" polyinstantiated directories. Using unshare and bind mounts, a | |
9 | .\" PAM module can create private namespace with appropriate | |
10 | .\" directories(based on user's security context) bind mounted on | |
11 | .\" public directories such as /tmp, thus providing an instance of | |
12 | .\" /tmp that is based on user's security context. Without the | |
13 | .\" unshare system call, namespace separation can only be achieved | |
14 | .\" by clone, which would require porting and maintaining all commands | |
15 | .\" such as login, and su, that establish a user session. | |
d44c4bf3 | 16 | .\" |
360ed6b3 MK |
17 | .\" FIXME Document CLONE_NEWIPC, which is new in 2.6.18 |
18 | .\" FIXME Document CLONE_NEWUTS, which is new in 2.6.19 | |
19 | .\" | |
cc4615cc | 20 | .TH UNSHARE 2 2007-07-26 "Linux" "Linux Programmer's Manual" |
5cc01e9c MK |
21 | .SH NAME |
22 | unshare \- disassociate parts of the process execution context | |
23 | .SH SYNOPSIS | |
24 | .nf | |
cc4615cc MK |
25 | .B #define _GNU_SOURCE |
26 | .\" Actually _BSD_SOURCE || _SVID_SOURCE | |
27 | .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749 | |
5cc01e9c MK |
28 | .B #include <sched.h> |
29 | .sp | |
30 | .BI "int unshare(int " flags ); | |
31 | .fi | |
32 | .SH DESCRIPTION | |
c13182ef | 33 | .BR unshare () |
5cc01e9c | 34 | allows a process to disassociate parts of its execution |
c13182ef MK |
35 | context that are currently being shared with other processes. |
36 | Part of the execution context, such as the namespace, is shared | |
37 | implicitly when a new process is created using | |
5cc01e9c MK |
38 | .BR fork (2) |
39 | or | |
c13182ef | 40 | .BR vfork (2), |
5cc01e9c | 41 | while other parts, such as virtual memory, may be |
c13182ef | 42 | shared by explicit request when creating a process using |
5cc01e9c MK |
43 | .BR clone (2). |
44 | ||
c13182ef | 45 | The main use of |
5cc01e9c MK |
46 | .BR unshare () |
47 | is to allow a process to control its | |
48 | shared execution context without creating a new process. | |
49 | ||
c13182ef MK |
50 | The |
51 | .I flags | |
52 | argument is a bit mask that specifies which parts of | |
53 | the execution context should be unshared. | |
5cc01e9c MK |
54 | This argument is specified by ORing together zero or more |
55 | of the following constants: | |
56 | .TP | |
57 | .B CLONE_FILES | |
58 | Reverse the effect of the | |
59 | .BR clone (2) | |
60 | .B CLONE_FILES | |
61 | flag. | |
c13182ef | 62 | Unshare the file descriptor table, so that the calling process |
5cc01e9c MK |
63 | no longer shares its file descriptors with any other process. |
64 | .TP | |
65 | .B CLONE_FS | |
66 | Reverse the effect of the | |
67 | .BR clone (2) | |
c13182ef | 68 | .B CLONE_FS |
5cc01e9c | 69 | flag. |
c13182ef MK |
70 | Unshare file system attributes, so that the calling process |
71 | no longer shares its root directory, current directory, | |
5cc01e9c MK |
72 | or umask attributes with any other process. |
73 | .BR chroot (2), | |
74 | .BR chdir (2), | |
75 | or | |
76 | .BR umask (2) | |
77 | .TP | |
78 | .B CLONE_NEWNS | |
79 | .\" These flag name are inconsistent: | |
c13182ef | 80 | .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM, |
5cc01e9c MK |
81 | .\" CLONE_FS, and CLONE_FILES reverse the action of the clone() |
82 | .\" flags of the same name. | |
c13182ef MK |
83 | This flag has the |
84 | .I same | |
3d5f4595 | 85 | effect as the |
5cc01e9c MK |
86 | .BR clone (2) |
87 | .B CLONE_NEWNS | |
88 | flag. | |
89 | Unshare the namespace, so that the calling process has a private copy of | |
90 | its namespace which is not shared with any other process. | |
91 | Specifying this flag automatically implies | |
92 | .B CLONE_FS | |
93 | as well. | |
94 | .\" As at 2.6.16, the following forced implications also apply, | |
3d5f4595 | 95 | .\" although the relevant flags are not yet implemented. |
5cc01e9c | 96 | .\" If CLONE_THREAD is set force CLONE_VM. |
c13182ef MK |
97 | .\" If CLONE_VM is set, force CLONE_SIGHAND. |
98 | .\" If CLONE_SIGHAND is set and signals are also being shared | |
5cc01e9c | 99 | .\" (i.e., current->signal->count > 1), force CLONE_THREAD. |
3d5f4595 MK |
100 | .\" |
101 | .\" FIXME . CLONE_VM is not (yet, as at 2.6.16) implemented. | |
102 | .\" .TP | |
103 | .\" .B CLONE_VM | |
104 | .\" Reverse the effect of the | |
105 | .\" .BR clone (2) | |
106 | .\" .B CLONE_VM | |
107 | .\" flag. | |
108 | .\" .RB ( CLONE_VM | |
109 | .\" is also implicitly set by | |
110 | .\" .BR vfork (2), | |
111 | .\" and can be reversed using this | |
112 | .\" .BR unshare () | |
113 | .\" flag.) | |
c13182ef | 114 | .\" Unshare virtual memory, so that the calling process no |
3d5f4595 MK |
115 | .\" longer shares its virtual address space with any other process. |
116 | .PP | |
c13182ef | 117 | If |
5cc01e9c MK |
118 | .I flags |
119 | is specified as zero, then | |
120 | .BR unshare () | |
121 | is a no-op; | |
122 | no changes are made to the calling process's execution context. | |
123 | .SH RETURN VALUE | |
c13182ef MK |
124 | On success, zero returned. |
125 | On failure, \-1 is returned and | |
126 | .I errno | |
5cc01e9c MK |
127 | is set to indicate the error. |
128 | .SH ERRORS | |
129 | .TP | |
eab64696 MK |
130 | .B EINVAL |
131 | An invalid bit was specified in | |
132 | .IR flags . | |
133 | .TP | |
134 | .B ENOMEM | |
135 | Cannot allocate sufficient memory to copy parts of caller's | |
136 | context that need to be unshared. | |
137 | .TP | |
5cc01e9c MK |
138 | .B EPERM |
139 | .I flags | |
140 | specified | |
c13182ef | 141 | .B CLONE_NEWNS |
5cc01e9c MK |
142 | but the calling process was not privileged (did not have the |
143 | .B CAP_SYS_ADMIN | |
144 | capability). | |
ff457ccb | 145 | .SH VERSIONS |
5cc01e9c MK |
146 | The |
147 | .BR unshare () | |
148 | system call was added to Linux in kernel 2.6.16. | |
2dd578fd MK |
149 | .SH CONFORMING TO |
150 | The | |
151 | .BR unshare () | |
8382f16d | 152 | system call is Linux-specific. |
ff457ccb | 153 | .SH NOTES |
c13182ef | 154 | Not all of the process attributes that can be shared when |
5cc01e9c MK |
155 | a new process is created using |
156 | .BR clone (2) | |
157 | can be unshared using | |
158 | .BR unshare (). | |
159 | In particular, as at kernel 2.6.16, | |
c13182ef | 160 | .BR unshare () |
5cc01e9c MK |
161 | does not implement flags that reverse the effects of |
162 | .BR CLONE_SIGHAND , | |
3d5f4595 | 163 | .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND |
5cc01e9c MK |
164 | .\" was not specified when doing clone(); i.e., unsharing |
165 | .\" signal handlers is permitted if we are not actually | |
166 | .\" sharing signal handlers. mtk | |
167 | .BR CLONE_SYSVSEM , | |
3d5f4595 MK |
168 | .BR CLONE_THREAD , |
169 | or | |
170 | .\" FIXME . check future kernel versions (e.g., 2.6.17) | |
171 | .\" to see if CLONE_VM gets implemented. | |
172 | .BR CLONE_VM . | |
173 | .\" However, as at 2.6.16, we can do unshare(CLONE_VM) if CLONE_VM | |
174 | .\" was not specified when doing clone(); i.e., unsharing | |
175 | .\" virtual memory is permitted if we are not actually | |
176 | .\" sharing virtual memory. mtk | |
5cc01e9c MK |
177 | Such functionality may be added in the future, if required. |
178 | .\" | |
179 | .\"9) Future Work | |
180 | .\"-------------- | |
181 | .\"The current implementation of unshare does not allow unsharing of | |
182 | .\"signals and signal handlers. Signals are complex to begin with and | |
183 | .\"to unshare signals and/or signal handlers of a currently running | |
184 | .\"process is even more complex. If in the future there is a specific | |
185 | .\"need to allow unsharing of signals and/or signal handlers, it can | |
186 | .\"be incrementally added to unshare without affecting legacy | |
187 | .\"applications using unshare. | |
188 | .\" | |
189 | .SH SEE ALSO | |
c13182ef MK |
190 | .BR clone (2), |
191 | .BR fork (2), | |
192 | .BR vfork (2), | |
5cc01e9c | 193 | Documentation/unshare.txt |