C++ 이름 맹글링: _Z 심볼 읽기, nm·c++filt로 디맹글링, extern C 링크 에러

작성 0xmote · 2026년 3월 11일 · 12분 읽기 · 수정 2026년 9월 24일 고급 튜토리얼

이 글의 핵심

C 라이브러리를 C++에서 호출하거나 그 반대로 쓸 때 undefined reference가 나는 원인은 대부분 맹글링된 이름이 서로 맞지 않기 때문입니다. extern "C" 함수는 오버로딩할 수 없는 이유와 컴파일러마다 맹글링 규칙이 달라 서로 다른 컴파일러로 빌드한 C++ 라이브러리를 섞기 어려운 이유도 함께 다룹니다.

Name Mangling이란?

컴파일러가 함수·변수 이름을 타입·네임스페이스·인자 목록을 반영해 고유한 심볼 이름으로 바꾸는 것을 name mangling(이름 맹글링)이라고 합니다. 링킹과 ABI 호환성을 다룰 때 이해해 두면 좋습니다.

링커 입장에서는 최종 실행 파일/라이브러리 안의 심볼 이름이 문자열 하나로 정해져야 합니다. C는 func처럼 짧은 이름이면 충분하지만, C++는 같은 이름 func에 서로 다른 매개변수 타입(오버로딩)을 붙일 수 있으므로, 컴파일러가 “이름 + 타입 정보”를 인코딩한 문자열로 바꿉니다. 그 결과가 .o 파일의 심볼 테이블에 _Z... 같은 형태로 들어갑니다.

아래 코드는 소스에서는 같은 식별자 func 이지만, 링커가 구분할 수 있도록 서로 다른 심볼이 됩니다.

// 소스 코드: 사람이 읽는 이름은 둘 다 "func"
void func(int x) {}
void func(double x) {}

// GCC/Clang(Itanium ABI) 계열에서 대략 이런 식으로 구분됩니다(환경에 따라 약간 다를 수 있음).
// _Z4funci  →  "func" + (int)
// _Z4funcd  →  "func" + (double)
//
// _Z : Itanium 맹글링 접두사
// 4func : 이름 길이 4 + 이름 func
// i, d : 인자 타입 인코드 (int, double)

nm으로 오브젝트를 보면 _Z로 시작하는 줄이 보일 수 있습니다. c++filt에 파이프로 넣으면 다시 func(int), func(double)처럼 사람이 읽기 좋은 형태(디맹글링)로 볼 수 있습니다.

맹글링 규칙에서 알아 둘 만한 점은 일반 함수의 반환 타입은 이름에 들어가지 않는다는 것입니다. int f(int)와 double f(int)는 같은 심볼 _Z1fi가 되므로, 반환 타입만 다른 오버로딩이 C++에서 금지되는 이유가 맹글링에도 그대로 반영되어 있습니다. 반면 함수 템플릿의 인스턴스는 반환 타입까지 인코딩합니다(뒤의 _Z4funcIiEvT_에서 v가 void 반환입니다). 또 Itanium ABI에서 전역 네임스페이스의 일반 변수(int counter;)는 맹글링되지 않고 이름 그대로 심볼이 되지만, 네임스페이스 안의 변수나 정적 멤버 변수는 _ZN...E 형태로 맹글링됩니다.

const나 참조 같은 수식어도 인코딩됩니다. void f(const std::string&)는 _Z1fRKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEE처럼 길어지는데, R은 참조, K는 const를 뜻합니다. 이 긴 이름 덕분에 선언과 정의의 매개변수 타입이 조금만 달라도 링크 단계에서 서로 다른 함수로 취급되어, 헤더와 .cpp의 시그니처 불일치가 undefined reference로 드러납니다.

왜 필요한가?

// 오버로딩: 컴파일러는 "호출 시점의 인자 타입"으로 어떤 print인지 고릅니다.
void print(int x) {}
void print(double x) {}
void print(const std::string& x) {}

// 링크 단계까지 살아 남는 이름은 서로 달라야 하므로,
// 각 정의가 서로 다른 맹글링 이름을 갖습니다.

네임스페이스·클래스 멤버·템플릿 인스턴스도 전부 “이름 공간”이 다르므로 맹글링 문자열에 추가 정보가 붙습니다. 그래야 A::f와 B::f, vector<int>::size와 vector<double>::size가 충돌하지 않습니다.

실전 예시

예시 1: 심볼 확인

# 컴파일
g++ -c program.cpp

# 심볼 확인
nm program.o

# 디맹글링
nm program.o | c++filt

