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
MicrosoftWindowsdynamic link library file.dll
UNIX[a] and Linux[b] shared object file.so
AppleMacintoshdynamic 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:

To call a library function, 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, 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.

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.

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)

Unloading the Library

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

unloadlibrary libmx

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:

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:

Figure: Methods of library libmx. Contains no critical information.

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 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.

  


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