Pass Pointers Examples

multDoubleRef Function

The multDoubleRef function in the shrlibsample library multiplies the input by 5.

EXPORTED_FUNCTION double *multDoubleRef(double *x) 
{
     *x *= 5;
     return x;
}

The input is a pointer to a double, and the function returns a pointer to a double. The MATLAB^® function signature is:

Return Type	Name	Arguments
[lib.pointer, doublePtr]	multDoubleRef	(doublePtr)

Pass Pointer of Type double

This example shows how to construct and pass a pointer to C function multDoubleRef.

Load the library containing the function.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
end

Construct a pointer, Xptr, to the input argument, X.

X = 13.3;
Xptr = libpointer('doublePtr',X);

Verify the contents of Xptr.

get(Xptr)

       Value: 13.3000
    DataType: 'doublePtr'

Call the function and check the results.

calllib('shrlibsample','multDoubleRef',Xptr);
Xptr.Value

ans = 
66.5000

Xptr is a handle object. Copies of this handle refer to the same underlying object and any operations you perform on a handle object affect all copies of that object. However, Xptr is not a C language pointer. Although it points to X, it does not contain the address of X. The function modifies the Value property of Xptr but does not modify the value in the underlying object X. The original value of X is unchanged.

X

X = 
13.3000

Create Pointer Offset from Existing lib.pointer Object

This example shows how to create a pointer to a subset of a MATLAB vector X. The new pointer is valid only as long as the original pointer exists.

Create a pointer to a vector.

X = 1:10;
xp = libpointer('doublePtr',X);
xp.Value

ans = 1×10

     1     2     3     4     5     6     7     8     9    10

Use the lib.pointer plus operator (+) to create a pointer to the last six elements of X.

xp2 = xp + 4;
xp2.Value

ans = 1×6

     5     6     7     8     9    10

Multilevel Pointers

Multilevel pointers are arguments that have more than one level of referencing. A multilevel pointer type in MATLAB uses the suffix PtrPtr. For example, use doublePtrPtr for the C argument double **.

When calling a function that takes a multilevel pointer argument, use a lib.pointer object and let MATLAB convert it to the multilevel pointer.

allocateStruct and deallocateStruct Functions

The allocateStruct function in the shrlibsample library takes a c_structPtrPtr argument.

EXPORTED_FUNCTION void allocateStruct(struct c_struct **val) 
{
    *val=(struct c_struct*) malloc(sizeof(struct c_struct));
    (*val)->p1 = 12.4;
    (*val)->p2 = 222;
    (*val)->p3 = 333333;
}

The MATLAB function signatures are:

Return Type	Name	Arguments
c_structPtrPtr	allocateStruct	(c_structPtrPtr)
voidPtr	deallocateStruct	(voidPtr)

Pass Multilevel Pointer

This example shows how to pass a multilevel pointer to a C function.

Load the library containing allocateStruct and deallocateStruct.

if not(libisloaded('shrlibsample'))
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
    loadlibrary('shrlibsample')
end

Create a c_structPtr pointer.

sp = libpointer('c_structPtr');

Call allocateStruct to allocate memory for the structure.

res = calllib('shrlibsample','allocateStruct',sp)

res = struct with fields:
    p1: 12.4000
    p2: 222
    p3: 333333

Free the memory created by the allocateStruct function.

calllib('shrlibsample','deallocateStruct',sp)

Return Array of Strings

Suppose that you have a library, myLib, with a function, acquireString, that reads an array of strings. The function signature is:

Return Type	Name	Arguments
char**	acquireString	(void)

char** acquireString(void)

The following pseudo-code shows how to manipulate the return value, an array of pointers to strings.

ptr = calllib(myLib,'acquireString')

MATLAB creates a lib.pointer object ptr of type stringPtrPtr. This object points to the first string. To view other strings, increment the pointer. For example, to display the first three strings, type:

for index = 0:2
    tempPtr = ptr + index;
    tempPtr.Value
end 

ans = 
    'str1'
ans = 
    'str2'
ans = 
    'str3'