nm 출력의 두 번째 열은 심볼 종류입니다. T는 이 오브젝트 파일의 코드 영역에 정의된 함수, U는 다른 곳에 정의되어 있어야 하는 미정의 참조, W/V는 인라인 함수나 템플릿 인스턴스처럼 여러 파일에 중복 생성될 수 있는 약한 심볼입니다. 링크 에러를 조사할 때는 에러 메시지의 심볼이 어떤 파일에서 U로 참조되고, 어떤 파일에서 T로 정의되는지를 비교하면 됩니다. 이름이 비슷한데 맹글링 결과가 다르다면, 그 차이를 디맹글링해서 보면 어느 타입이 어긋났는지 바로 드러납니다. GNU nm은 -C 옵션으로 c++filt 없이도 디맹글링된 이름을 보여 줍니다.

예시 2: extern “C”

// C++ 맹글링
void func(int x) {}
// 심볼: _Z4funci

// C 맹글링 (맹글링 없음)
extern "C" void func(int x) {}
// 심볼: func

// C 라이브러리 사용
extern "C" {
    #include <stdio.h>
}

extern "C"는 “이 함수를 C 언어 링크 방식으로 다뤄라”는 지시입니다. 이름을 맹글링하지 않고, 호출 규약도 해당 플랫폼의 C 방식을 따릅니다. 함수 본문 안에서는 여전히 C++의 모든 기능(클래스, 템플릿, 예외)을 쓸 수 있습니다. 바뀌는 것은 외부에서 보이는 이름과 호출 방식뿐입니다.

다만 마지막 예시처럼 <stdio.h>를 extern "C"로 감쌀 필요는 없고, 감싸지 않는 것이 좋습니다. 표준 C 헤더와 대부분의 C 라이브러리 헤더는 이미 내부에 #ifdef __cplusplus 가드를 갖고 있습니다. 게다가 C++ 컴파일러가 제공하는 <stdio.h>는 내부에서 C++ 전용 선언(오버로드나 템플릿)을 포함할 수 있는데, 이를 extern "C" 블록 안에 넣으면 template with C linkage 같은 에러가 납니다. extern "C" 블록은 가드가 없는 오래된 서드파티 C 헤더에만 씁니다.

예시 3: C++ 라이브러리를 C에서 사용

// mylib.h
#ifdef __cplusplus
extern "C" {
#endif

void my_function(int x);

#ifdef __cplusplus
}
#endif

// mylib.cpp
extern "C" void my_function(int x) {
    std::cout << x << std::endl;
}

이 헤더 하나를 C 컴파일러와 C++ 컴파일러가 모두 읽습니다. C 컴파일러는 extern "C" 문법을 모르므로 __cplusplus 매크로(C++ 컴파일러만 정의)로 감춰야 합니다. C++ 라이브러리를 C에 노출할 때 지켜야 할 규칙이 두 가지 더 있습니다. 첫째, 예외가 extern "C" 경계를 넘어가면 안 됩니다. C 쪽 호출자는 스택 되감기를 모르므로, 예외가 빠져나가면 C 코드의 정리 작업이 건너뛰어지거나 플랫폼에 따라 std::terminate가 호출됩니다. 경계 함수 안에서 모든 예외를 잡아 에러 코드로 바꿔야 합니다. 둘째, 매개변수와 반환값은 C가 이해하는 타입(기본 타입, 포인터, POD 구조체)만 써야 합니다. std::string이나 클래스 객체는 불투명 포인터(typedef struct Handle Handle;)로 감싸서 넘기는 것이 관례입니다.

플러그인 시스템에서 dlsym(handle, "create_plugin")이나 GetProcAddress로 함수를 찾을 때도 같은 이유로 extern "C"가 필요합니다. 맹글링된 이름은 컴파일러와 버전에 따라 달라서 문자열로 하드코딩할 수 없기 때문입니다.

예시 4: 링크 에러 해결

// ❌ C 함수를 C++에서 호출
void c_function();  // C로 컴파일됨

// main.cpp
c_function();  // 링크 에러

// ✅ extern "C" 사용
extern "C" void c_function();

int main() {
    c_function();  // OK
}

맹글링 규칙

// 네임스페이스
namespace MyLib {
    void func() {}
}
// _ZN5MyLib4funcEv

// 클래스 멤버
class MyClass {
    void func() {}
};
// _ZN7MyClass4funcEv

// 템플릿
template<typename T>
void func(T x) {}
// func<int>: _Z4funcIiEvT_

네임스페이스나 클래스 안의 이름은 N ... E로 감싼 중첩 이름으로 인코딩되고, 마지막의 v는 매개변수가 없음(void)을 뜻합니다. 네임스페이스 함수와 클래스 멤버 함수가 같은 모양(_ZN5MyLib4funcEv, _ZN7MyClass4funcEv)인 것에서 알 수 있듯, 맹글링은 “무엇이 네임스페이스이고 무엇이 클래스인지”를 구분하지 않고 이름 경로만 기록합니다. const 멤버 함수라면 _ZNK7MyClass4funcEv처럼 K가 붙습니다. 템플릿의 I ... E는 템플릿 인자 목록이고, T_는 “첫 번째 템플릿 매개변수”를 가리키는 역참조입니다.

