Linux 下 undefined reference to pthread_create 解決方案

錯誤現象

$ gcc thread.c -o thread
/tmp/ccXXXXXX.o: In function `main':
thread.c:(.text+0x1a): undefined reference to `pthread_create'
thread.c:(.text+0x2e): undefined reference to `pthread_join'

代碼包含了 <pthread.h>，調用了 pthread_create、pthread_join，編譯預處理通過，鏈接失敗。

根本原因

pthread 庫不是 GCC 默認鏈接的庫。
頭文件 pthread.h 僅提供聲明，實現位於獨立的靜態庫 libpthread.a (或動態庫 libpthread.so) 中。鏈接器需顯式指定 -lpthread 才能解析符號。

解決命令

gcc thread.c -o thread -lpthread

順序很重要：-lpthread 必須放在源文件 後面 (GCC 鏈接器按順序解析符號)。

完整檢查清單

1. ✅ #include <pthread.h>
2. ✅ 編譯命令包含 -lpthread (或 -pthread，見下文)
3. ✅ 若用 pthread_atfork 等函數同理需鏈接
4. ✅ 某些教程提到 #include <stdlib.h>，實際上 pthread.h 已包含必要系統頭文件，非必需

進階：-pthread vs -lpthread

最佳實踐：

# 編譯+鏈接一步到位
gcc -pthread thread.c -o thread

# 或分離
gcc -pthread -c thread.c -o thread.o
gcc -pthread thread.o -o thread

CMake 中的正確姿勢

find_package(Threads REQUIRED)
add_executable(my_thread thread.c)
target_link_libraries(my_thread Threads::Threads)

Threads::Threads 目標會自動處理平台差異 (Linux -pthread、Windows 無需、部分 Unix -lpthread)。

驗證鏈接成功

$ nm thread | grep pthread
                 U pthread_create
                 U pthread_join
$ ldd thread | grep pthread
    libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x...)

符號表顯示 U (未定義，來自動態庫)，運行時動態鏈接器解析。

總結

undefined reference to pthread_create 純屬鏈接缺少庫。記住口訣：「用線程，加 -pthread」。現代構建系統 (CMake/Meson) 用 Threads 包裹，一勞永逸。