_MEMCPY_WT()--Copy Memory With Tags for i5/OS PASE

 #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);

Note: These functions can only be used in an i5/OS PASE program. See i5/OS PASE for more information about creating i5/OS PASE 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 i5/OS PASE 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 i5/OS PASE 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 i5/OS exception message that the system converts to an i5/OS PASE signal. See i5/OS PASE Signal Handling for information about handling i5/OS exceptions.

Usage Notes

1. _MEMCPY_WT only copies between memory areas in the i5/OS PASE address space. _MEMCPY_WT2 can copy between any memory areas addressable through tagged space pointers, which need not be in the i5/OS PASE address space.
   
   
2. 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.
   
   
3. _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 i5/OS PASE
• _SETSPP()--Set Space Pointer for i5/OS PASE
• _SETSPPM()--Set Multiple Space Pointers for i5/OS PASE