unshare (BPX1UNS, BPX4UNS) — Run program in a new namespace

Function

The unshare service disassociates a process from each namespace whose type is specified by the Flags parameter and moves it into a newly created namespace. For namespaces other than PID namespaces, the current process is moved into the new namespace as a result of the unshare service. For PID namespaces, the first child that is created after the unshare request by the current process is created in a new PID namespace. Subsequent children of the same calling process are also associated with this new PID 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 in the primary address space.

Format


CALL BPX1UNS,(Flags,
              Return value, 
              Return_code,
              Reason_code)

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

Parameters

Flags

Supplied parameter.

Type: Integer
Length: Fullword

The name of a fullword field that specifies which namespaces are to be disassociated by the process and a new namespace created. The flags are mapped by the CLONE_FLAGS structure that is contained within the BPXYCLNP macro. For more information, see BPXYCLNP— Map clone syscall parameters.

Zero or more of the following supported flags can be specified on the unshare service.

Flag	Description
0	No-op. No changes are made.
CLONE_NEWIPC	Unshare the process from the IPC namespace and move into a new IPC namespace.
CLONE_NEWNS	Unshare the process from the mount namespace and move into a new mount namespace.
CLONE_NEWPID	Unshare the PID namespace so the subsequent child of the current process will create a new PID namespace.
CLONE_NEWUTS	Unshare the process from the UTS namespace and move into a new UTS namespace.

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
EINVAL	An input parameter was not valid. The following reason code can accompany the return code: `JRUnsupportedFlag`, `JrMultiProc`, `JrMultiPidUnshares`.
ENOSPC	A system limit was reached. The limit on the number of namespaces would be exceeded. Creating a new PID namespace as requested by CLONE_NEWPID would cause the nesting depth limit of PID namespaces to be exceeded. The following reason code can accompany the return code: `JRMaxNamespace`, `JrMaxNamespaceNestin`.
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.
EAGAIN	The resources required to let another process be created are not available or you have reached the maximum number of processes that you can 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.

Reason_code

Returned parameter.

Type: Integer
Length: Fullword

The name of a fullword in which the unshare service stores the reason code. The unshare service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_value. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.

Usage notes for unshare

When the input flags specified are zero, the unshare is treated as a no-op, and will indicate success on return.
Flags that are supported by unshare are CLONE_NEWNS, CLONE_NEWPID, CLONE_NEWIPC, and CLONE_NEWUTS. Any other flag will result in the operation failing with an EINVAL error.
When the unshare requests the process to be moved to one or more new namespaces (nonzero unshare flags specified), the caller must be authorized by being a superuser or have at least READ access to the CONTAINERS resource in the UNIXPRIV class.
For unshare syscalls that specify a flag (CLONE_NEWNS, CLONE_NEWIPC, and CLONE_NEWUTS), the requested namespace is created and the current process is moved into the new namespace after the syscall completes. For unshare syscalls that specify the CLONE_NEWPID flag, the new PID namespace is not immediately created and the current process never changes namespaces. Instead, a new PID namespace is created when the first subsequent child of the calling process is created. Any additional child processes of the calling process is created in the namespace that was created by the first child after the unshare syscall.

Related services

Examples

For examples that use the unshare callable service, see BPX1UNS (unshare) example and BPX4UNS (unshare) example.

Characteristics and restrictions

Following is a list of characteristics or restrictions for the unshare service:

There is a limit on the maximum number of namespaces (all types combined). It is set to one half of the maximum process limit. It is a static limit that is not affected by any changes that are made to MAXPROCSYS.
PID namespaces can be nested, thus forming a hierarchical tree. There is a limit to the nesting depth of PID namespaces set to four namespaces levels underneath the root namespace.
A process can only perform the unshare operation once. Subsequent unshare Clone_Newpid or clone Clone_Newpid requests will result in a failure.