uc_access(3) Library Functions Manual uc_access(3)
NAME
uc_access: __uc_get_ar(), __uc_get_ar_bsp(), __uc_get_ar_bspstore(), __uc_get_ar_ccv(), __uc_get_ar_csd(), __uc_get_ar_ec(),
__uc_get_ar_fpsr(), __uc_get_ar_lc(), __uc_get_ar_pfs(), __uc_get_ar_rsc(), __uc_get_ar_ssd(), __uc_get_ar_unat(), __uc_get_brs(),
__uc_get_cfm(), __uc_get_cr(), __uc_get_ed(), __uc_get_frs(), __uc_get_grs(), __uc_get_ip(), __uc_get_prs(), __uc_get_reason(),
__uc_get_rsebs(), __uc_get_rsebs64(), __uc_get_um(), __uc_set_ar(), __uc_set_ar_ccv(), __uc_set_ar_csd(), __uc_set_ar_ec(),
__uc_set_ar_fpsr(), __uc_set_ar_lc(), __uc_set_ar_pfs(), __uc_set_ar_rsc(), __uc_set_ar_ssd(), __uc_set_ar_unat(), __uc_set_brs(),
__uc_set_cfm(), __uc_set_ed(), __uc_set_frs(), __uc_set_grs(), __uc_set_ip(), __uc_set_prs(), __uc_set_rsebs(), __uc_set_rsebs64(),
__uc_set_um() - user context access (ucontext_t)
SYNOPSIS
Command: [flag]... file... [library]...
DESCRIPTION
The Ucontext Access interfaces allow an application to access the Integrity register state contained inside the opaque structure within the
user context structure.
In all these interfaces, is a pointer to a passed to the application as the third argument to a signal handler, allocated by the user and
filled in with or read from an application file.
Because a syscall occurs on a function call boundary, contexts created in a syscall omit scratch registers and other specific values as
detailed below.
To use any of these functions, link in the ucontext access library by specifying on the compiler or linker command line.
Individual Interface Descriptions
Returns (in the location referenced by the
argument) zero if the context was created in a syscall or a non-zero value if the context was created while handling an interrup-
tion that occurred while running user code.
Returns (in the
array) the saved values of the Static General Registers in the range through + inclusive, and (in the argument) the corresponding
NaT bit values. Only Static General Registers (GR1-GR31) may be read with this interface. Stacked General Registers
(GR32-GR127) must be read from the RSE backing store, or the RSE Backing Store overflow area. (See below.)
The NaT bits corresponding to the requested General Registers will be in the corresponding bits of NaT. For example, represents
the Nat Bit for GR5.
If the context was created in a syscall, scratch registers (GR2, GR3 and GR14-GR31) will read as
Overwrites the saved values of the Static General Registers in the range
through + inclusive, with the contents of the first elements of the array, and overwrites the corresponding NaT bits with bits
from the argument. Only Static General Registers (GR1-GR31) may be written with this interface. Stacked General Registers
(GR32-GR127) must be written to the RSE backing store, or the RSE Backing Store overflow area. (See below.)
The NaT bits corresponding to the specified General Registers must be in the corresponding bits of NaT. For example, the NaT bit
for GR5 will be overwritten with
If the context was created in a syscall, an attempt to write scratch registers (GR2, GR3 and GR14-GR31) will return
Returns (in the
array) the saved values of the Floating-Point Registers in the range through + inclusive.
If the context was created in a syscall, scratch registers (FR6-FR15 and FR32-FR127) will read as
Overwrites the saved values of the Floating-Point Registers in the range
through + inclusive, with the contents of the first elements of the array.
If the context was created in a syscall, an attempt to write scratch registers (FR6-FR15 and FR32-FR127) will return An attempt
to set bits {127:82} of an FP value will return
Returns (in the location referenced by the
argument) the saved values of the Predicate Registers.
If the context was created in a syscall, scratch predicates (PR6-PR15) will read as
Overwrites the saved values of the Predicate Registers with
If the context was created in a syscall, an attempt to set scratch predicates (PR6-PR15) will return
Attempts to clear PR[0] will be silently ignored.
Returns (in the
array) the saved values of the Branch Registers in the range through + inclusive.
If the context was created in a syscall, scratch registers (BR6-BR7) will read as
Overwrites the saved values of the Branch Registers in the range
through + inclusive, with the contents of the first elements of the array.
If the context was created in a syscall, an attempt to write scratch registers (BR6-BR7) will return
Returns (in the
argument) the saved value of the Instruction Pointer Register.
If the context was created while handling an interruption, will be that of the next instruction to execute. The instruction slot
will be indicated by a value of or in the low-order 2 bits of the For traps and interrupts, it will point to the next instruc-
tion. For faults, it will point to the faulting instruction. If the context was created in a syscall, will be the return
pointer from the system call. The low-order 2 bits of the will be
Overwrites the saved value of the Instruction Pointer Register with
If the context was created while handling an interruption, the instruction slot indicated by the 2 low-order bits of will be the
next instruction to execute. If the context was created in a syscall, an attempt to set the instruction slot to a non-zero value
will return
Returns (in the
argument) the saved value of the Current Frame Marker Register.
If the context was created in a syscall, will be the frame marker corresponding to the function that called the kernel.
Overwrites the saved value of the Current Frame Marker Register with
Returns (in the
argument) the saved value of the User Mask Register.
Overwrites the saved User Mask Register with
An attempt to set reserved bits will return
Returns (in the low-order bit of the
argument) the saved value of the Exception Deferral Bit. This bit is only saved in interruption contexts. An attempt to read it
from a context saved in a syscall will return
Overwrites the saved Exception Deferral Bit value with the low-order bit of the
specified. This bit is only saved in interruption contexts. An attempt to write it in a context saved in a syscall will return
An attempt to set it if CR.ISR.ED is not set will return
Returns (in the
argument) the saved value of the register.
Overwrites the saved value of the
register with
Returns (in the
argument) the saved value of the register. By convention, this value reflects the effects of the instruction used to enter a
syscall or the instruction used in handling an interruption. To find the value that will be in when the next instruction is exe-
cuted the caller must:
1) Call to determine whether the context was created in a syscall or while handling an interruption.
2) Call to fetch the current frame marker.
3) Adjust the value by (for a syscall context) or (for an interruption context).
Returns (in the
argument) the saved value of the register.
Returns (in the
argument) the saved value of the register. If the context was created in a syscall, the value is undefined.
Overwrites the saved value of the
register with If the context was created in a syscall, this call returns with no other side-effects.
Returns (in the
argument) the saved value of the register. If the context was created in a syscall, the value is undefined.
Overwrites the saved value of the
register with If the context was created in a syscall, this call returns with no other side-effects.
Returns (in the
argument) the saved value of the register. If the context was created in a syscall, the value is undefined.
Overwrites the saved value of the
register with If the context was created in a syscall, this call returns with no other side-effects.
Returns (in the
argument) the saved value of the register.
Overwrites the saved value of the
register with
Returns (in the
argument) the saved value of the register.
Overwrites the saved value of the
register with
Returns (in the
argument) the saved value of the register. In a syscall context, the value returned is undefined. Use to read the current frame
marker and to read the current epilog count.
Overwrites the saved value of the
register with If the context was created in a syscall, returns with no other side-effects.
Returns (in the
argument) the saved value of the register.
Overwrites the saved value of the
register with
Returns (in the
argument) the saved value of the register.
Overwrites the saved value of the
register with the low-order 6 bits of
Returns (in the
argument) the saved value of the Application Register specified by
Overwrites the saved value of the Application Register specified by
with
The following Application Registers may be specified:
+----+-------------+----+----+
|Reg |Register |Get |Set |
+----+-------------+----+----+
|16 |AR_RSC |X |X |
+----+-------------+----+----+
|17 |AR_BSP |X | |
+----+-------------+----+----+
|18 |AR_BSPSTORE |X |X |
+----+-------------+----+----+
|25 |AR_AR_CSD(*) |X |X |
+----+-------------+----+----+
|26 |AR_AR_SSD(*) |X |X |
+----+-------------+----+----+
|32 |AR_AR_CCV(*) |X |X |
+----+-------------+----+----+
|36 |AR_UNAT |X |X |
+----+-------------+----+----+
|40 |AR_FPSR |X |X |
+----+-------------+----+----+
|64 |AR_PFS(+) |X |X |
+----+-------------+----+----+
|65 |AR_LC |X |X |
+----+-------------+----+----+
|66 |AR_EC |X |X |
+----+-------------+----+----+
*
and are scratch registers. If the context was created in a syscall, it will read as 0. An attempt to write it will return
+ Note the caller should consult the unwind information for the function preceding the delivery of the signal to determine if the
register contained valid data.
Returns (in the
argument) the saved value of the Control Register specified by
The following Control Registers may be specified:
+----+---------+------------------------------------------------+
|Reg |Register |Notes |
+----+---------+------------------------------------------------+
|17 |CR_ISR | |
+----+---------+------------------------------------------------+
|20 |CR_IFA | Only valid for certain types of interruptions. |
+----+---------+------------------------------------------------+
|22 |CR_IIPA | |
+----+---------+------------------------------------------------+
If the context was created in a syscall, the control registers will
read as 0.
When a signal handler is invoked, the kernel attempts to write all dirty RSE
registers to the original RSE backing store. If it is unable to do this (that is, if the memory is not mapped) the kernel will
write remaining dirty registers to an overflow area within the These interfaces are provided to access those values saved in this
overflow area.
Use to fetch the and values.
+------------------------------------------+------------------------+
|If the address of the value you want is |Use |
+------------------------------------------+------------------------+
|addr < AR.BSPSTORE |direct read/write |
+------------------------------------------+------------------------+
|AR.BSPSTORE <= addr < AR.BSP |__uc_[gs]et_rsebs{64}() |
+------------------------------------------+------------------------+
|Special case for the last NaT collection: |__uc_[gs]et_rsebs{64}() |
|addr == AR.BSP | 0x1f8 | |
+------------------------------------------+------------------------+
The bits may be split between the value and the overflow area.
+--------------------------------------+-----------------------------------+
|Address |Where to find the NaT |
+--------------------------------------+-----------------------------------+
|addr < AR.BSPSTORE & ~0x1ff |direct read/write of backing store |
+--------------------------------------+-----------------------------------+
|AR.BSPSTORE & ~0x1ff <= addr < AR.BSP |__uc_[gs]et_rsebs{64}(addr|0x1f8) |
+--------------------------------------+-----------------------------------+
For 32-bit callers,
and will swizzle the addr argument.
are provided for 32-bit callers reading a generated within a 64-bit application. They differ from in that the addr argument will
not be swizzled. are only included in 32-bit versions of the library.
RETURN VALUE
Upon successful completion, all the interfaces return 0 to indicate success and return if passed invalid arguments.
ERRORS
The Ucontext Access interfaces will fail if any of the following conditions are encountered:
For any of the interfaces listed above, the
argument is NULL, or points to a with an invalid version or size.
For the or calls the range of registers specified by and included a value outside the range 1 to 31 inclusive.
For the call, was created by a syscall and the range of registers specified by and included a scratch register.
For the or calls the range of registers specified by and included a value outside the range 2 to 127 inclusive.
For the call, was created by a syscall and the range of registers specified by and included a scratch register or an attempt
is made to set bits {127:82} of an FP value.
For the call, was created by a syscall and included a set scratch bit or bits.
For the or calls the range of registers specified by and included a value outside the range 0 to 7 inclusive.
For the call, was created by a syscall and the range of registers specified by and included a scratch register.
For the call, was created by a syscall and the low-order two bits of are not zero, or was not created by a syscall and the
low-order two bits of are
For the call, bits outside the range 37:0 are set.
For the call, bits outside the range 5:1 are set.
For the or calls, a reserved field is non-zero.
For the or calls, an invalid register is specified.
For the call, specifies a valid register and includes reserved bits that are set.
For the or calls, was created in a system call.
For the call, includes bits set other than the low-order bit or the low-order bit is set and the saved CR.ISR.ED bit is
clear.
For the or calls, the range of memory locations specified by and includes values outside the range (inclusive) and (exclu-
sive) or if specifying the last NaT collection location, != 1
WARNINGS
Only minimal argument checking is performed. The caller must take care not to write invalid or out-of-range values to any register or reg-
ister field. The effects of returning from a signal handler or calling after overwriting any register with invalid or out-of-range values
are undefined.
is deprecated and should be used only by legacy applications. and are the recommended replacements.
is deprecated and should be used only by legacy applications. and are the recommended replacements. is deprecated and should be used only
by legacy applications.
AUTHOR
The UContext Access library was developed by HP.
FILES
Prototypes for the interfaces
SEE ALSO
getcontext(2), sigaction(2), core(4), signal(5), <ucontext.h>.
Integrity Systems Only uc_access(3)