loadlibrary (External Interfaces Reference)

Load external library into MATLAB

Syntax

loadlibrary('shrlib', 'hfile')
loadlibrary('shrlib', @protofile)
loadlibrary('shrlib', ..., 'options')
loadlibrary shrlib hfile options

Description

loadlibrary('shrlib', 'hfile') loads the functions defined in header file hfile and found in shared library shrlib into MATLAB. On Windows systems, shrlib refers to the name of a dynamic link library (.dll) file. On UNIX systems, it refers to the name of a shared object (.so) file.

loadlibrary('shrlib', @protofile) uses the prototype M-file protofile in place of a header file in loading the library shrlib. The string @protofile specifies a function handle to the prototype M-file. (See the description of "Prototype M-Files" below).

If you do not include a file extension with the shrlib argument, loadlibrary uses .dll or .so, depending on the platform you are using. If you do not include a file extension with the second argument, and this argument is not a function handle, loadlibrary uses .h for the extension.

loadlibrary('shrlib', ..., 'options') loads the library shrlib with one or more of the following options.

Option
Description

addheader hfileN

Loads the functions defined in the additional header file, hfileN. Specify the string hfileN as a filename without a file extension. MATLAB does not verify the existence of the header files and ignores any that are not needed.

You can specify as many additional header files as you need using the syntax

loadlibrary shrlib hfile ... addheader hfile1 ... addheader hfile2 ... % and so on

alias name
Associates the specified alias name with the library. All subsequent calls to MATLAB functions that reference this library must use this alias until the library is unloaded.

includepath path
Specifies an additional path in which to look for included header files.

mfilename mfile
Generates a prototype M-file mfile in the current directory. You can use this file in place of a header file when loading the library. (See the description of "Prototype M-Files" below).

Option	Description
`addheader` `hfileN`	Loads the functions defined in the additional header file, `hfileN`. Specify the string `hfileN` as a filename without a file extension. MATLAB does not verify the existence of the header files and ignores any that are not needed. You can specify as many additional header files as you need using the syntax loadlibrary shrlib hfile ... addheader hfile1 ... addheader hfile2 ... % and so on
`alias` `name`	Associates the specified alias `name` with the library. All subsequent calls to MATLAB functions that reference this library must use this alias until the library is unloaded.
`includepath` `path`	Specifies an additional `path` in which to look for included header files.
`mfilename` `mfile`	Generates a prototype M-file `mfile` in the current directory. You can use this file in place of a header file when loading the library. (See the description of "Prototype M-Files" below).

Only the alias option is available when loading using a prototype M-file.

If you have more than one library file of the same name, load the first using the library filename, and load the additional libraries using the alias option.

loadlibrary shrlib hfile options is the command format for this function.

Remarks

Prototype M-Files

When you use the mfilename option with loadlibrary, MATLAB generates an M-file called a prototype file. This file can then be used on subsequent calls to loadlibrary in place of a header file.

Like a header file, the prototype file supplies MATLAB with function prototype information for the library. You can make changes to the prototypes by editing this file and reloading the library.

Here are some reasons for using a prototype file, along with the changes you would need to make to the file:

You want to make temporary changes to signatures of the library functions.

Edit the prototype file, changing the fcns.LHS or fcns.RHS field for that function. This changes the types of arguments on the left hand side or right hand side, respectively.

You want to rename some of the library functions.

Edit the prototype file, defining the fcns.alias field for that function.

You expect to use only a small percentage of the functions in the library you are loading.

Edit the prototype file, commenting out the unused functions. This reduces the amount of memory required for the library.

You need to specify a number of include files when loading a particular library.

Specify the full list of include files (plus the mfilename option) in the first call to loadlibrary. This puts all the information from the include files into the prototype file. After that, specify just the prototype file.

Examples

Example 1

Use loadlibrary to load the MATLAB sample shared library, shrlibsample:

addpath([matlabroot '\extern\examples\shrlib'])
loadlibrary shrlibsample shrlibsample.h

Example 2

Load sample library shrlibsample, giving it an alias name of lib. Once you have set an alias, you need to use this name in all further interactions with the library for this session:

addpath([matlabroot '\extern\examples\shrlib'])
loadlibrary shrlibsample shrlibsample.h alias lib

libfunctionsview lib

str = 'This was a Mixed Case string';
calllib('lib', 'stringToUpper', str)
ans =
   THIS WAS A MIXED CASE STRING
unloadlibrary lib

Example 3

Load the library, specifying an additional path in which to search for included header files:

addpath([matlabroot '\extern\examples\shrlib'])
loadlibrary('shrlibsample','shrlibsample.h','includepath', ...
            fullfile(matlabroot , 'extern', 'include'));

Example 4

Load the libmx library and generate a prototype M-file containing the prototypes defined in header file matrix.h:

hfile = [matlabroot '\extern\include\matrix.h'];
loadlibrary('libmx.dll', hfile, 'mfilename', 'mxproto')

dir mxproto.m
   mxproto.m

Edit the generated file mxproto.m and locate the function 'mxGetNumberOfDimensions'. Give it an alias of 'mxGetDims' by adding this text to the line before fcnNum is incremented:

```
fcns.alias{fcnNum}='mxGetDims';
```

Here is the new function prototype. The change is shown in bold:

fcns.name{fcnNum}='mxGetNumberOfDimensions'; 
fcns.calltype{fcnNum}='cdecl';
fcns.LHS{fcnNum}='int32'; 
fcns.RHS{fcnNum}={'MATLAB array'};
fcns.alias{fcnNum}='mxGetDims'; % Alias defined
fcnNum=fcnNum+1; % Increment fcnNum

Unload the library and then reload it using the prototype M-file.

unloadlibrary libmx

loadlibrary('libmx.dll', @mxproto)

Now call mxGetNumberOfDimensions using the alias function name:

y = rand(4, 7, 2);

calllib('libmx', 'mxGetDims', y)
ans =
     3

unloadlibrary libmx

libstruct unloadlibrary