_MEMCPY_WT() and _MEMCPY_WT2()--Copy Memory With Tags for IBM PASE for i
Syntax
#include <as400_protos.h> void* _MEMCPY_WT(void *target, const void *source, size_t length); void _MEMCPY_WT2(const ILEpointer *target, const ILEpointer *source, size_t length);
Default Public Authority: *USE
Library: Standard C Library (libc.a)
Threadsafe: Yes
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 _MEMCPY_WT() and _MEMCPY_WT2() functions copy memory without destroying 16-byte tagged pointers.
Standard memory copy functions such as memcpy never produce a usable tagged pointer in the target memory. _MEMCPY_WT and _MEMCPY_WT2 copy memory in a way that preserves the integrity of any complete (16-byte) tagged pointers copied, as long as the source and target have the same alignment with respect to a 16-byte boundary.
Parameters
- target
- (Output) Pointer to target memory. For _MEMCPY_WT, target is the IBM PASE for i
address of the target memory. For _MEMCPY_WT2, target is the 16-byte
aligned address of a tagged space pointer to the target memory.
- source
- (Input) Pointer to source memory. For _MEMCPY_WT, source is the IBM PASE for i
address of the source memory. For _MEMCPY_WT2, source is the 16-byte aligned
address of a tagged space pointer to the source memory.
- length
- (Input) Specifies the number of bytes to copy between the source and
target.
Authorities
_MEMCPY_WT and _MEMCPY_WT2 require no authority.
Return Value
_MEMCPY_WT returns the target memory address. _MEMCPY_WT2 returns no function result.
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
- _MEMCPY_WT only copies between memory areas in the IBM PASE for i address
space. _MEMCPY_WT2 can copy between any memory areas addressable through tagged
space pointers, which need not be in the IBM PASE for i address space.
- Memory is copied without error if the source and target do not have the
same alignment with respect to a 16-byte boundary or if only part of a tagged
pointer is copied, but the target will not contain a usable tagged pointer.
- _MEMCPY_WT and _MEMCPY_WT2 are implemented with kernel system calls, so
they generally run slower than memcpy.
Related Information
- _CVTSPP()--Convert Space Pointer for IBM PASE for i
- _SETSPP() and _SETSPP_TS64()--Set Space Pointer for IBM PASE for i
- _SETSPPM()--Set Multiple Space Pointers for IBM PASE for i
API introduced: V4R5