aboutsummaryrefslogtreecommitdiffstats
path: root/man/man2const
diff options
context:
space:
mode:
authorAlejandro Colomar <alx@kernel.org>2024-06-11 02:18:22 +0200
committerAlejandro Colomar <alx@kernel.org>2024-06-13 23:54:51 +0200
commita660bbdd85ebf434f36df0004e88a1abcc63a804 (patch)
treefe829283ff555431c359b8197354254ec2a00a4b /man/man2const
parent38658f54478947ec7ed8f86bdf787c32cb78822a (diff)
parent2f857efc374e1c52a2084c77bf52b06ac371b129 (diff)
downloadman-pages-a660bbdd85ebf434f36df0004e88a1abcc63a804.tar.gz
ioctl_ns.2, ioctl_nsfs.2: Rename page, and make sashimi
Diffstat (limited to 'man/man2const')
-rw-r--r--man/man2const/NS_GET_NSTYPE.2const50
-rw-r--r--man/man2const/NS_GET_OWNER_UID.2const52
-rw-r--r--man/man2const/NS_GET_PARENT.2const1
-rw-r--r--man/man2const/NS_GET_USERNS.2const278
4 files changed, 381 insertions, 0 deletions
diff --git a/man/man2const/NS_GET_NSTYPE.2const b/man/man2const/NS_GET_NSTYPE.2const
new file mode 100644
index 0000000000..5208fe214d
--- /dev/null
+++ b/man/man2const/NS_GET_NSTYPE.2const
@@ -0,0 +1,50 @@
+.\" Copyright 2017, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH NS_GET_NSTYPE 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+NS_GET_NSTYPE
+\-
+discovering the namespace type
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/nsfs.h>" " /* Definition of " NS_GET_NSTYPE " */"
+.B #include <sys/ioctl.h>
+.P
+.BI "int ioctl(int " fd ", NS_GET_NSTYPE);"
+.fi
+.SH DESCRIPTION
+The
+.B NS_GET_NSTYPE
+operation can be used to discover
+the type of namespace referred to by the file descriptor
+.IR fd .
+.P
+.I fd
+refers to a
+.IR /proc/ pid /ns/*
+file.
+.SH RETURN VALUE
+On success,
+the return value is one of the
+.B CLONE_NEW*
+values that can be specified to
+.BR clone (2)
+or
+.BR unshare (2)
+in order to create a namespace.
+.P
+On error,
+\-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 4.11.
+.\" linux.git e5ff5ce6e20ee22511398bb31fb912466cf82a36
+.SH SEE ALSO
+.BR ioctl (2),
+.BR ioctl_nsfs (2)
diff --git a/man/man2const/NS_GET_OWNER_UID.2const b/man/man2const/NS_GET_OWNER_UID.2const
new file mode 100644
index 0000000000..f64d607bb4
--- /dev/null
+++ b/man/man2const/NS_GET_OWNER_UID.2const
@@ -0,0 +1,52 @@
+.\" Copyright 2017, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH NS_GET_OWNER_UID 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+NS_GET_OWNER_UID
+\-
+discovering the owner of a user namespace
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/nsfs.h>" " /* Definition of " NS_GET_OWNER_UID " */"
+.B #include <sys/ioctl.h>
+.P
+.BI "int ioctl(int " fd ", NS_GET_OWNER_UID, uid_t *" uid );
+.fi
+.SH DESCRIPTION
+The
+.B NS_GET_OWNER_UID
+operation can be used to discover
+the owner user ID of a user namespace (i.e., the effective user ID
+of the process that created the user namespace).
+.P
+.I fd
+refers to a
+.IR /proc/ pid /ns/user
+file.
+.P
+The owner user ID is returned in the
+.I uid_t
+pointed to by the third argument.
+.SH RETURN VALUE
+On success,
+0 is returned.
+On error,
+\-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I fd
+does not refer to a user namespace.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 4.11.
+.\" linux.git 015bb305b8ebe8d601a238ab70ebdc394c7a19ba
+.SH SEE ALSO
+.BR ioctl (2),
+.BR ioctl_nsfs (2)
diff --git a/man/man2const/NS_GET_PARENT.2const b/man/man2const/NS_GET_PARENT.2const
new file mode 100644
index 0000000000..3144fb463f
--- /dev/null
+++ b/man/man2const/NS_GET_PARENT.2const
@@ -0,0 +1 @@
+.so man2const/NS_GET_USERNS.2const
diff --git a/man/man2const/NS_GET_USERNS.2const b/man/man2const/NS_GET_USERNS.2const
new file mode 100644
index 0000000000..68a2b45dcf
--- /dev/null
+++ b/man/man2const/NS_GET_USERNS.2const
@@ -0,0 +1,278 @@
+.\" Copyright 2017, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH NS_GET_USERNS 2const (date) "Linux man-pages (unreleased)"
+.SH NAME
+NS_GET_USERNS,
+NS_GET_PARENT
+\-
+discovering namespace relationships
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/nsfs.h>" " /* Definition of " NS_GET_* " constants */"
+.B #include <sys/ioctl.h>
+.P
+.BI "int ioctl(int " fd ", unsigned long " op );
+.fi
+.SH DESCRIPTION
+The following
+.BR ioctl (2)
+operations are provided to allow discovery of namespace relationships (see
+.BR user_namespaces (7)
+and
+.BR pid_namespaces (7)).
+.P
+In each case,
+.I fd
+refers to a
+.IR /proc/ pid /ns/*
+file.
+Both operations return a new file descriptor on success.
+.TP
+.B NS_GET_USERNS
+Returns a file descriptor that refers to the owning user namespace
+for the namespace referred to by
+.IR fd .
+.TP
+.B NS_GET_PARENT
+Returns a file descriptor that refers to the parent namespace of
+the namespace referred to by
+.IR fd .
+This operation is valid only for hierarchical namespaces
+(i.e., PID and user namespaces).
+For user namespaces,
+.B NS_GET_PARENT
+is synonymous with
+.BR NS_GET_USERNS .
+.P
+The new file descriptor returned by these operations is opened with the
+.B O_RDONLY
+and
+.B O_CLOEXEC
+(close-on-exec; see
+.BR fcntl (2))
+flags.
+.P
+By applying
+.BR fstat (2)
+to the returned file descriptor, one obtains a
+.I stat
+structure whose
+.I st_dev
+(resident device) and
+.I st_ino
+(inode number) fields together identify the owning/parent namespace.
+This inode number can be matched with the inode number of another
+.IR /proc/ pid /ns/ { pid , user }
+file to determine whether that is the owning/parent namespace.
+.SH RETURN VALUE
+On success,
+a file descriptor is returned.
+Or error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EPERM
+The requested namespace is outside of the caller's namespace scope.
+This error can occur if, for example, the owning user namespace is an
+ancestor of the caller's current user namespace.
+It can also occur on attempts to obtain the parent of the initial
+user or PID namespace.
+.TP
+.B ENOTTY
+The operation is not supported by this kernel version.
+.P
+Additionally, the
+.B NS_GET_PARENT
+operation can fail with the following error:
+.TP
+.B EINVAL
+.I fd
+refers to a nonhierarchical namespace.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+.TP
+.B NS_GET_USERNS
+.\" linux.git bcac25a58bfc6bd79191ac5d7afb49bea96da8c9
+.\" linux.git 6786741dbf99e44fb0c0ed85a37582b8a26f1c3b
+Linux 4.9.
+.TP
+.B NS_GET_PARENT
+.\" linux.git a7306ed8d94af729ecef8b6e37506a1c6fc14788
+Linux 4.9.
+.SH EXAMPLES
+The example shown below uses the
+.BR ioctl (2)
+operations described above to perform simple
+discovery of namespace relationships.
+The following shell sessions show various examples of the use
+of this program.
+.P
+Trying to get the parent of the initial user namespace fails,
+since it has no parent:
+.P
+.in +4n
+.EX
+$ \fB./ns_show /proc/self/ns/user p\fP
+The parent namespace is outside your namespace scope
+.EE
+.in
+.P
+Create a process running
+.BR sleep (1)
+that resides in new user and UTS namespaces,
+and show that the new UTS namespace is associated with the new user namespace:
+.P
+.in +4n
+.EX
+$ \fBunshare \-Uu sleep 1000 &\fP
+[1] 23235
+$ \fB./ns_show /proc/23235/ns/uts u\fP
+Device/Inode of owning user namespace is: [0,3] / 4026532448
+$ \fBreadlink /proc/23235/ns/user\fP
+user:[4026532448]
+.EE
+.in
+.P
+Then show that the parent of the new user namespace in the preceding
+example is the initial user namespace:
+.P
+.in +4n
+.EX
+$ \fBreadlink /proc/self/ns/user\fP
+user:[4026531837]
+$ \fB./ns_show /proc/23235/ns/user p\fP
+Device/Inode of parent namespace is: [0,3] / 4026531837
+.EE
+.in
+.P
+Start a shell in a new user namespace, and show that from within
+this shell, the parent user namespace can't be discovered.
+Similarly, the UTS namespace
+(which is associated with the initial user namespace)
+can't be discovered.
+.P
+.in +4n
+.EX
+$ \fBPS1="sh2$ " unshare \-U bash\fP
+sh2$ \fB./ns_show /proc/self/ns/user p\fP
+The parent namespace is outside your namespace scope
+sh2$ \fB./ns_show /proc/self/ns/uts u\fP
+The owning user namespace is outside your namespace scope
+.EE
+.in
+.SS Program source
+\&
+.\" SRC BEGIN (ns_show.c)
+.EX
+/* ns_show.c
+\&
+ Licensed under the GNU General Public License v2 or later.
+*/
+#include <errno.h>
+#include <fcntl.h>
+#include <linux/nsfs.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
+#include <sys/sysmacros.h>
+#include <unistd.h>
+\&
+int
+main(int argc, char *argv[])
+{
+ int fd, userns_fd, parent_fd;
+ struct stat sb;
+\&
+ if (argc < 2) {
+ fprintf(stderr, "Usage: %s /proc/[pid]/ns/[file] [p|u]\en",
+ argv[0]);
+ fprintf(stderr, "\enDisplay the result of one or both "
+ "of NS_GET_USERNS (u) or NS_GET_PARENT (p)\en"
+ "for the specified /proc/[pid]/ns/[file]. If neither "
+ "\[aq]p\[aq] nor \[aq]u\[aq] is specified,\en"
+ "NS_GET_USERNS is the default.\en");
+ exit(EXIT_FAILURE);
+ }
+\&
+ /* Obtain a file descriptor for the \[aq]ns\[aq] file specified
+ in argv[1]. */
+\&
+ fd = open(argv[1], O_RDONLY);
+ if (fd == \-1) {
+ perror("open");
+ exit(EXIT_FAILURE);
+ }
+\&
+ /* Obtain a file descriptor for the owning user namespace and
+ then obtain and display the inode number of that namespace. */
+\&
+ if (argc < 3 || strchr(argv[2], \[aq]u\[aq])) {
+ userns_fd = ioctl(fd, NS_GET_USERNS);
+\&
+ if (userns_fd == \-1) {
+ if (errno == EPERM)
+ printf("The owning user namespace is outside "
+ "your namespace scope\en");
+ else
+ perror("ioctl\-NS_GET_USERNS");
+ exit(EXIT_FAILURE);
+ }
+\&
+ if (fstat(userns_fd, &sb) == \-1) {
+ perror("fstat\-userns");
+ exit(EXIT_FAILURE);
+ }
+ printf("Device/Inode of owning user namespace is: "
+ "[%x,%x] / %ju\en",
+ major(sb.st_dev),
+ minor(sb.st_dev),
+ (uintmax_t) sb.st_ino);
+\&
+ close(userns_fd);
+ }
+\&
+ /* Obtain a file descriptor for the parent namespace and
+ then obtain and display the inode number of that namespace. */
+\&
+ if (argc > 2 && strchr(argv[2], \[aq]p\[aq])) {
+ parent_fd = ioctl(fd, NS_GET_PARENT);
+\&
+ if (parent_fd == \-1) {
+ if (errno == EINVAL)
+ printf("Can\[aq] get parent namespace of a "
+ "nonhierarchical namespace\en");
+ else if (errno == EPERM)
+ printf("The parent namespace is outside "
+ "your namespace scope\en");
+ else
+ perror("ioctl\-NS_GET_PARENT");
+ exit(EXIT_FAILURE);
+ }
+\&
+ if (fstat(parent_fd, &sb) == \-1) {
+ perror("fstat\-parentns");
+ exit(EXIT_FAILURE);
+ }
+ printf("Device/Inode of parent namespace is: [%x,%x] / %ju\en",
+ major(sb.st_dev),
+ minor(sb.st_dev),
+ (uintmax_t) sb.st_ino);
+\&
+ close(parent_fd);
+ }
+\&
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR ioctl (2),
+.BR ioctl_nsfs (2)
generated by cgit 1.2.3-korg (git 2.43.0) at 2025-11-30 15:56:02 +0000