リンカー

C言語で発生するLNK2031エラーの原因と対策について解説

2025-03-31更新日: 2025-03-31

C言語で発生するLNK2031エラーは、関数の呼び出し規則が一致しない場合にリンク処理が失敗する現象です。

コード内で適切な呼び出し規則を指定することで、このエラーを回避できる場合があります。

具体例を参考に、正しい宣言方法を確認することが求められます。

目次から探す

LNK2031エラーの原因解析
- エラー発生の背景
- ネイティブ関数と純粋なイメージの違い
C言語における呼び出し規則とリンカ処理
- 呼び出し規則の種類
- リンカ処理の基本メカニズム
具体的なエラー発生事例
- エラー発生ケースの分析
- エラーメッセージの詳細解析
エラー対策の検討
- 呼び出し規則の正しい指定方法
- コンパイラオプションの調整
まとめ

LNK2031エラーの原因解析

エラー発生の背景

リンカツールエラーLNK2031の概要

LNK2031エラーは、リンク時に発生するエラーコードのひとつで、特に混在する呼び出し規則が原因で発生します。

このエラーは、関数の宣言で期待される呼び出し規則と、実際にリンカに渡されたメタデータ内の情報が一致しない場合に発生します。

たとえば、あるコンポーネントが暗黙的に __cdecl 呼び出し規則でエクスポートされているのに対し、/clr:pure オプションの下で __clrcall を前提としたクライアントから呼び出されると、リンカは適切な呼び出し規則の情報を見つけられずエラーとなります。

呼び出し規則の不一致による問題点

呼び出し規則が一致しないと、関数の呼び出し時にスタック領域のクリア方法や引数の受け渡し方法に齟齬が生じ、実行時の不具合や予期せぬ動作を引き起こす可能性があります。

特に、純粋なイメージ(pure image)でコンパイルされたコードは __clrcall を採用するため、ネイティブ関数が __cdecl で実装されていると、リンカが正しくメタデータを生成できずエラーが発生します。

ネイティブ関数と純粋なイメージの違い

ネイティブ関数は通常、標準の C ランタイムライブラリや OS の機能との互換性を前提に __cdecl 等の呼び出し規則で実装されます。

一方、純粋なイメージ(clr:pure でコンパイルされたコード)は、.NETの実行環境(CLR)上で動作し、関数呼び出しの規則として __clrcall を使用します。

これにより、両者の呼び出し規則が異なるため、同じ関数を異なる規則で扱う場合、リンカ側で混乱が生じエラーの原因となります。

C言語における呼び出し規則とリンカ処理

呼び出し規則の種類

cdeclとclrcallの違い

C言語で標準的に使用される __cdecl は、関数呼び出し時に引数のスタッククリアを呼び出し側が行うため、引数の個数が可変の場合や複数のライブラリとの連携で採用されることが多い呼び出し規則です。

一方、__clrcall は、CLR環境下で管理されたコードの呼び出しに適した方式で、呼び出し規則の詳細がコンパイラ内部で管理されるため、純粋なコードとしてコンパイルされた場合に採用されます。

これらの違いにより、同一の関数定義でもコンパイルオプションにより振る舞いが変更される点に注意が必要です。

リンカ処理の基本メカニズム

メタデータとの連携

CLR環境でコンパイルされた純粋なイメージでは、コンパイラは関数の呼び出し規則を含むメタデータを生成します。

このメタデータは、実行時に関数の呼び出し方法を決定するための重要な情報です。

メタデータに不足や矛盾がある場合、リンク時に適切な情報が取得できずにエラーが発生します。

エラー検出の流れ

リンカはコンパイルされた各オブジェクトファイルやライブラリからメタデータを収集し、各関数のシンボル情報や呼び出し規則を照合します。

もし、宣言と定義で呼び出し規則の不一致があった場合、リンカは該当するシンボル(decorated name)とメタデータの間で整合性が取れないことを検知し、LNK2031のようなエラーを出力します。

これにより、プロジェクト全体の整合性が保たれる仕組みとなっています。

具体的なエラー発生事例

エラー発生ケースの分析

/clr:pureオプション使用時の注意点

/clr:pure オプションでコンパイルすると、コードは CLR の制約内で動作する純粋なイメージとして扱われ、関数呼び出しは __clrcall に統一されます。

そのため、ネイティブで __cdecl によってエクスポートされた関数を呼び出そうとすると、呼び出し規則が異なるためリンクエラーが発生します。

以下は、/clr:pure の使用でエラーが発生するサンプルコードです。

// Sample_LNK2031_b.c
// /clr:pure オプションと共にコンパイルしてください(例：cl /clr:pure Sample_LNK2031_b.c Sample_LNK2031.lib)
// LNK2031エラーが発生するサンプル
#include <stdio.h>
// ネイティブ関数が __cdecl で実装されていると仮定
extern "C" int func();
int main() {
    // ネイティブ関数を呼び出す
    return func();
}

