original/man2/setns.2

   1 .\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com>
   2 .\" Licensed under the GPLv2
   3 .\"
   4 .TH SETNS 2 2011-10-04 "Linux" "Linux Programmer's Manual"
   5 .SH NAME
   6 setns \- reassociate thread with a namespace
   7 .SH SYNOPSIS
   8 .nf
   9 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  10 .B #include <sched.h>
  11 .sp
  12 .BI "int setns(int " fd ", int " nstype );
  13 .fi
  14 .SH DESCRIPTION
  15 Given a file descriptor referring to a namespace,
  16 reassociate the calling thread with that namespace.
  17
  18 The
  19 .I fd
  20 argument is a file descriptor referring to one of the namespace entries in a
  21 .I /proc/[pid]/ns/
  22 directory; see
  23 .BR proc (5)
  24 for further information on
  25 .IR /proc/[pid]/ns/ .
  26 The calling thread will be reassociated with the corresponding namespace,
  27 subject to any constraints imposed by the
  28 .I nstype
  29 argument.
  30
  31 The
  32 .I nstype
  33 argument specifies which type of namespace
  34 the calling thread may be reassociated with.
  35 This argument can have one of the following values:
  36 .TP
  37 .BR 0
  38 Allow any type of namespace to be joined.
  39 .TP
  40 .BR CLONE_NEWIPC
  41 .I fd
  42 must refer to an IPC namespace.
  43 .TP
  44 .BR CLONE_NEWNET
  45 .I fd
  46 must refer to a network namespace.
  47 .TP
  48 .BR CLONE_NEWUTS
  49 .I fd
  50 must refer to a UTS namespace.
  51 .PP
  52 Specifying
  53 .I nstype
  54 as 0 suffices if the caller knows (or does not care)
  55 what type of namespace is referred to by
  56 .IR fd .
  57 Specifying a nonzero value for
  58 .I nstype
  59 is useful if the caller does not know what type of namespace is referred to by
  60 .IR fd
  61 and wants to ensure that the namespace is of a particular type.
  62 (The caller might not know the type of the namespace referred to by
  63 .IR fd
  64 if the file descriptor was opened by another process and, for example,
  65 passed to the caller via a UNIX domain socket.)
  66 .SH RETURN VALUE
  67 On success,
  68 .IR setns ()
  69 returns 0.
  70 On failure, \-1 is returned and
  71 .I errno
  72 is set to indicate the error.
  73 .SH ERRORS
  74 .TP
  75 .B EBADF
  76 .I fd
  77 is not a valid file descriptor.
  78 .TP
  79 .B EINVAL
  80 .I fd
  81 refers to a namespace whose type does not match that specified in
  82 .IR nstype ,
  83 or there is problem with reassociating the
  84 the thread with the specified namespace.
  85 .TP
  86 .B ENOMEM
  87 Cannot allocate sufficient memory to change the specified namespace.
  88 .TP
  89 .B EPERM
  90 The calling thread did not have the required privilege
  91 .RB ( CAP_SYS_ADMIN )
  92 for this operation.
  93 .SH VERSIONS
  94 The
  95 .BR setns ()
  96 system call first appeared in Linux in kernel 3.0
  97 .SH CONFORMING TO
  98 The
  99 .BR setns ()
 100 system call is Linux-specific.
 101 .SH NOTES
 102 Not all of the attributes that can be shared when
 103 a new thread is created using
 104 .BR clone (2)
 105 can be changed using
 106 .BR setns ().
 107 .SH BUGS
 108 The PID namespace and the mount namespace are not currently supported.
 109 (See the descriptions of
 110 .BR CLONE_NEWPID
 111 and
 112 .BR CLONE_NEWNS
 113 in
 114 .BR clone (2).)
 115 .SH SEE ALSO
 116 .BR clone (2),
 117 .BR fork (2),
 118 .BR vfork (2),
 119 .BR proc (5),
 120 .BR unix (7)