자주 발생하는 문제

문제 1: 링크 에러

// C 라이브러리
// mylib.c
void my_func() {}

// main.cpp
void my_func();  // C++ 맹글링
my_func();  // 링크 에러

// ✅ extern "C"
extern "C" void my_func();

이 에러의 메시지는 undefined reference to 'my_func()'처럼 괄호가 붙은 형태로 나옵니다. 괄호가 있다는 것은 링커가 C++ 맹글링 이름(_Z7my_funcv)을 찾고 있다는 뜻이고, 실제 mylib.o에는 맹글링되지 않은 my_func만 있으니 둘이 만나지 못합니다. 반대 방향, 즉 extern "C"로 선언했는데 정의 쪽 .cpp가 그 헤더를 include하지 않아 맹글링된 이름으로 정의된 경우에는 undefined reference to 'my_func'(괄호 없음)가 납니다. 메시지에 괄호가 있는지만 봐도 어느 쪽이 C 링크를 기대하는지 알 수 있습니다.

문제 2: 헤더 가드

// myheader.h
#ifdef __cplusplus
extern "C" {
#endif

void c_function();

#ifdef __cplusplus
}
#endif

문제 3: 오버로딩

// ❌ extern "C"는 오버로딩 불가
extern "C" {
    void func(int x);
    // void func(double x);  // 에러
}

// ✅ 다른 이름
extern "C" {
    void func_int(int x);
    void func_double(double x);
}

문제 4: 컴파일러 차이

# GCC/Clang 계열은 Itanium C++ ABI 맹글링을 따르는 경우가 많고,
# MSVC는 다른 규칙을 씁니다. 따라서 "같은 C++ 소스"라도
# 서로 다른 툴체인으로 만든 .o/.obj를 섞어 링크하면 심볼이 안 맞을 수 있습니다.
#
# 실무에서는: 한 프로젝트 안에서는 동일 컴파일러(및 호환 ABI)로 통일하는 것이 안전합니다.

MSVC에서는 같은 void func(int)가 ?func@@YAXH@Z 같은 전혀 다른 형식이 됩니다. 이 차이는 사실 의도된 것입니다. 두 컴파일러는 클래스 레이아웃, vtable 구조, 예외 처리 방식까지 다르기 때문에, 이름이 우연히 맞아 링크가 되더라도 실행 시 망가질 가능성이 높습니다. 맹글링이 다르면 적어도 링크 단계에서 깔끔하게 실패합니다.

같은 GCC 안에서도 맹글링 차이로 인한 링크 에러가 흔히 납니다. 대표적인 것이 libstdc++의 이중 ABI입니다. GCC 5부터 std::string과 std::list의 구현이 바뀌면서 새 구현은 std::__cxx11 네임스페이스로 들어갔고, _GLIBCXX_USE_CXX11_ABI 매크로로 옛 ABI를 선택할 수 있게 되었습니다. 제가 서드파티 바이너리 라이브러리를 링크할 때 가장 많이 본 에러가 undefined reference to 'foo(std::__cxx11::basic_string<char, ...> const&)'인데, 라이브러리는 _GLIBCXX_USE_CXX11_ABI=0으로, 내 코드는 기본값 1로 빌드되어 std::string을 받는 함수의 맹글링 이름이 서로 달랐던 경우였습니다. 에러 메시지에 __cxx11이 보이면 이 매크로 값부터 맞춰 보십시오.

디맹글링

# c++filt 사용
echo "_Z4funci" | c++filt
# func(int)

# nm과 함께
nm program.o | c++filt

# objdump
objdump -t program.o | c++filt

FAQ

Q1: Name Mangling은 왜?

오버로딩 지원
네임스페이스 구분
타입 안전성

Q2: extern “C”는 언제?

C 라이브러리 사용
C에서 C++ 호출
플러그인 시스템

Q3: 디맹글링은?

A: c++filt 도구 사용.

Q4: 컴파일러별 차이?

A: 맹글링 규칙 다름. Itanium ABI 표준.

Q5: 오버로딩 안 되는 이유?

A: extern “C”는 맹글링 없어서 오버로딩 불가.

Q6: Name Mangling 학습 리소스는?

“Linkers and Loaders”
Itanium ABI 문서
GCC 문서

관련 글: 링킹 가이드, ABI 호환성, extern 링킹, 컴파일 과정.