Main Content

loadlibrary

C 共有ライブラリを MATLAB に読み込む

説明

loadlibrary(libname,hfile) は、ヘッダー ファイル hfile に定義されている C 共有ライブラリ libname から関数を MATLAB® に読み込みます。関数 loadlibrary は C から呼び出せる関数および C コンパイラによって解析可能なヘッダー ファイルの呼び出しのみをサポートします。C++ で記述された関数は extern "C" として宣言しなければなりません。あるいは、C++ ライブラリの関数を呼び出すには、MATLAB からの C++ の呼び出しを参照してください。

ヘッダー ファイルの名前がライブラリ ファイルの名前と同じである場合、loadlibrary(libname) はライブラリを読み込みます。

loadlibrary(libname,hfile,Name,Value) は、1 つ以上の Name,Value 引数のペアをもつライブラリを読み込みます。

loadlibrary(libname,@protofile) は、ヘッダー ファイルの代わりにプロトタイプ ファイル protofile を使用します。

[notfound,warnings] = loadlibrary(___) は警告情報を返し、前述の構文の任意の入力引数を含むことができます。

すべて折りたたむ

examples フォルダーへのパスを追加します。

addpath(fullfile(matlabroot,'extern','examples','shrlib'))

ライブラリ内の関数を表示します。

if not(libisloaded('shrlibsample'))
    loadlibrary('shrlibsample')
end
libfunctions('shrlibsample')
Functions in library shrlibsample:

addDoubleRef              addMixedTypes             addStructByRef            addStructFields           allocateStruct            deallocateStruct          exportedDoubleValue       getListOfStrings          multDoubleArray           multDoubleRef             multiplyShort             print2darray              printExportedDoubleValue  readEnum                  stringToUpper             

クリーンアップします。

unloadlibrary shrlibsample

mylib ライブラリとヘッダー ファイル mylib.h があるとします。ヘッダー ファイルにはステートメントとして #include header2.h が含まれています。header2.h で定義されている関数を使用するには、addheader オプションを使用して loadlibrary を呼び出します。

loadlibrary('mylib','mylib.h','addheader','header2')
if libisloaded('shrlibsample')
    unloadlibrary('shrlibsample')
else
    addpath(fullfile(matlabroot,'extern','examples','shrlib'))
end

shrlibsample ライブラリに lib というエイリアス名を作成します。

loadlibrary('shrlibsample','shrlibsample.h','alias','lib')

このエイリアス名を使用して関数 stringToUpper を呼び出します。

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

クリーンアップします。

unloadlibrary lib

shrlibsample とそのヘッダー ファイル shrlibsample.h を含むフォルダーへのパスを追加します。

addpath(fullfile(matlabroot,'extern','examples','shrlib'))

ヘッダー ファイル shrlibsample.h にはヘッダー ファイル shrhelp.h が含まれています。shrhelp.hc:\work などの別のフォルダーにある場合、'includepath' オプションを使用して、MATLAB にファイルの場所を示します。

loadlibrary('shrlibsample','shrlibsample.h','includepath','c:\work')

クリーンアップします。

unloadlibrary shrlibsample

次の例では、MATLAB shrlibsample ライブラリの関数名 addMixedTypes をエイリアス名 addTypes に置き換える方法を説明します。エイリアス名を定義するには、プロトタイプ ファイルを作成してから、このファイルをヘッダー ファイルに使用してライブラリを読み込みます。

書き込み権限のあるフォルダーを使用します。

cd('c:\work')

プロトタイプ ファイル mxproto.m を作成します。

hfile = fullfile(matlabroot,'extern','examples','shrlib','shrlibsample.h');
[notfound,warnings] = loadlibrary('shrlibsample',hfile,'mfilename','mxproto')

MATLAB によって、現在のフォルダーにプロトタイプ ファイルが作成されます。警告メッセージは無視してください。

プロトタイプ ファイルにエイリアス名を追加します。MATLAB エディターでファイルを開きます。

edit mxproto.m

関数 addMixedTypes を検索します。

次のステートメントは、エイリアス addTypes を割り当てます。

fcns.alias{fcnNum}='addTypes';

このステートメントを、fcnNum をインクリメントするステートメントの前の行に追加します。新しい関数プロトタイプは以下のようになります (新たに追加したステートメントを太字で表記)。

%  double addMixedTypes ( short , int , double ); 
fcns.thunkname{fcnNum}='doubleint16int32doubleThunk';
fcns.name{fcnNum}='addMixedTypes'; 
fcns.calltype{fcnNum}='Thunk'; 
fcns.LHS{fcnNum}='double'; 
fcns.RHS{fcnNum}={'int16', 'int32', 'double'};
fcns.alias{fcnNum}='addTypes'; % Alias defined
fcnNum=fcnNum+1; % Increment fcnNum

プロトタイプ ファイルを使用して shrlibsample を再び読み込みます。

unloadlibrary shrlibsample
loadlibrary('shrlibsample',@mxproto)

エイリアス名を使用して関数を呼び出します。

calllib('shrlibsample','addTypes',int16(127),int32(33000),pi)
ans = 3.3130e+04

クリーンアップします。

unloadlibrary shrlibsample

入力引数

すべて折りたたむ

