Learn more about MATLAB

Calling Functions in Shared Libraries

On this page…
What Is a Shared Library? Loading the Library Unloading the Library Viewing Library Functions Invoking Library Functions Limitations to Shared Library Support

What Is a Shared Library?

A shared library is a collection of functions designed to be dynamically loaded by an application at run time. This MATLAB interface supports libraries containing functions programmed in any language, provided the functions have a C interface. MATLAB supports dynamic linking on all supported platforms.

Platform	Shared Library	File Extension
MicrosoftWindows	dynamic link library file	.dll
UNIX[a] and Linux[b]	shared object file	.so
AppleMacintosh	dynamic shared library	.dylib
[a] UNIX is a registered trademark of The Open Group in the United States and other countries. [b] Linux is a registered trademark of Linus Torvalds.

A shared library needs a header file, which provides signatures for the functions in the library. A signature, or function prototype, establishes the name of the function and the number and types of its parameters. You need to know the full path of the shared library and its header file.

MATLAB accesses C routines built into external, shared libraries through a command-line interface. This interface lets you load an external library into MATLAB memory and access functions in the library. Although types differ between the two language environments, in most cases you can pass types to the C functions without converting. MATLAB does this for you.

Details about using a shared library are in the topics:

• Loading the Library

• Viewing Library Functions

• Invoking Library Functions

To call a library function, you need to determine the data passed to and from the function. For information about data, see:

• Passing Arguments to Shared Library Functions

• Manually Converting Data Passed to Functions

• Working with Pointers

• Working with Structures

When you are finished working with the shared library, it is important to unload the library to free memory, as described in Unloading the Library.

For more information, see Limitations to Shared Library Support.

Back to Top

Loading the Library

To give MATLAB software access to functions in a shared library, you must first load the library into memory. After you load the library, you can request information about library functions and call them directly from the MATLAB command line. When you no longer need the library, unload it from memory to conserve memory usage.

To load a shared library into MATLAB, use the loadlibrary function. The most common syntax for loadlibrary is:

loadlibrary('shrlib', 'hfile')

where shrlib is the shared library file name, and hfile is the name of the header file containing the function prototypes. See the loadlibrary reference page for variations in the syntax and information on library file extensions.

Note   The header file provides signatures for the functions in the library and is a required argument for loadlibrary.

For example, you can use loadlibrary to load the libmx library that defines the MATLAB mx routines. The following command creates the full path for the library header file, matrix.h:

hfile = [matlabroot '\extern\include\matrix.h'];

To load the library, type:

loadlibrary('libmx', hfile)

Back to Top

Unloading the Library

Use the unloadlibrary function to unload the library and free up memory. For example:

unloadlibrary libmx

Back to Top

Viewing Library Functions

• Viewing Functions in the Command Window

• Viewing Functions in a GUI

Viewing Functions in the Command Window

Use the libfunctions command to display information about a library's functions in the MATLAB Command Window. For example, to see what functions are available in the libmx library, type:

if not(libisloaded('libmx'))
  hfile = [matlabroot '\extern\include\matrix.h'];
  loadlibrary('libmx', hfile);
end
libfunctions libmx

MATLAB displays (in part):

Functions in library libmx:

mxAddField                         mxGetScalar
mxArrayToString                    mxGetString_730
mxCalcSingleSubscript_730          mxGetUserBits
mxCalloc                           mxIsCell
mxCreateCellArray_730              mxIsChar
mxCreateCellMatrix_730             mxIsClass
       .                               .
       .                               .
       .                               .

To view function signatures, use the -full switch. This shows the MATLAB syntax for calling functions written in C. The types used in the argument lists and return values are MATLAB types, not C types. For more information on types, see C and MATLAB Equivalent Types. For example, at the command line enter:

libfunctions libmx -full

MATLAB displays (in part):

Functions in library libmx:

[int32, MATLAB array, cstring] mxAddField(MATLAB array, cstring)
[cstring, MATLAB array] mxArrayToString(MATLAB array)
lib.pointer mxCalloc(uint32, uint32)
[MATLAB array, uint32Ptr] mxCreateCellArray_730(uint32, uint32Ptr)
MATLAB array mxCreateCellMatrix_730(uint32, uint32)
[MATLAB array, uint32Ptr] mxCreateCharArray_730(uint32, uint32Ptr)
         .
         .
         .

Viewing Functions in a GUI

Use the libfunctionsview function to get information about functions in a library. MATLAB creates a new window to display the following information:

Heading	Description
Return Type	Types the method returns
Name	Function name
Arguments	Valid types for input arguments

To see the functions in the libmx library, type:

if not(libisloaded('libmx'))
  hfile = [matlabroot '\extern\include\matrix.h'];
  loadlibrary('libmx', hfile);
