s390_guarded_storage(2) System Calls Manual s390_guarded_storage(2)
NAME
s390_guarded_storage - operations with z/Architecture guarded storage
facility
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <asm/guarded_storage.h> /* Definition of GS_* constants */
#include <sys/syscall.h> /* Definition of SYS_* constants */
#include <unistd.h>
int syscall(SYS_s390_guarded_storage, int command,
struct gs_cb *gs_cb);
Note: glibc provides no wrapper for s390_guarded_storage(), necessitat-
ing the use of syscall(2).
DESCRIPTION
The s390_guarded_storage() system call enables the use of the Guarded
Storage Facility (a z/Architecture-specific feature) for user-space
processes.
The guarded storage facility is a hardware feature that allows marking
up to 64 memory regions (as of z14) as guarded; reading a pointer with a
newly introduced "Load Guarded" (LGG) or "Load Logical and Shift
Guarded" (LLGFSG) instructions will cause a range check on the loaded
value and invoke a (previously set up) user-space handler if one of the
guarded regions is affected.
The command argument indicates which function to perform. The following
commands are supported:
GS_ENABLE
Enable the guarded storage facility for the calling task. The
initial content of the guarded storage control block will be all
zeros. After enablement, user-space code can use the "Load
Guarded Storage Controls" (LGSC) instruction (or the load_gs_cb()
function wrapper provided in the asm/guarded_storage.h header) to
load an arbitrary control block. While a task is enabled, the
kernel will save and restore the calling content of the guarded
storage registers on context switch.
GS_DISABLE
Disables the use of the guarded storage facility for the calling
task. The kernel will cease to save and restore the content of
the guarded storage registers, the task-specific content of these
registers is lost.
GS_SET_BC_CB
Set a broadcast guarded storage control block to the one provided
in the gs_cb argument. This is called per thread and associates
a specific guarded storage control block with the calling task.
This control block will be used in the broadcast command
GS_BROADCAST.
GS_CLEAR_BC_CB
Clears the broadcast guarded storage control block. The guarded
storage control block will no longer have the association estab-
lished by the GS_SET_BC_CB command.
GS_BROADCAST
Sends a broadcast to all thread siblings of the calling task.
Every sibling that has established a broadcast guarded storage
control block will load this control block and will be enabled
for guarded storage. The broadcast guarded storage control block
is consumed; a second broadcast without a refresh of the stored
control block with GS_SET_BC_CB will not have any effect.
The gs_cb argument specifies the address of a guarded storage control
block structure and is currently used only by the GS_SET_BC_CB command;
all other aforementioned commands ignore this argument.
RETURN VALUE
On success, the return value of s390_guarded_storage() is 0.
On error, -1 is returned, and errno is set to indicate the error.
ERRORS
EFAULT command was GS_SET_BC_CB and the copying of the guarded storage
control block structure pointed by the gs_cb argument has failed.
EINVAL The value provided in the command argument was not valid.
ENOMEM command was one of GS_ENABLE or GS_SET_BC_CB, and the allocation
of a new guarded storage control block has failed.
EOPNOTSUPP
The guarded storage facility is not supported by the hardware.
STANDARDS
Linux on s390.
HISTORY
Linux 4.12. System z14.
NOTES
The description of the guarded storage facility along with related in-
structions and Guarded Storage Control Block and Guarded Storage Event
Parameter List structure layouts is available in "z/Architecture Princi-
ples of Operations" beginning from the twelfth edition.
The gs_cb structure has a field gsepla (Guarded Storage Event Parameter
List Address), which is a user-space pointer to a Guarded Storage Event
Parameter List structure (that contains the address of the aforemen-
tioned event handler in the gseha field), and its layout is available as
a gs_epl structure type definition in the asm/guarded_storage.h header.
SEE ALSO
syscall(2)
Linux man-pages 6.9.1 2024-05-02 s390_guarded_storage(2)
Generated by dwww version 1.16 on Tue Dec 16 04:15:11 CET 2025.