MATLAB Function Reference

libpointer - Create pointer object for use with external libraries

Syntax

p = libpointer
p = libpointer('type')
p = libpointer('type',value)

Description

p = libpointer returns an empty (void) pointer.

p = libpointer('type') returns an empty pointer that contains a reference to the specified data type. This type can be any MATLAB^® numeric type, or a structure or enumerated type defined in an external library that has been loaded into MATLAB with the loadlibrary function. For valid types, see the table under Primitive Types in the MATLAB External Interfaces documentation.

Note   Using this syntax, p is a NULL pointer. You, therefore, must ensure that any library function to which you pass p must be able to accept a NULL pointer as an argument.

p = libpointer('type',value) returns a pointer to the specified data type and initialized to the value supplied.

Remarks

MATLAB automatically converts data passed to and from external library functions to the data type expected by the external function. The libpointer function enables you to convert your argument data manually. This is an advanced feature available to experienced C programmers. For more information about using pointer objects, see Creating References in the MATLAB External Interfaces documentation. Additional examples for using libpointer can be found in Reference Pointers in the same documentation.

Examples

This example passes an int16 pointer to a function that multiplies each value in a matrix by its index. The function multiplyShort is defined in the MATLAB sample shared library, shrlibsample.

Here is the C function:

void multiplyShort(short *x, int size)
{
    int i;
    for (i = 0; i < size; i++)
    *x++ *= i;
}

Load the shrlibsample library. Create the matrix, v, and also a pointer to it, pv:

addpath([matlabroot '\extern\examples\shrlib'])
loadlibrary shrlibsample shrlibsample.h

v = [4 6 8; 7 5 3];

pv = libpointer('int16Ptr', v);
get(pv, 'Value')
ans =
     4     6     8
     7     5     3

Now call the C function in the library, passing the pointer to v. If you were to pass a copy of v, the results would be lost once the function terminates. Passing a pointer to v enables you to get back the results:

calllib('shrlibsample', 'multiplyShort', pv, 6);
get(pv, 'Value')
ans =
     0    12    32
     7    15    15

unloadlibrary shrlibsample

See Also

loadlibrary, libfunctions, libfunctionsview, libstruct, calllib, libisloaded, unloadlibrary

libisloaded

libstruct