setns (BPX1SNS, BPX4SNS) — Reassociate thread with a namespace

Function

The setns service moves a process into an existing namespace. For namespaces other than PID namespaces, the current process is moved into the specified namespace as a result of the setns service. For PID namespaces, subsequent child processes that were created by the current process after the setns request are associated with the specified namespace.

For the macro, see BPXYCLNP— Map clone syscall parameters.

Requirements

Operation	Environment
Authorization	Supervisor state or problem state, any PSW key
Dispatchable unit mode	Task
Cross memory mode	PASN = HASN
AMODE (BPX1UNS)	31-bit
AMODE (BPX4UNS)	64-bit
ASC mode	Primary mode
Interrupt status	Enabled for interrupts
Locks	Unlocked
Control parameters	All parameters must be addressable by the caller and be in the primary address space.

Format

CALL BPX1SNS,(Ns_File_Descriptor,
                       Nstype,
                       Return value,
                       Return_code,
                       Reason_code)

AMODE 64 callers use BPX4SNS with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.

Parameters

Ns_File_Descriptor

Supplied parameter.

Type: Integer
Length: Fullword

The name of a fullword field that contains the file descriptor referring to the /proc[pid]/ns magic link (/pid, /mnt, /net, /ipc, /uts) for the specific namespace type.

Nstype

Supplied parameter.

Type: Integer
Length: Fullword

The name of a fullword field that specifies the type of namespace to which the calling process can be reassociated.

When the Ns_File_Descriptor refers to a /proc/[pid]/ns link, only a single flag that matches the namespace type referred to by the file descriptor or a 0 flag can be specified.

The flags are mapped by the CLONE_FLAGS structure in the BPXYCLNP macro. For more information, see BPXYCLNP— Map clone syscall parameters. The following flags are supported by the setns service:

Flag	Description
0	The process is reassociated into the namespace type that is associated with the input file descriptor.
CLONE_NEWIPC	Reassociate the process into the IPC namespace associated with the input file descriptor. If specified, Ns_File_Descriptor must refer to either an IPC link in the /proc/[pid]/ns directory.
CLONE_NEWNS	Reassociate the process into the mount namespace associated with the input file descriptor. If specified, Ns_File_Descriptor must refer to either a mount link in the /proc/[pid]/ns directory.
CLONE_NEWPID	Reassociate the process into the IPC namespace associated with the input file descriptor. If specified, Ns_File_Descriptor must refer to either a PID link in the /proc/[pid]/ns directory.
CLONE_NEWUTS	Reassociate the process into the UTS namespace associated with the input file descriptor. If specified, Ns_File_Descriptor must refer to either a UTS link in the /proc/[pid]/ns directory.

Return_value

Returned parameter.

Type: Integer
Length: Fullword

The name of a fullword in which the unshare service returns 0 if the request is successful or -1 if it is not successful.

Return_code

Returned parameter.

Type

Integer

Length

Fullword

The name of a fullword in which the unshare service stores the return code. The unshare service returns Return_code only if Process_ID is -1. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes A list of possible return codes follows.

Return_code	Explanation
EBADF	`Ns_File_Descriptor` is not valid.
EINVAL	One of the input parameters was not valid. The following reason code can accompany the return code: `JRUnsupportedFlag`.
ENOMEM	The process requires more space than is available.
ESRCH	The process referred to by the file descriptor no longer exists.
EPERM	The calling process does not have appropriate privileges. The user is not a superuser and is not permitted to the CONTAINERS resource in the UNIXPRIV class. The following reason code can accompany the return code: `JrNotAuthNameS`.
EAGAIN	The resources required to let another process be created are not available now or you have reached the maximum number of processes you are allowed to run. The following reason code can accompany the return code: `JrNoSecurityProduct`.
EMVSSAF2ERR	An error occurred in the security product. The following reason code can accompany the return code: `JrSAFInternal`.

Reason_code

Returned parameter.

Type: Integer
Length: Fullword
The name of a fullword in which the unshare service returns 0 if the request is successful, or -1 if it is not successful.

Usage notes

The setns service supports the following flags for the nstype parameter: CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWIPC, and CLONE_NEWUTS. Unsupported flags will result in the operation failing with an EINVAL error.
The caller must be authorized by being a superuser or having at least READ access to the CONTAINERS resource in the UNIXPRIV class.
For setns requests that specify CLONE_NEWNS, CLONE_NEWIPC, or CLONE_NEWUTS, the current process is moved into the namespace associated with the specified file descriptor. For setns requests that specify CLONE_NEWPID, the current process does not change its PID namespace. Instead, subsequent children of the calling process are associated with the PID namespace represented by the Ns_File_Descriptor.

Related services

Examples

For examples that use the setns callable service, see BPX1SNS (setns) example and BPX4SNS (setns) example.