C言語の開発において、多くのエンジニアが一度は遭遇し、頭を悩ませるのが「undefined reference to ‘x’」というエラーメッセージです。

このエラーはコンパイル自体は成功しているように見えるため、初心者にとっては原因の特定が難しく感じられることが少なくありません。

本記事では、このエラーが発生するメカニズムから具体的な解決策まで、実務で役立つ知識を網羅的に詳しく解説します。

目次 [ close ]
  1. 「undefined reference to 'x'」が発生する本質的な理由
    1. コンパイルエラーとの決定的な違い
  2. 原因1：関数の定義（実体）が記述されていない
  3. 原因2：複数ファイルのビルド指定漏れ
  4. 原因3：外部ライブラリのリンク指定忘れ
  5. 原因4：リンク順序による問題
  6. 原因5：C++との混在によるマングリングの問題
  7. 原因6：グローバル変数の宣言と定義
  8. エラー解決のためのチェックリスト
  9. まとめ

「undefined reference to ‘x’」が発生する本質的な理由

このエラーは、プログラミングのビルドプロセスにおける「リンク（Link）」という工程で発生するエラーです。

C言語のソースコードが実行ファイルになるまでには、プリプロセス、コンパイル、アセンブル、そしてリンクという段階を踏みます。

コンパイラは個別のソースファイル（.c）をチェックし、関数のプロトタイプ宣言があれば、その時点では「実体はどこかにあるはずだ」と判断して処理を先に進めます。

しかし、最終的にバラバラのオブジェクトファイルを一つに統合するリンカが関数の実体を見つけられなかったときに、このエラーが吐き出されます。

つまり、「名前（宣言）は知っているが、中身（定義）がどこにあるかわからない」という状態に陥っていることを意味します。

コンパイルエラーとの決定的な違い

構文エラー（Syntax Error）などはコンパイル段階で検出されますが、今回のエラーはそれよりも後の段階で発生します。

そのため、文法的に正しいコードを書いていても、プロジェクトの構成やビルドの設定に不備があると発生してしまいます。

原因1：関数の定義（実体）が記述されていない

最も単純かつ頻繁に起こる原因は、ヘッダファイルに関数のプロトタイプ宣言を書いたものの、ソースファイル側にその関数の本体を書き忘れているケースです。

C言語
/* main.c */
#include <stdio.h>

void calculate_data(int value); // 宣言はある

int main(void) {
    calculate_data(10); // ここで呼び出している
    return 0;
}

/* 本来ここに calculate_data の定義が必要だが、書き忘れている */
実行結果
/usr/bin/ld: /tmp/ccXXXXXX.o: in function `main':
main.c:(.text+0x15): undefined reference to `calculate_data'
collect2: error: ld returned 1 exit status

この場合、リンカは calculate_data という名前の処理を探しますが、どこにも見つからないためエラーとなります。

解決策は、関数の中身を正しく実装することです。

原因2：複数ファイルのビルド指定漏れ

プロジェクトが複数のソースファイルで構成されている場合、すべてのファイルを同時にリンクする必要があります。

例えば、main.c と sub.c の2つのファイルがあるとき、main.c だけを指定してビルドするとエラーになります。

C言語
/* functions.c */
#include <stdio.h>

void print_hello(void) {
    printf("Hello from sub file!\n");
}
C言語
/* main.c */
void print_hello(void);

int main(void) {
    print_hello();
    return 0;
}

ここで、以下のようにコマンドを実行すると失敗します。

Shell
gcc main.c -o myprog

リンカは main.c のオブジェクトファイルだけを見ているため、functions.c にある実体を知ることができません。

この問題を解決するには、すべてのソースファイルをビルドコマンドに含める必要があります。

Shell
gcc main.c functions.c -o myprog

これにより、リンカは両方のファイルをスキャンし、正しくシンボルを解決できるようになります。

原因3：外部ライブラリのリンク指定忘れ

標準ライブラリ以外の外部ライブラリ（数学関数、スレッド、グラフィックスなど）を使用する場合、リンカに対して明示的にライブラリを結合するよう指示しなければなりません。

特に数学関数（math.h）を使用する際に pow や sin などの関数でエラーが出るのは、非常に有名なトラブルパターンです。

C言語
#include <stdio.h>
#include <math.h>

