original/man2/setns.2

   1 .\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com>
   2 .\" and Copyright (C) 2011, 2012, Michael Kerrisk <mtk.manpages@gamil.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2_ONELINE)
   5 .\" Licensed under the GPLv2
   6 .\" %%%LICENSE_END
   7 .\"
   8 .TH SETNS 2 2013-01-01 "Linux" "Linux Programmer's Manual"
   9 .SH NAME
  10 setns \- reassociate thread with a namespace
  11 .SH SYNOPSIS
  12 .nf
  13 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  14 .B #include <sched.h>
  15 .sp
  16 .BI "int setns(int " fd ", int " nstype );
  17 .fi
  18 .SH DESCRIPTION
  19 Given a file descriptor referring to a namespace,
  20 reassociate the calling thread with that namespace.
  21
  22 The
  23 .I fd
  24 argument is a file descriptor referring to one of the namespace entries in a
  25 .I /proc/[pid]/ns/
  26 directory; see
  27 .BR proc (5)
  28 for further information on
  29 .IR /proc/[pid]/ns/ .
  30 The calling thread will be reassociated with the corresponding namespace,
  31 subject to any constraints imposed by the
  32 .I nstype
  33 argument.
  34
  35 The
  36 .I nstype
  37 argument specifies which type of namespace
  38 the calling thread may be reassociated with.
  39 This argument can have one of the following values:
  40 .TP
  41 .BR 0
  42 Allow any type of namespace to be joined.
  43 .TP
  44 .BR CLONE_NEWIPC
  45 .I fd
  46 must refer to an IPC namespace.
  47 .TP
  48 .BR CLONE_NEWNET
  49 .I fd
  50 must refer to a network namespace.
  51 .TP
  52 .BR CLONE_NEWUTS
  53 .I fd
  54 must refer to a UTS namespace.
  55 .PP
  56 Specifying
  57 .I nstype
  58 as 0 suffices if the caller knows (or does not care)
  59 what type of namespace is referred to by
  60 .IR fd .
  61 Specifying a nonzero value for
  62 .I nstype
  63 is useful if the caller does not know what type of namespace is referred to by
  64 .IR fd
  65 and wants to ensure that the namespace is of a particular type.
  66 (The caller might not know the type of the namespace referred to by
  67 .IR fd
  68 if the file descriptor was opened by another process and, for example,
  69 passed to the caller via a UNIX domain socket.)
  70 .SH RETURN VALUE
  71 On success,
  72 .IR setns ()
  73 returns 0.
  74 On failure, \-1 is returned and
  75 .I errno
  76 is set to indicate the error.
  77 .SH ERRORS
  78 .TP
  79 .B EBADF
  80 .I fd
  81 is not a valid file descriptor.
  82 .TP
  83 .B EINVAL
  84 .I fd
  85 refers to a namespace whose type does not match that specified in
  86 .IR nstype ,
  87 or there is problem with reassociating the
  88 the thread with the specified namespace.
  89 .TP
  90 .B ENOMEM
  91 Cannot allocate sufficient memory to change the specified namespace.
  92 .TP
  93 .B EPERM
  94 The calling thread did not have the required privilege
  95 .RB ( CAP_SYS_ADMIN )
  96 for this operation.
  97 .SH VERSIONS
  98 The
  99 .BR setns ()
 100 system call first appeared in Linux in kernel 3.0;
 101 library support was added to glibc in version 2.14.
 102 .SH CONFORMING TO
 103 The
 104 .BR setns ()
 105 system call is Linux-specific.
 106 .SH NOTES
 107 Not all of the attributes that can be shared when
 108 a new thread is created using
 109 .BR clone (2)
 110 can be changed using
 111 .BR setns ().
 112 .SH EXAMPLE
 113 The program below takes two or more arguments.
 114 The first argument specifies the pathname of a namespace file in an existing
 115 .I /proc/[pid]/ns/
 116 directory.
 117 The remaining arguments specify a command and its arguments.
 118 The program opens the namespace file, joins that namespace using
 119 .BR setns (),
 120 and executes the specified command inside that namespace.
 121
 122 The following shell session demonstrates the use of this program
 123 (compiled as a binary named
 124 .IR ns_exec )
 125 in conjunction with the
 126 .BR CLONE_NEWUTS
 127 example program in the
 128 .BR clone (2)
 129 man page (complied as a binary named
 130 .IR newuts ).
 131
 132 We begin by executing the example program in
 133 .BR clone (2)
 134 in the background.
 135 That program creates a child in a separate UTS namespace.
 136 The child changes the hostname in its namespace,
 137 and then both processes display the hostnames in their UTS namespaces,
 138 so that we can see that they are different.
 139
 140 .nf
 141 .in +4n
 142 $ \fBsu\fP                   # Need privilege for namespace operations
 143 Password:
 144 # \fB./newuts bizarro &\fP
 145 [1] 3549
 146 clone() returned 3550
 147 uts.nodename in child:  bizarro
 148 uts.nodename in parent: antero
 149 # \fBuname \-n\fP             # Verify hostname in the shell
 150 antero
 151 .in
 152 .fi
 153
 154 We then run the program shown below,
 155 using it to execute a shell.
 156 Inside that shell, we verify that the hostname is the one
 157 set by the child created by the first program:
 158
 159 .nf
 160 .in +4n
 161 # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP
 162 # \fBuname \-n\fP             # Executed in shell started by ns_exec
 163 bizarro
 164 .in
 165 .fi
 166 .SS Program source
 167 .nf
 168 #define _GNU_SOURCE
 169 #include <fcntl.h>
 170 #include <sched.h>
 171 #include <unistd.h>
 172 #include <stdlib.h>
 173 #include <stdio.h>
 174
 175 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 176                         } while (0)
 177
 178 int
 179 main(int argc, char *argv[])
 180 {
 181     int fd;
 182
 183     if (argc < 3) {
 184         fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\\n", argv[0]);
 185         exit(EXIT_FAILURE);
 186     }
 187
 188     fd = open(argv[1], O_RDONLY);   /* Get descriptor for namespace */
 189     if (fd == \-1)
 190         errExit("open");
 191
 192     if (setns(fd, 0) == \-1)         /* Join that namespace */
 193         errExit("setns");
 194
 195     execvp(argv[2], &argv[2]);      /* Execute a command in namespace */
 196     errExit("execvp");
 197 }
 198 .fi
 199 .SH SEE ALSO
 200 .BR clone (2),
 201 .BR fork (2),
 202 .BR vfork (2),
 203 .BR proc (5),
 204 .BR unix (7)
 205 .SH COLOPHON
 206 This page is part of release 3.68 of the Linux
 207 .I man-pages
 208 project.
 209 A description of the project,
 210 information about reporting bugs,
 211 and the latest version of this page,
 212 can be found at
 213 \%http://www.kernel.org/doc/man\-pages/.