man-pages/man2/setns.2

.\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com>
.\" Licensed under the GPLv2
.\"
.TH SETNS 2 2012-05-04 "Linux" "Linux Programmer's Manual"
.SH NAME
setns \- reassociate thread with a namespace
.SH SYNOPSIS
.nf
.BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
.B #include <sched.h>
.sp
.BI "int setns(int " fd ", int " nstype );
.fi
.SH DESCRIPTION
Given a file descriptor referring to a namespace,
reassociate the calling thread with that namespace.

The
.I fd
argument is a file descriptor referring to one of the namespace entries in a
.I /proc/[pid]/ns/
directory; see
.BR proc (5)
for further information on
.IR /proc/[pid]/ns/ .
The calling thread will be reassociated with the corresponding namespace,
subject to any constraints imposed by the
.I nstype
argument.

The
.I nstype
argument specifies which type of namespace
the calling thread may be reassociated with.
This argument can have one of the following values:
.TP
.BR 0
Allow any type of namespace to be joined.
.TP
.BR CLONE_NEWIPC
.I fd
must refer to an IPC namespace.
.TP
.BR CLONE_NEWNET
.I fd
must refer to a network namespace.
.TP
.BR CLONE_NEWUTS
.I fd
must refer to a UTS namespace.
.PP
Specifying
.I nstype
as 0 suffices if the caller knows (or does not care)
what type of namespace is referred to by
.IR fd .
Specifying a nonzero value for
.I nstype
is useful if the caller does not know what type of namespace is referred to by
.IR fd
and wants to ensure that the namespace is of a particular type.
(The caller might not know the type of the namespace referred to by
.IR fd
if the file descriptor was opened by another process and, for example,
passed to the caller via a UNIX domain socket.)
.SH RETURN VALUE
On success,
.IR setns ()
returns 0.
On failure, \-1 is returned and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EBADF
.I fd
is not a valid file descriptor.
.TP
.B EINVAL
.I fd
refers to a namespace whose type does not match that specified in
.IR nstype ,
or there is problem with reassociating the
the thread with the specified namespace.
.TP
.B ENOMEM
Cannot allocate sufficient memory to change the specified namespace.
.TP
.B EPERM
The calling thread did not have the required privilege
.RB ( CAP_SYS_ADMIN )
for this operation.
.SH VERSIONS
The
.BR setns ()
system call first appeared in Linux in kernel 3.0;
library support was added to glibc in version 2.14.
.SH CONFORMING TO
The
.BR setns ()
system call is Linux-specific.
.SH NOTES
Not all of the attributes that can be shared when
a new thread is created using
.BR clone (2)
can be changed using
.BR setns ().
.SH BUGS
The PID namespace and the mount namespace are not currently supported.
(See the descriptions of
.BR CLONE_NEWPID
and
.BR CLONE_NEWNS
in
.BR clone (2).)
.SH SEE ALSO
.BR clone (2),
.BR fork (2),
.BR vfork (2),
.BR proc (5),
.BR unix (7)