MATLAB®

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.

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.

It is possible to call a Microsoft^® Visual Basic^® Version 6.0 DLL; however, you must create a C header file for the library. A Microsoft^® ActiveX^® interface might be simpler to use. See Introducing MATLAB COM Integration for more information.

Note   The MATLAB Interface to Shared Libraries does not support library functions that have function pointer inputs.

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:

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.

^[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