loadlibrary :: Functions (MATLAB)

text://2

MATLAB

Provide feedback about this page

loadlibrary
Load shared library into MATLAB software

Syntax
loadlibrary('shrlib', 'hfile') loadlibrary('shrlib', @protofile) loadlibrary('shrlib', ..., 'options') loadlibrary shrlib hfile options [notfound, warnings] = loadlibrary('shrlib', 'hfile')

Description
loadlibrary('shrlib', 'hfile') loads the functions defined in header file hfile and found in shared library shrlib into MATLAB. The hfile and shrlib file names are case sensitive. The name you use in loadlibrary must use the same case as the file on your system. On Microsoft Windows systems, shrlib refers to the name of a dynamic link library (.dll) file. On Linux systems, it refers to the name of a shared object (.so) file. On Apple Macintosh systems, it refers to a dynamic shared library (.dylib). See File Extensions for Libraries for more information. 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). Note The MATLAB Generic Shared Library interface does not support library functions that have function pointer inputs.

File Extensions for Libraries

If you do not include a file extension with the shrlib argument, loadlibrary attempts to find the library with either the appropriate platform MEX-file extension or the appropriate platform library extension (usually .dll, .so, or .dylib). For a list of file extensions, see Binary MEX-File Extensions. 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 addheader hfileN

Description Loads the functions defined in the additional header file, hfileN. Note that each file specified by addheader must be referenced by a corresponding #include statement in the base header file. Specify the string hfileN as a file name without a file extension. MATLAB does not verify the existence of the header files and ignores any that are not needed. You can specify additional header files 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.

1 of 4

05/05/2009 12:03 p.m.

loadlibrary :: Functions (MATLAB)

text://2

Option includepath path mfilename mfile

Description Specifies an additional path in which to look for included header files. 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 following description of Prototype M-Files). Overrides the default thunk file name with tfile. For more information, see Using loadlibrary on 64-Bit Platforms.

thunkfilename tfile

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 file name, and load the additional libraries using the alias option. loadlibrary shrlib hfile options is the command format for this function. [notfound, warnings] = loadlibrary('shrlib', 'hfile') returns warning information from the shrlib library file. notfound is a cell array of the names of functions found in the header file hfile, or any header added with the addheader option, but not found in the shrlib library. warnings contains a single character array of warnings produced while processing the header file hfile.

Remarks
How to Use the addheader Option
The addheader option enables you to add functions for MATLAB to load from those listed in header files included in the base header file (with a #include statement). For example, if your library header file contains the statement: #include header2.h then to load the functions in header2.h, you need to use addheader in the call to loadlibrary: loadlibrary libname libname.h addheader header2.h You can use the addheader option with a header file that lists function prototypes for only the functions that are needed by your library, and thereby avoid loading functions that you do not define in your library. To do this, you might need to create a header file that contains a subset of the functions listed in large header file.

addheader Syntax
When using addheader to specify which functions to load, ensure that there are #include statements in the base header file for each additional header file in the loadlibrary call. For example, to use the following statement: loadlibrary mylib mylib.h addheader header2.h the file mylib.h must contain this statement: #include header2.h

Prototype M-Files
When you use the mfilename option with loadlibrary, MATLAB generates an M-file called a prototype file. Use this file 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.

2 of 4

05/05/2009 12:03 p.m.

loadlibrary :: Functions (MATLAB)

text://2

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.

Using loadlibrary on 64-Bit Platforms

You must install a C compiler to use loadlibrary on a 64-bit platform and Perl must be available. The supported compilers are shown in the following table.

64-bit Platform Windows Linux SunSolarisSPARC

Required Compiler Microsoft Visual C++ 2005 SP1 Version 8.0 Professional Edition gcc / g++ Version 4.1.1 Sun Studio 12 cc / CC Version 5.9

MATLAB generates a thunk file, which is a compatibility layer to your 64-bit library. The name of the thunk file is: BASENAME_thunk_COMPUTER.c where BASENAME is either the name of the shared library or the mfilename, if specified. COMPUTER is the string returned by the computer function. MATLAB compiles this file and creates the file: BASENAME_thunk_COMPUTER.LIBEXT where LIBEXT is the platform-dependent default shared library extension, for example, dll on Windows.

Examples
Load shrlibsample Example
Use loadlibrary to load the MATLAB sample shared library, shrlibsample: addpath([matlabroot '\extern\examples\shrlib']) loadlibrary shrlibsample shrlibsample.h

Using alias Example

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

Using addpath Example

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

3 of 4

05/05/2009 12:03 p.m.

loadlibrary :: Functions (MATLAB)

text://2

fullfile(matlabroot , 'extern', 'include'));

Using Prototype Example

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', 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', @mxproto) Now call mxGetNumberOfDimensions using the alias function name: y = rand(4, 7, 2); calllib('libmx', 'mxGetDims', y) ans = 3 unloadlibrary libmx

See Also
unloadlibrary, libisloaded, libfunctions,
Provide feedback about this page

load (serial)

loadobj

1984-2008 The MathWorks, Inc. Terms of Use Patents Trademarks Acknowledgments

4 of 4

05/05/2009 12:03 p.m.