_MEMCPY_WT() and _MEMCPY_WT2()--Copy Memory With Tags for IBM PASE for i

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

1. _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.
   
   
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 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

[ Back to top | IBM PASE for i APIs | APIs by category ]