setns

Setns is a Linux system call that re-associates the calling process with an existing namespace. By using a file descriptor that refers to a namespace instance, setns can cause the process to adopt the resources, identifiers, and behavior of that namespace. This mechanism is central to how containers and namespace tools move processes between different isolated environments.

The function signature is int setns(int fd, int nstype). The fd must reference a namespace, for example a file under /proc/[pid]/ns/ such as /proc/1234/ns/net. The nstype parameter is a bitmask of the namespace types to switch to, including types such as CLONE_NEWNS (mount), CLONE_NEWNET (network), CLONE_NEWPID (PID), CLONE_NEWIPC (IPC), CLONE_NEWUTS (UTS), CLONE_NEWUSER (user), and CLONE_NEWCGROUP (cgroup). On success, setns returns 0; on error, it returns -1 and sets errno.

Privileges and constraints apply to setns. The operation is permitted only if the process has the necessary capabilities (typically CAP_SYS_ADMIN) in the appropriate namespace context. The exact effect can vary by namespace type, and operations involving PID namespaces can alter the process’s view of PIDs. In practice, setns is a core primitive used by tools such as nsenter and by container runtimes to join or transfer processes into an existing namespace rather than creating a new one from scratch.

Related concepts include unshare, which creates new namespaces, and nsenter, which provides a user-facing way to invoke setns to join another process’s namespaces. setns plays a key role in flexible process isolation and orchestrated runtime environments.