|On this page…|
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|
|dynamic link library file||.dll|
UNIX® and Linux®
|shared object file||.so|
|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
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:
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:
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.
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)' . . .
Use the libfunctionsview function to get information about functions in a library. MATLAB creates a new window to display the following information:
Types the method returns
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.
After loading a shared library into the MATLAB workspace, use the calllib function to call functions in the library. The syntax for calllib is:
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:
ans = 56
MATLAB displays the number of elements in the array.
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.