Debian Codegraph @

upstream/debian-unstable/man2/NS_GET_USERNS.2const

raw
1 .\" Copyright 2017, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH NS_GET_USERNS 2const 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 NS_GET_USERNS,
9 NS_GET_PARENT
10 \-
11 discovering namespace relationships
12 .SH SYNOPSIS
13 .nf
14 .BR "#include <linux/nsfs.h>" " /* Definition of " NS_GET_* " constants */"
15 .B #include <sys/ioctl.h>
16 .P
17 .BI "int ioctl(int " fd ", unsigned long " op );
18 .fi
19 .SH DESCRIPTION
20 The following
21 .BR ioctl (2)
22 operations are provided to allow discovery of namespace relationships (see
23 .BR user_namespaces (7)
24 and
25 .BR pid_namespaces (7)).
26 .P
27 In each case,
28 .I fd
29 refers to a
30 .IR /proc/ pid /ns/*
31 file.
32 Both operations return a new file descriptor on success.
33 .TP
34 .B NS_GET_USERNS
35 Returns a file descriptor that refers to the owning user namespace
36 for the namespace referred to by
37 .IR fd .
38 .TP
39 .B NS_GET_PARENT
40 Returns a file descriptor that refers to the parent namespace of
41 the namespace referred to by
42 .IR fd .
43 This operation is valid only for hierarchical namespaces
44 (i.e., PID and user namespaces).
45 For user namespaces,
46 .B NS_GET_PARENT
47 is synonymous with
48 .BR NS_GET_USERNS .
49 .P
50 The new file descriptor returned by these operations is opened with the
51 .B O_RDONLY
52 and
53 .B O_CLOEXEC
54 (close-on-exec;
55 see
56 .BR fcntl (2))
57 flags.
58 .P
59 By applying
60 .BR fstat (2)
61 to the returned file descriptor, one obtains a
62 .I stat
63 structure whose
64 .I st_dev
65 (resident device) and
66 .I st_ino
67 (inode number) fields together identify the owning/parent namespace.
68 This inode number can be matched with the inode number of another
69 .IR /proc/ pid /ns/ { pid , user }
70 file to determine whether that is the owning/parent namespace.
71 .SH RETURN VALUE
72 On success,
73 a file descriptor is returned.
74 Or error, \-1 is returned, and
75 .I errno
76 is set to indicate the error.
77 .SH ERRORS
78 .TP
79 .B EPERM
80 The requested namespace is outside of the caller's namespace scope.
81 This error can occur if, for example, the owning user namespace is an
82 ancestor of the caller's current user namespace.
83 It can also occur on attempts to obtain the parent of the initial
84 user or PID namespace.
85 .TP
86 .B ENOTTY
87 The operation is not supported by this kernel version.
88 .P
89 Additionally, the
90 .B NS_GET_PARENT
91 operation can fail with the following error:
92 .TP
93 .B EINVAL
94 .I fd
95 refers to a nonhierarchical namespace.
96 .SH STANDARDS
97 Linux.
98 .SH HISTORY
99 .TP
100 .B NS_GET_USERNS
101 .\" linux.git bcac25a58bfc6bd79191ac5d7afb49bea96da8c9
102 .\" linux.git 6786741dbf99e44fb0c0ed85a37582b8a26f1c3b
103 Linux 4.9.
104 .TP
105 .B NS_GET_PARENT
106 .\" linux.git a7306ed8d94af729ecef8b6e37506a1c6fc14788
107 Linux 4.9.
108 .SH EXAMPLES
109 The example shown below uses the
110 .BR ioctl (2)
111 operations described above to perform simple
112 discovery of namespace relationships.
113 The following shell sessions show various examples of the use
114 of this program.
115 .P
116 Trying to get the parent of the initial user namespace fails,
117 since it has no parent:
118 .P
119 .in +4n
120 .EX
121 .RB $ " ./ns_show /proc/self/ns/user p" ;
122 The parent namespace is outside your namespace scope
123 .EE
124 .in
125 .P
126 Create a process running
127 .BR sleep (1)
128 that resides in new user and UTS namespaces,
129 and show that the new UTS namespace is associated with the new user namespace:
130 .P
131 .in +4n
132 .EX
133 .RB $ " unshare \-Uu sleep 1000 &"
134 [1] 23235
135 .RB $ " ./ns_show /proc/23235/ns/uts u" ;
136 Device/Inode of owning user namespace is: [0,3] / 4026532448
137 .RB $ " readlink /proc/23235/ns/user" ;
138 user:[4026532448]
139 .EE
140 .in
141 .P
142 Then show that the parent of the new user namespace in the preceding
143 example is the initial user namespace:
144 .P
145 .in +4n
146 .EX
147 .RB $ " readlink /proc/self/ns/user" ;
148 user:[4026531837]
149 .RB $ " ./ns_show /proc/23235/ns/user p" ;
150 Device/Inode of parent namespace is: [0,3] / 4026531837
151 .EE
152 .in
153 .P
154 Start a shell in a new user namespace, and show that from within
155 this shell, the parent user namespace can't be discovered.
156 Similarly, the UTS namespace
157 (which is associated with the initial user namespace)
158 can't be discovered.
159 .P
160 .in +4n
161 .EX
162 .RB $ " PS1=\[dq]sh2$ \[dq] unshare \-U bash" ;
163 .RB sh2$ " ./ns_show /proc/self/ns/user p" ;
164 The parent namespace is outside your namespace scope
165 .RB sh2$ " ./ns_show /proc/self/ns/uts u" ;
166 The owning user namespace is outside your namespace scope
167 .EE
168 .in
169 .SS Program source
170 \&
171 .\" SRC BEGIN (ns_show.c)
172 .EX
173 /* ns_show.c
174 \&
175 Licensed under the GNU General Public License v2 or later.
176 */
177 #include <errno.h>
178 #include <fcntl.h>
179 #include <linux/nsfs.h>
180 #include <stdint.h>
181 #include <stdio.h>
182 #include <stdlib.h>
183 #include <string.h>
184 #include <sys/ioctl.h>
185 #include <sys/stat.h>
186 #include <sys/sysmacros.h>
187 #include <unistd.h>
188 \&
189 int
190 main(int argc, char *argv[])
191 {
192 int fd, userns_fd, parent_fd;
193 struct stat sb;
194 \&
195 if (argc < 2) {
196 fprintf(stderr, "Usage: %s /proc/[pid]/ns/[file] [p|u]\[rs]n",
197 argv[0]);
198 fprintf(stderr, "\[rs]nDisplay the result of one or both "
199 "of NS_GET_USERNS (u) or NS_GET_PARENT (p)\[rs]n"
200 "for the specified /proc/[pid]/ns/[file]. If neither "
201 "\[aq]p\[aq] nor \[aq]u\[aq] is specified,\[rs]n"
202 "NS_GET_USERNS is the default.\[rs]n");
203 exit(EXIT_FAILURE);
204 }
205 \&
206 /* Obtain a file descriptor for the \[aq]ns\[aq] file specified
207 in argv[1]. */
208 \&
209 fd = open(argv[1], O_RDONLY);
210 if (fd == \-1) {
211 perror("open");
212 exit(EXIT_FAILURE);
213 }
214 \&
215 /* Obtain a file descriptor for the owning user namespace and
216 then obtain and display the inode number of that namespace. */
217 \&
218 if (argc < 3 || strchr(argv[2], \[aq]u\[aq])) {
219 userns_fd = ioctl(fd, NS_GET_USERNS);
220 \&
221 if (userns_fd == \-1) {
222 if (errno == EPERM)
223 printf("The owning user namespace is outside "
224 "your namespace scope\[rs]n");
225 else
226 perror("ioctl\-NS_GET_USERNS");
227 exit(EXIT_FAILURE);
228 }
229 \&
230 if (fstat(userns_fd, &sb) == \-1) {
231 perror("fstat\-userns");
232 exit(EXIT_FAILURE);
233 }
234 printf("Device/Inode of owning user namespace is: "
235 "[%x,%x] / %ju\[rs]n",
236 major(sb.st_dev),
237 minor(sb.st_dev),
238 (uintmax_t) sb.st_ino);
239 \&
240 close(userns_fd);
241 }
242 \&
243 /* Obtain a file descriptor for the parent namespace and
244 then obtain and display the inode number of that namespace. */
245 \&
246 if (argc > 2 && strchr(argv[2], \[aq]p\[aq])) {
247 parent_fd = ioctl(fd, NS_GET_PARENT);
248 \&
249 if (parent_fd == \-1) {
250 if (errno == EINVAL)
251 printf("Can\[aq] get parent namespace of a "
252 "nonhierarchical namespace\[rs]n");
253 else if (errno == EPERM)
254 printf("The parent namespace is outside "
255 "your namespace scope\[rs]n");
256 else
257 perror("ioctl\-NS_GET_PARENT");
258 exit(EXIT_FAILURE);
259 }
260 \&
261 if (fstat(parent_fd, &sb) == \-1) {
262 perror("fstat\-parentns");
263 exit(EXIT_FAILURE);
264 }
265 printf("Device/Inode of parent namespace is: [%x,%x] / %ju\[rs]n",
266 major(sb.st_dev),
267 minor(sb.st_dev),
268 (uintmax_t) sb.st_ino);
269 \&
270 close(parent_fd);
271 }
272 \&
273 exit(EXIT_SUCCESS);
274 }
275 .EE
276 .\" SRC END
277 .SH SEE ALSO
278 .BR ioctl (2),
279 .BR ioctl_nsfs (2)