Main Content

Represent Pointer Arguments in C Shared Library Functions

Pointer Arguments in C Functions

Many functions in external libraries pass arguments by reference. When you pass by reference, you pass a pointer to the value. In the function signature, pointer arguments have names ending in Ptr and PtrPtr. Although MATLAB® does not support passing by reference, you can create a MATLAB argument, called a lib.pointer object, that is compatible with a C pointer. This object is an instance of the MATLAB lib.pointer class.

Often, you can simply pass a MATLAB variable (passing an argument by value), even when the signature for that function declares the argument to be a pointer. There are times, however, when it is useful to pass a lib.pointer.

  • You want to modify the data in the input arguments.

  • You are passing large amounts of data, and you want to control when MATLAB makes copies of the data.

  • The library stores and uses the pointer so you want the MATLAB function to control the lifetime of the lib.pointer object.

Put String into Void Pointer

C represents characters as 8-bit integers. To use a MATLAB character array as an input argument, convert the string to the proper type and create a voidPtr. For example:

str = 'string variable';
vp = libpointer('voidPtr',[int8(str) 0]);

The syntax [int8(str) 0] creates the null-terminated string required by the C function. To read the string, and verify the pointer type, enter:

char(vp.Value)
vp.DataType
ans = 
string variable
ans = 
voidPtr

MATLAB automatically converts an argument passed by value into an argument passed by reference when the external function prototype defines the argument as a pointer. Call a function that takes a voidPtr to a string as an input argument using the following syntax. 

func_name([int8(str) 0])

Although MATLAB converts the argument from a value to a pointer, it must be of the correct type.

Memory Allocation for External Library

In general, MATLAB passes a valid memory address each time you pass a variable to a library function. Use a lib.pointer object in cases where the library stores the pointer and accesses the buffer over time. In these cases, ensure that MATLAB has control over the lifetime of the buffer and prevent copies of the data from being made. The following pseudo-code is an example of asynchronous data acquisition that shows how to use a lib.pointer in this situation.

Suppose an external library myLib has the following functions:

AcquireData(int points,short *buffer)
IsAquisitionDone(void)

where buffer is declared as follows:

short buffer[99]

First, create a lib.pointer to an array of 99 points:

BufferSize = 99;
pBuffer = libpointer('int16Ptr',zeros(BufferSize,1));

Then, begin acquiring data and wait in a loop until it is done:

calllib('myLib','AcquireData,BufferSize,pbuffer)
while (~calllib('myLib','IsAcquisitionDone')
  pause(0.1)
end

The following statement reads the data in the buffer:

result = pBuffer.Value;

When the library is done with the buffer, clear the MATLAB variable:

clear pBuffer

See Also