int main(void) {
    double result = sqrt(16.0); // 数学関数を使用
    printf("Result: %f\n", result);
    return 0;
}

上記のコードを単に gcc main.c とコンパイルすると、undefined reference to `sqrt' というエラーが出ることがあります。

これは、数学ライブラリ（libm）がデフォルトではリンクされないためです。

解決するには、コンパイルオプションに -lm を追加します。

Shell
gcc main.c -o myprog -lm

主なライブラリとリンク用オプションの対応表を以下に示します。

使用する機能ヘッダファイルリンクオプション
数学関数 (sin, cos, sqrt等)math.h-lm
POSIXスレッド (pthread_create等)pthread.h-lpthread
リアルタイム拡張 (clock_gettime等)time.h-lrt
動的ロード (dlopen等)dlfcn.h-ldl

原因4：リンク順序による問題

GCCなどのリンカは、コマンドラインに並べられたファイルを左から右へと順番にスキャンしていきます。

依存される側のライブラリを先に記述してしまうと、後から出てくるオブジェクトファイルが必要としているシンボルを見落としてしまうことがあります。

例えば、-lm オプションをソースファイルよりも前に置くとエラーになる場合があります。

Shell
# 誤った順序（エラーになる可能性がある）
gcc -lm main.c -o myprog

# 正しい順序（ソースファイルの後にライブラリを置く）
gcc main.c -o myprog -lm

常に「依存している側を先に、依存されている側を後に」記述するというルールを徹底しましょう。

原因5：C++との混在によるマングリングの問題

C言語のプロジェクトにC++のコードを混ぜる場合、あるいはその逆の場合に「undefined reference」が発生することがあります。

C++コンパイラは、関数のオーバーロードをサポートするために、内部的に関数名を書き換える「名前マングリング」という処理を行います。

一方、C言語はマングリングを行わないため、名前の不一致が起こります。

これを防ぐためには、C++側のヘッダファイルでextern “C”を使用し、C言語の形式で名前を扱うように指示しなければなりません。

C++
/* header.h */
#ifdef __cplusplus
extern "C" {
#endif

void my_c_function(void);

#ifdef __cplusplus
}
#endif

この記述により、C++コンパイラでビルドしてもC言語互換の名前が保持されるようになります。

原因6：グローバル変数の宣言と定義

関数だけでなく、グローバル変数（外部変数）でも同様のエラーが発生します。

複数のファイルで同じ変数を参照したい場合、ヘッダファイルには extern を付けて宣言し、どこか一つのソースファイルだけで実体を定義しなければなりません。

C言語
/* common.h */
extern int global_counter; // 宣言

/* sub.c */
int global_counter = 0; // ここで実体を定義

/* main.c */
#include "common.h"
int main(void) {
    global_counter = 10; // 参照
    return 0;
}

もし sub.c での定義を忘れると、undefined reference to `global_counter' というエラーに繋がります。

エラー解決のためのチェックリスト

トラブルシューティングをスムーズに進めるため、以下のチェックリストを活用してください。

  • 関数名のスペルミス（大文字・小文字の違いを含む）はないか。
  • 関数の引数の数や型が、宣言と定義で一致しているか。
  • すべての .c ファイルをビルド対象に含めているか。
  • 外部ライブラリを使用する場合、-l オプションを指定しているか。
  • リンクオプションの順番は適切か（ソースファイルの後に記述しているか）。
  • static 修飾子を付けた関数を、別ファイルから呼ぼうとしていないか。

特に static 関数は、そのファイル内（翻訳単位内）でしか参照できないため、外部から呼び出すとリンカは見つけることができません。

まとめ

「undefined reference to ‘x’」は、C言語のビルドにおけるリンク段階でシンボルが見つからないことを示すエラーです。

その原因は単純な実装漏れから、コマンドのオプション不足、ビルドの順序、さらには言語間の互換性まで多岐にわたります。

まずは「宣言（プロトタイプ）」と「定義（実体）」が対になっているかを確認し、次にビルド環境がすべての実体を把握できているかを見直すことが解決の近道です。

本記事で紹介した事例を一つずつ確認していけば、必ず原因を突き止め、エラーを解消することができるはずです。

リンカの仕組みを正しく理解することは、より複雑なプロジェクトや大規模なシステム開発において非常に大きな武器となるでしょう。