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