This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

Pass Pointers

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 TypeNameArguments

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'))

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

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

Verify the contents of Xptr.

       Value: 13.3000
    DataType: 'doublePtr'

Call the function and check the results.

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 = 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);
ans = 

     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;
ans = 

     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 TypeNameArguments
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'))

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.


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 TypeNameArguments
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;
ans = 
ans = 
ans = 

See Also

Was this topic helpful?