共有ライブラリの名前。文字ベクトルとして指定します。名前の大文字と小文字は区別され、システム上のファイルと一致しなければなりません。

Microsoft® Windows® システムでは、libname は共有ライブラリ (.dll) ファイルの名前を参照します。Linux® システムでは、共有オブジェクト (.so) ファイルの名前を参照します。Apple Mac システムでは、動的共有ライブラリ (.dylib) を参照します。libname の引数にファイル拡張子を含めない場合、関数 loadlibrary は、適切なプラットフォームの MEX ファイル拡張子または適切なプラットフォームのライブラリ拡張子のいずれかでライブラリを見つけようとします。MEX ファイル拡張子のリストは、mexext を使用してください。

MATLAB は libname の名前の部分を抽出して、他の共有ライブラリ関数のライブラリを識別します。たとえば、関数 calllib を呼び出すときに、ライブラリの引数名にパスやファイルの拡張子を含めないでください。

データ型: char

C ヘッダー ファイルの名前。文字ベクトルとして指定します。名前の大文字と小文字は区別され、システム上のファイルと一致しなければなりません。ファイル名にファイル拡張子を含めない場合は、loadlibrary は拡張子として .h を使用します。

データ型: char

プロトタイプ ファイルの名前。文字ベクトルとして指定します。名前は大文字と小文字が区別され、システム上のファイルと一致しなければなりません。@protofile は、プロトタイプ ファイルへの関数ハンドルを指定します。プロトタイプ ファイルを使用する場合、唯一有効な Name,Value の引数ペアは alias です。

データ型: char

名前と値の引数

引数のオプションのペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後になければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、コンマを使用してそれぞれの名前と値を区切り、Name を引用符で囲みます。

例: loadlibrary('mylib','mylib.h','addheader','header2')

ヘッダー ファイル。'addheader' と文字ベクトルから成るコンマ区切りのペアとして指定します。ファイル名をファイル拡張子なしで指定します。

addheader で指定された各ファイルでは、対応する #include ステートメントがベース ヘッダー ファイル内に含まれていなければなりません。ヘッダー ファイルで定義された、MATLAB で使用する関数のみを読み込むには、addheader を使用します。

MATLAB は複数のヘッダー ファイルの存在を検証せず、不必要なファイルは無視します。

ライブラリの代替名。'alias' と文字ベクトルから成るコンマ区切りのペアとして指定されます。指定された名前をライブラリと関連付けます。このライブラリを参照する MATLAB 関数のその後のすべての呼び出しは、ライブラリがアンロードされるまでこのエイリアスを使用しなければなりません。

下位ヘッダー ファイル (ヘッダー ファイル内のヘッダー ファイル) を検索するための追加のパス。'includepath' と文字ベクトルから成るコンマ区切りのペアとして指定します。

プロトタイプ ファイル。'mfilename' と文字ベクトルから成るコンマ区切りのペアとして指定します。現在のフォルダーでプロトタイプ ファイルを生成します。プロトタイプ ファイル名はライブラリ名と異なっていなければなりません。ライブラリを読み込む際、ヘッダー ファイルの代わりにこのファイルを使用します。

thunk ファイル。'thunkfilename' と文字ベクトルから成るコンマ区切りのペアとして指定します。既定の thunk ファイル名をオーバーライドします。

出力引数

すべて折りたたむ

cell 配列として返される、ヘッダーファイルにはあるがライブラリにはない関数の名前。

データ型: cell

文字配列として返される、ヘッダー ファイル処理中に生成された警告。

制限

  • サポートされている C コンパイラが必要で、Perl が使用可能でなければなりません。

  • ライブラリが既にメモリに読み込まれている場合は、loadlibrary を呼び出さないでください。この条件をテストするには、libisloaded を呼び出します。

  • loadlibrary は、MATLAB Compiler SDK™ および MATLAB Coder などのコード生成製品で生成されるライブラリをサポートしません。

  • MATLAB 共有ライブラリ インターフェイスは、関数ポインターを入力とするライブラリ関数をサポートしていません。

  • 詳細については、共有ライブラリのサポートの制限を参照してください。

詳細

すべて折りたたむ

プロトタイプ ファイル

プロトタイプ ファイルは、編集してヘッダー ファイルの代わりに使用可能な MATLAB コマンドのファイルです。

Thunk ファイル

thunk ファイルは、MATLAB で生成された 64 ビット ライブラリへの互換レイヤーです。thunk ファイルの名前は BASENAME_thunk_COMPUTER.c です。ここで BASENAME は共有ライブラリの名前か、mfilename プロトタイプ名 (指定されている場合) のいずれかです。COMPUTER は、関数 computer が返すテキストです。

MATLAB はこのファイルをコンパイルし、ファイル BASENAME_thunk_COMPUTER.LIBEXT を作成します。ここで、LIBEXT は、Windows の dll のような、プラットフォーム依存の既定の共有ライブラリ拡張子です。

ヒント

  • 同じ名前のライブラリ ファイルが複数ある場合、ライブラリ ファイル名を使用して最初のライブラリ ファイルを読み込みます。次に、alias オプションでその他のライブラリを読み込みます。

  • alias オプションをライブラリの別名として使用します。別のヘッダー ファイルを読み込みむには引数 @protofile を使用します。

バージョン履歴

R2006a より前に導入