Calling Functions in Shared Libraries

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.

PlatformShared LibraryFile Extension

Microsoft® Windows®

dynamic link library file.dll

UNIX® and Linux®

shared object file.so

Apple Macintosh

dynamic shared library.dylib

A shared library needs a header file, which provides signatures for the functions in the library. A function signature, or 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.

You need an installed MATLAB-supported C compiler. For an up-to-date list of supported compilers, see the Supported and Compatible Compilers website.

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:

If the library function passes arguments, you need to determine the data passed to and from the function. For information about data, see:

When you are finished working with the shared library, it is important to unload the library to free memory.

For more information, see Limitations to Shared Library Support

Loading and Unloading the Library

To give MATLAB 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 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.

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

For example, load the libmx library that defines the MATLAB Matrix Library routines. The following command creates the full path for the library header file, matrix.h:

hfile = fullfile(matlabroot,'extern','include','matrix.h');

To load the library, type:

loadlibrary('libmx',hfile)

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

    Note:   If you call loadlibrary on a library that is already loaded, MATLAB displays a message, but does not reload the library. To determine if a library is loaded, use the libisloaded function.

Viewing Library Functions

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:

list = libfunctions('libmx','-full')

MATLAB displays (in part):

list = 

'[int32, MATLAB array, cstring] mxAddField(MATLAB array, cstring)'
'[cstring, MATLAB array] mxArrayToString(MATLAB array)'
'[uint64, MATLAB array, uint64Ptr] mxCalcSingleSubscript_730(
 MATLAB array, uint64, uint64Ptr)'
'lib.pointer mxCalloc(uint64, uint64)'
'[MATLAB array, uint64Ptr] mxCreateCellArray_730(uint64, uint64Ptr)'
'MATLAB array mxCreateCellMatrix_730(uint64, uint64)'
         .
         .
         .

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.

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, if required, 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)
ans =
    56

MATLAB displays the number of elements in the array.

Type:

calllib('libmx','mxGetClassID',y)
ans =
   mxDOUBLE_CLASS

MATLAB displays the class of the array.

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

Was this topic helpful?