end
libfunctionsview libmx

MATLAB displays the following window:

The types used in the argument lists and return values are MATLAB types, not C types. For more information on types, see C and MATLAB Equivalent Types.

Back to Top

Invoking Library Functions

After loading a shared library into the MATLAB workspace, use the calllib function to call functions in the library. The syntax for calllib is:

calllib('libname', 'funcname', arg1, ..., argN)

You need to specify the library name, function name, and any arguments that get passed to the function.

The following example calls functions from the libmx library. To load the library, type:

if not(libisloaded('libmx'))
  hfile = [matlabroot '\extern\include\matrix.h'];
  loadlibrary('libmx', hfile);
end

To create an array y, type:

y = rand(4, 7, 2);

To get information about y, type:

calllib('libmx', 'mxGetNumberOfElements', y)

MATLAB displays the number of elements in the array:

ans =
    56

Type:

calllib('libmx', 'mxGetClassID', y)

MATLAB displays the class of the array:

ans =
   mxDOUBLE_CLASS

For information on how to define the argument types, see Passing Arguments to Shared Library Functions.

Back to Top

Limitations to Shared Library Support

The MATLAB shared library interface supports C library routines only. Most professionally-written libraries designed to be used by multiple languages and platforms work fine. Many homegrown libraries or libraries that have only been tested from C++ have interfaces that are not usable and require modification or an interface layer. In this case, we recommend using MEX-files, as described in Creating C Language MEX-Files.

Refer to the following topics for limitations to shared library support:

• Using C++ Libraries

• Using Bit Fields

• Using Enum Declarations

• Unions Not Supported

• Compiler Dependencies

• Limitations Using Structures

• Limitations Using Pointers

Using C++ Libraries

The shared library interface does not support C++ classes or overloaded functions elements.

If you need to load a library written in C++, all functions must be declared as extern "C". For example, the following function prototype from the file shrlibsample.h shows the syntax to use for each function:

#ifdef __cplusplus
extern "C" {
#endif
void addMixedTypes(
  short  x,
  int    y, 
  double z
);

/* other prototypes may be here */

#ifdef __cplusplus
}
#endif

The following C++ code is not legal C code for the header file:

extern "C" void addMixedTypes(short x, int y, double z); 

Using Bit Fields

You can modify a bit field declaration by using type int or an equivalent. For example, if your library has the following declared in its header file:

int myfunction();

struct mystructure
{
    /* note the sum of fields bits */
    unsigned field1 :4;
    unsigned field2 :4;
};

you can replace it with:

int myfunction();

struct mystructure
{
    /* field 8 bits wide to be manipulated in MATLAB */
    char allfields; /* A char is 8 bits on all supported platforms */
};

It is then possible to access the data in the two fields using bit masking in MATLAB.

Using Enum Declarations

char definitions for enum are not supported. In C a char constant ‘A' for instance is automatically converted to its numeric equivalent (65) but MATLAB does not do this so the header file must be modified first replacing ‘A' with the number 65 (int8(‘A') == 65). For example, replace:

enum Enum1 {ValA='A', ValB='B'};

with:

enum Enum1 {ValA=65, ValB=66};

Unions Not Supported

Unions are not supported. It may be possible to modify the source code taking out the union declaration and replacing it with the largest alternative, then writing MATLAB code to interpret the results as needed. For example, replace the following union:

struct mystruct
{
    union 
    {
        struct {char byte1,byte2;};
	       short word;
    };
};

with:

struct mystruct 
{
    short word;
};

where on a little-endian based machine, byte1 is mod(f,256), byte2 is f/256, and word=byte2*256+byte1.

Compiler Dependencies

Header files must be compatible with the supported compilers on a platform. For an up-to-date list of supported compilers, see the Supported and Compatible Compilers Web page. You cannot load external libraries with explicit dependencies on other compilers.

Limitations Using Structures

Nested structures or structures containing a pointer to a structure are not supported. However, MATLAB can access an array of structures created in an external library.

Limitations Using Pointers

Function Pointers.   The shared library interface does not support library functions that work with function pointers. If the functions accepts a NULL pointer, it is possible to call the function, but it may not be useful.

Multilevel Pointers.   Limited support for multilevel pointers and structures containing pointers. Using inputs and outputs and structure members declared with more then two levels of indirection is unsupported. For example, double ***outp translated to doublePtrPtrPtr is not supported.

---

^[a] UNIX is a registered trademark of The Open Group in the United States and other countries.

^[b] Linux is a registered trademark of Linus Torvalds.

Back to Top

MATLAB Interface to Shared Libraries

Passing Arguments to Shared Library Functions

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS