Main Content

Pass Arguments to Shared C Library Functions

C and MATLAB Equivalent Types

The shared library interface supports all standard scalar C types. The following table shows these C types with their equivalent MATLAB® types. MATLAB uses the type from the right column for arguments having the C type shown in the left column.

Note

All scalar values returned by MATLAB are of type double.

MATLAB Primitive Types

C TypeEquivalent MATLAB Type

char, byte

int8

unsigned char, byte

uint8

short

int16

unsigned short

uint16

int

int32

long (Windows®)

int32,
long

long (Linux®)

int64,
long

unsigned int

uint32

unsigned long (Windows)

uint32,
long

unsigned long (Linux)

uint64,
long

float

single

double

double

char *

char array (1xn)

*char[]

cell array of character vectors

The following table shows how MATLAB maps C pointers (column 1) to the equivalent MATLAB function signature (column 2). Usually, you can pass a variable from the Equivalent MATLAB Type column to functions with the corresponding Argument Data Type. See Pointer Arguments in C Functions for information about when to use a lib.pointer object instead.

MATLAB Extended Types

C Pointer TypeArgument
Data Type		Equivalent
MATLAB Type

Example Function in
Shared Library shrlibsample

double *

doublePtr

doubleaddDoubleRef

float *

singlePtr

single 

intsize * (integer pointer types)

(u)int(size)Ptr
For example, int64 * becomes int64Ptr.

(u)int(size)multiplyShort

byte[]

int8Ptr

int8 

char[] (null-terminated string passed by value)

cstring

char array (1xn)

stringToUpper

char ** (array of pointers to strings)

stringPtrPtr

cell array of character vectors

 
enum

enumPtr

  

type **

typePtrPtr
For example, double **
becomes doublePtrPtr.

lib.pointer object

allocateStruct

void *

voidPtr

 deallocateStruct

void **

voidPtrPtr

lib.pointer object

 

struct (C-style structure)

structure

MATLAB struct

addStructFields

mxArray *

MATLAB array

MATLAB array

 

mxArray **

MATLAB arrayPtr

lib.pointer object

 

How MATLAB Displays Function Signatures

Here are things to note about the input and output arguments shown in MATLAB function signatures.

  • Many arguments (like int32 and double) are similar to their C counterparts. In these cases, pass in the MATLAB types shown for these arguments.

  • Some C arguments (for example, **double, or predefined structures), are different from standard MATLAB types. In these cases, either pass a standard MATLAB type and let MATLAB convert it for you, or convert the data yourself using the MATLAB functions libstruct and libpointer. For more information, see Manually Convert Data Passed to Functions.

  • C functions often return data in input arguments passed by reference. MATLAB creates additional output arguments to return these values. Input arguments ending in Ptr or PtrPtr are also listed as outputs.

For an example of MATLAB function signatures, see Shared Library shrlibsample.

Guidelines for Passing Arguments

  • Nonscalar arguments must be declared as passed by reference in the library functions.

  • If the library function uses single subscript indexing to reference a two-dimensional matrix, keep in mind that C programs process matrices row by row. MATLAB processes matrices by column. To get C behavior from the function, transpose the input matrix before calling the function, and then transpose the function output.

  • Use an empty array, [], to pass a NULL parameter to a library function that supports optional input arguments. This notation is valid only when the argument is declared as a Ptr or PtrPtr as shown by libfunctions or libfunctionsview.

NULL Pointer

You can create a NULL pointer to pass to library functions in the following ways:

  • Pass an empty array [] as the argument.

  • Use the libpointer function:

    p = libpointer; % no arguments 
    p = libpointer('string') % string argument
    p = libpointer('cstring') % pointer to a string argument

  • Use the libstruct function:

    p = libstruct('structtype'); % structure type

Empty libstruct Object

To create an empty libstruct object, call libstruct with only the structtype argument. For example:

sci = libstruct('c_struct')
get(sci)
    p1: 0
    p2: 0
    p3: 0

MATLAB displays the initialized values.

Manually Convert Data Passed to Functions

Under most conditions, MATLAB software automatically converts data passed to and from external library functions to the type expected by the external function. However, you might choose to convert your argument data manually. For example:

  • When passing the same data to a series of library functions, convert it once manually before calling the first function rather than having MATLAB convert it automatically on every call. This strategy reduces the number of unnecessary copy and conversion operations.

  • When passing large structures, save memory by creating MATLAB structures that match the shape of the C structures used in the function instead of using generic MATLAB structures. The libstruct function creates a MATLAB structure modeled from a C structure taken from the library.

  • When an argument to an external function uses more than one level of referencing (for example, double **), pass a pointer created using the libpointer function rather than relying on MATLAB to convert the type automatically.

See Also

| | |

Related Examples

More About