1ioctl_ns(2)                   System Calls Manual                  ioctl_ns(2)
2
3
4

NAME

6       ioctl_ns - ioctl() operations for Linux namespaces
7

DESCRIPTION

9   Discovering namespace relationships
10       The  following  ioctl(2)  operations are provided to allow discovery of
11       namespace relationships (see user_namespaces(7) and pid_namespaces(7)).
12       The form of the calls is:
13
14           new_fd = ioctl(fd, request);
15
16       In  each case, fd refers to a /proc/pid/ns/* file.  Both operations re‐
17       turn a new file descriptor on success.
18
19       NS_GET_USERNS (since Linux 4.9)
20              Returns a file descriptor that refers to the owning  user  name‐
21              space for the namespace referred to by fd.
22
23       NS_GET_PARENT (since Linux 4.9)
24              Returns a file descriptor that refers to the parent namespace of
25              the namespace referred to by fd.  This operation is  valid  only
26              for  hierarchical  namespaces  (i.e.,  PID and user namespaces).
27              For  user   namespaces,   NS_GET_PARENT   is   synonymous   with
28              NS_GET_USERNS.
29
30       The new file descriptor returned by these operations is opened with the
31       O_RDONLY and O_CLOEXEC (close-on-exec; see fcntl(2)) flags.
32
33       By applying fstat(2) to the returned file  descriptor,  one  obtains  a
34       stat structure whose st_dev (resident device) and st_ino (inode number)
35       fields together identify the owning/parent namespace.  This inode  num‐
36       ber    can    be   matched   with   the   inode   number   of   another
37       /proc/pid/ns/{pid,user} file to determine  whether  that  is  the  own‐
38       ing/parent namespace.
39
40       Either of these ioctl(2) operations can fail with the following errors:
41
42       EPERM  The  requested  namespace  is  outside of the caller's namespace
43              scope.  This error can occur if, for example,  the  owning  user
44              namespace is an ancestor of the caller's current user namespace.
45              It can also occur on attempts to obtain the parent of  the  ini‐
46              tial user or PID namespace.
47
48       ENOTTY The operation is not supported by this kernel version.
49
50       Additionally,  the  NS_GET_PARENT operation can fail with the following
51       error:
52
53       EINVAL fd refers to a nonhierarchical namespace.
54
55       See the EXAMPLES section for an example of the use of these operations.
56
57   Discovering the namespace type
58       The NS_GET_NSTYPE operation (available since Linux 4.11) can be used to
59       discover the type of namespace referred to by the file descriptor fd:
60
61           nstype = ioctl(fd, NS_GET_NSTYPE);
62
63       fd refers to a /proc/pid/ns/* file.
64
65       The  return value is one of the CLONE_NEW* values that can be specified
66       to clone(2) or unshare(2) in order to create a namespace.
67
68   Discovering the owner of a user namespace
69       The NS_GET_OWNER_UID operation (available since Linux 4.11) can be used
70       to  discover the owner user ID of a user namespace (i.e., the effective
71       user ID of the process that created the user namespace).  The  form  of
72       the call is:
73
74           uid_t uid;
75           ioctl(fd, NS_GET_OWNER_UID, &uid);