// 実行結果：リンクエラー LNK2031 が発生

ネイティブ関数のエクスポート時の落とし穴

ネイティブ関数をエクスポートする際、明示的に呼び出し規則を指定しないと、暗黙の __cdecl が適用されます。

特に、DLLを作成して他のモジュールから参照する場合、呼び出し規則が適切に統一されていないと、リンク時に上記のようなエラーが発生する可能性があります。

次のサンプルは、__cdecl を明示せずにエクスポートした場合の一例です。

// Sample_LNK2031_native.c
// /LD オプションでDLLを作成する例
#include <stdio.h>
extern "C" {
    // 呼び出し規則を明示せず、暗黙的に __cdecl が適用される
    __declspec(dllexport) int func() {
        // コメント：単純な処理の例として3を返す
        return 3;
    }
}
int main() {
    // このDLL自体をテストするためのmain関数
    printf("func() returns: %d\n", func());
    return 0;
}

// 出力結果：func() returns: 3
// ※DLL作成後、純粋なイメージから呼び出す際に呼び出し規則の不一致が問題となる

エラーメッセージの詳細解析

“function_declaration”とdecorated_nameの関係

エラーメッセージに表示される “function_declaration” は、関数の宣言におけるシンボル情報を示しています。

一方、decorated_name はコンパイラが生成する装飾された名前で、呼び出し規則や引数情報などが組み込まれています。

これらの情報が一致しない場合、リンカは正しい呼び出し規則を特定できなくなり、エラーを報告します。

この関係は内部的な処理で連携され、正しく設計されていない場合、例えば __cdecl と __clrcall の混在がある場合にリンクエラーとして露呈します。

呼び出し規則欠如エラーの要因

エラーの根本的な要因としては、関数宣言や定義において呼び出し規則が明示されていない点が挙げられます。

特に、/clr:pure 環境では、CLR側のメタデータが __clrcall を前提としているため、__cdecl の関数が混在するとリンカ側で情報が不足し、正しい呼び出しができなくなります。

対策としては、関数宣言時に呼び出し規則を明示的に指定することが求められます。

エラー対策の検討

呼び出し規則の正しい指定方法

適切な宣言記法の例

C言語でネイティブ関数をエクスポートする場合、明示的に __cdecl を指定することで、リンク時の不一致を回避できます。

以下は __cdecl を指定した適切な宣言方法の例です。

// Sample_LNK2031_c.c
// /clr:pure オプション下でも利用できるよう、__cdecl を明示的に指定
#include <stdio.h>
// __cdecl で関数宣言を明示することで、CLR環境との整合性を保つ
extern "C" int __cdecl func();
int main() {
    // 呼び出し前に正しい呼び出し規則が適用されることを確認
    printf("func() returns: %d\n", func());
    return 0;
}

// 出力結果：func() returns: 3

__cdecl指定の導入手順

関数の宣言および定義箇所に __cdecl を追加し、呼び出し規則を明確にします。
DLLやライブラリとしてエクスポートする際も、全ての対象関数で __cdecl を一貫して使用するようソースコードを修正します。
修正後、コンパイルおよびリンク時に発生するエラーが解消されることを確認します。

コンパイラオプションの調整

/clr:pureオプションの影響と回避策

/clr:pure オプションは、コードが完全にマネージド環境で動作することを保証するために使用されますが、ネイティブ機能との相互運用には制約が生じます。

そのため、ネイティブ関数を利用する場合は /clr:pure の使用が影響を及ぼすことを念頭に置く必要があります。

回避策としては、ネイティブ関数との連携がある場合に呼び出し規則を明示する、または必要に応じて /clr オプションのみを使用して混在モードでコンパイルする方法が考えられます。

Visual Studioバージョンごとの対応方法

Visual Studio 2015までは /clr:pure オプションがサポートされていましたが、Visual Studio 2017以降では非推奨またはサポートされないため、各バージョンでの仕様変更に注意が必要です。

Visual Studio 2015：ネイティブ関数と純粋なイメージの連携において、呼び出し規則の明示によりエラー回避が可能です。
Visual Studio 2017以降：/clr:pure の使用は避け、マネージドとネイティブコードの相互運用には /clr を使用するか、完全なネイティブプロジェクトとして管理することが望ましいです。

各バージョンのドキュメントや Microsoft Learn の最新情報を参照し、適切な対応方法を選択してください。

まとめ

この記事では、LNK2031エラーの発生背景と原因として、ネイティブ関数と純粋なイメージでの呼び出し規則の不一致が重要であることを解説しました。

具体的には、__cdecl と __clrcall の相違、CLR環境のメタデータ連携、/clr:pureオプション使用時の注意点などをサンプルコードを交えて紹介。

これにより、エラー発生要因の把握と適切な対策方法の導入が可能となります。