Note: These functions can only be used in an IBM® i PASE
program. See the IBM PASE for i topic collection for more
information about creating IBM PASE for i programs.
The _SETSPP() function sets a tagged space pointer to the teraspace
equivalent of an IBM PASE for i memory address.
The _SETSPP_TS64() function sets a tagged space pointer to the memory identified by a 64-bit teraspace address.
Parameters
target
(Output) Pointer to a 16-byte aligned buffer where the tagged space pointer (or null pointer) is returned.
memory
(Input) Pointer containing either an IBM PASE for i memory address, or a null pointer (zero).
ts64
(Input) 64-bit teraspace address, or null (zero).
Authorities
_SETSPP and _SETSPP_TS64 require no authority.
Return Value
_SETSPP and _SETSPP_TS64 return no function result. A tagged space pointer
or 16-byte null pointer is returned in the target buffer.
Error Conditions
Any error is reported with an IBM i exception message that the system
converts to an IBM PASE for i signal. See IBM PASE for i
Signal Handling for information about handling IBM i exceptions.
Usage Notes
_SETSPP returns a 16-byte null pointer if the input IBM PASE for i
memory address is null (zero) or if a 64-bit memory value
points to a location that cannot contain IBM PASE for i memory. IBM PASE for i memory
is allocated from teraspace, but teraspace has a limited capacity smaller than
64-bits, so IBM PASE for i can only provide addressability to a subset of a 64-bit
address space.
_SETSPP_TS64 returns a 16-byte null pointer if the input
ts64 value is zero or outside the range of teraspace.
_SETSPP and _SETSPP_TS64 return target a space pointer regardless
of whether there is currently any memory at the target address.
A tagged space pointer to a teraspace location must only be used by the
process that owns the teraspace, although the current system implementation
does not reliably enforce this restriction. Applications must not assume that a
process can reference memory in the teraspace of another process because future
system implementations may make this impossible. Tagged space pointers to
teraspace memory that were either inherited by the child process of a fork or
stored in shared memory by another process should be considered unusable.
Tagged (16-byte) pointers must not be stored in memory mapped from a
bytestream file (by either mmap or shmat) although the current system
implementation does not reliably enforce this restriction. Tagged pointers can
be stored in shared memory objects (created by shmget and mapped by shmat), but
a tagged space pointer to teraspace memory cannot be reliably used by a process
other than the one that owns the teraspace.