GDB Extension and IDE · 3/6

GDB Pretty-Printer 심화 — STL·커스텀 타입 시각화

2026년 5월 27일 · Hawk · 4분 읽기

std::vector<int>가 {1, 2, 3, 4}로 깔끔하게 표시되는 이유는 pretty-printer 덕입니다. Python 클래스 하나가 원시 메모리를 사람 읽을 표현으로 변환. 이 장은 그 메커니즘을 깊이 다룹니다 — to_string/children/display_hint 인터페이스, MI 트리 출력, auto-load 메커니즘, 그리고 libstdc++ 표준 printer의 내부.

#Dispatch 메커니즘

Pretty-printer dispatch 흐름

(gdb) print v 처리 흐름:

v의 타입을 파악 → gdb.Type
등록된 pretty-printer들 순회
첫 매칭되는 printer로 인스턴스 생성
instance.to_string() 호출 → 결과 문자열
instance.children() 호출 (있으면) → 자식 노드 yield
instance.display_hint() (있으면) → "array"/"map"/"string"
위 정보를 종합해 출력

매칭이 없으면 원시 출력 (struct 멤버 그대로). print /r val로 강제 원시.

#단순 printer

1
import gdb
2
import gdb.printing
3

4
class PointPrinter:
5
    def __init__(self, val):
6
        self.val = val
7
    def to_string(self):
8
        return f"Point({int(self.val['x'])}, {int(self.val['y'])})"
9

10
def build_pp():
11
    pp = gdb.printing.RegexpCollectionPrettyPrinter("myproject")
12
    pp.add_printer('Point', '^Point$', PointPrinter)
13
    return pp
14

15
gdb.printing.register_pretty_printer(gdb.current_objfile(), build_pp())

1
(gdb) print p
2
$1 = Point(3, 4)
3

4
(gdb) print /r p
5
$2 = {x = 3, y = 4}

#매칭 — regex

1
pp.add_printer('std::vector', '^std::vector<.*>$', VectorPrinter)
2
pp.add_printer('std::shared_ptr', '^std::shared_ptr<.*>$', SharedPtrPrinter)

regex 매칭. ^std::vector<.*>$ 같은 패턴으로 템플릿 인스턴스화 전체를 한 패턴이 잡음.

#자식 노드 — children()

1
class VectorPrinter:
2
    def __init__(self, val):
3
        self.val = val
4
    def to_string(self):
5
        size = int(self.val['_M_impl']['_M_finish'] - self.val['_M_impl']['_M_start'])
6
        return f"std::vector of size {size}"
7
    def children(self):
8
        start = self.val['_M_impl']['_M_start']
9
        finish = self.val['_M_impl']['_M_finish']
10
        size = int(finish - start)
11
        for i in range(size):
12
            yield f"[{i}]", start[i]
13
    def display_hint(self):
14
        return "array"

1
(gdb) print v
2
$1 = std::vector of size 3 = {
3
  [0] = 1,
4
  [1] = 2,
5
  [2] = 3
6
}

children()이 (name, value) 쌍을 yield. value는 gdb.Value 또는 Python 기본 타입.

#display_hint 종류

hint	표시 방식
`"array"`	`{[0] = .., [1] = ..}` 인덱스 형식
`"map"`	children이 key, value 교대로 emit, `[key] = value`
`"string"`	따옴표 + 이스케이프

MI(머신 인터페이스) 프런트엔드(VSCode)가 이 힌트로 트리 위젯 모양을 결정.

#map printer

1
class MapPrinter:
2
    def __init__(self, val):
3
        self.val = val
4
    def to_string(self):
5
        return f"std::map of {int(self.val['_M_t']['_M_impl']['_M_node_count'])} entries"
6
    def children(self):
7
        # red-black tree 순회
8
        node = self.val['_M_t']['_M_impl']['_M_header']['_M_left']  # 최소
9
        idx = 0
10
        while node:
11
            # key/value 추출 (단순화)
12
            kv = node.cast(gdb.lookup_type("std::_Rb_tree_node<std::pair<KeyT, ValueT>>").pointer())
13
            pair = kv['_M_storage']['_M_storage']
14
            yield f"key{idx}", pair['first']
15
            yield f"val{idx}", pair['second']
16
            # 다음 노드
17
            node = next_node(node)
18
            idx += 1
19
    def display_hint(self):
20
        return "map"

1
(gdb) print m
2
$1 = std::map of 3 entries = {
3
  ["a"] = 1,
4
  ["b"] = 2,
5
  ["c"] = 3
6
}

#String printer

1
class StringPrinter:
2
    def __init__(self, val):
3
        self.val = val
4
    def to_string(self):
5
        # std::string 내부: _M_dataplus._M_p 가 char *
6
        ptr = self.val['_M_dataplus']['_M_p']
7
        return ptr.string(encoding='utf-8')
8
    def display_hint(self):
9
        return "string"

display_hint = "string"이면 GDB가 자동으로 "..."로 감싸고 이스케이프. set print elements N이 잘림 한계.

#똑똑한 printer — 크기 제한

1
class VectorPrinter:
2
    ...
3
    def children(self):
4
        max_elements = gdb.parameter("print elements")
5
        start = self.val['_M_impl']['_M_start']
6
        finish = self.val['_M_impl']['_M_finish']
7
        size = int(finish - start)
8
        n_show = min(size, max_elements) if max_elements else size
9
        for i in range(n_show):
10
            yield f"[{i}]", start[i]
11
        if size > n_show:
12
            yield "...", f"and {size - n_show} more"

큰 컨테이너 출력 시 전체를 yield하면 디버거가 느려집니다. print elements를 따라 자르기.

#auto-load — 라이브러리 따라가는 printer

libfoo.so와 같은 디렉터리에 libfoo.so-gdb.py 두면 GDB가 라이브러리 로드 시 자동 source.

1
/usr/lib/libfoo.so
2
/usr/lib/libfoo.so-gdb.py    ← 자동 로드

내용 예.

1
import gdb, gdb.printing
2

3
class FooNode:
4
    def __init__(self, val):
5
        self.val = val
6
    def to_string(self):
7
        return f"FooNode({int(self.val['id'])})"
8

9
def build_pp():
10
    pp = gdb.printing.RegexpCollectionPrettyPrinter("libfoo")
11
    pp.add_printer('FooNode', '^FooNode$', FooNode)
12
    return pp
13

14
# 등록 시 objfile=현재 로드된 객체
15
gdb.printing.register_pretty_printer(gdb.current_objfile(), build_pp())

#보안

set auto-load safe-path / (또는 특정 디렉터리). 신뢰하는 환경.

1
(gdb) info auto-load
2
gdb-scripts:  No auto-loaded scripts.
3
libthread-db:  No auto-loaded libthread-db.
4
local-gdbinit:  No auto-loaded .gdbinit.
5
python-scripts:
6
Loaded  Script
7
Yes     /usr/lib/libstdc++.so.6.0.32-gdb.py

/usr/lib/libstdc++.so.6.x.x-gdb.py가 libstdc++ pretty-printer. 시스템에 자동 설치.

#libstdc++ printer 내부

libstdc++의 표준 printer 분석. 소스: gcc/libstdc++-v3/python/libstdcxx/v6/printers.py.

1
class StdVectorPrinter:
2
    "Print a std::vector"
3

4
    class _iterator(Iterator):
5
        def __init__(self, start, finish, bitvec):
6
            self.bitvec = bitvec
7
            if bitvec:
8
                self.item = start['_M_p']
9
                self.so = 0
10
                self.finish = finish['_M_p']
11
                self.fo  = finish['_M_offset']
12
                ...
13
            else:
14
                self.item = start
15
                self.finish = finish
16
            self.count = 0
17

18
        def __next__(self):
19
            count = self.count
20
            self.count = self.count + 1
21
            if self.bitvec:
22
                # vector<bool> 특수 처리
23
                ...
24
            else:
25
                if self.item == self.finish:
26
                    raise StopIteration
27
                elt = self.item.dereference()
28
                self.item = self.item + 1
29
                return ('[%d]' % count, elt)
30

31
    def __init__(self, typename, val):
32
        self.typename = strip_versioned_namespace(typename)
33
        self.val = val
34
        self.is_bool = val.type.template_argument(0).code == gdb.TYPE_CODE_BOOL
35

36
    def children(self):
37
        return self._iterator(self.val['_M_impl']['_M_start'],
38
                              self.val['_M_impl']['_M_finish'],
39
                              self.is_bool)
40

41
    def to_string(self):
42
        start = self.val['_M_impl']['_M_start']
43
        finish = self.val['_M_impl']['_M_finish']
44
        end = self.val['_M_impl']['_M_end_of_storage']
45
        if self.is_bool:
46
            length = start['_M_offset'] + finish['_M_p'] * 8 - start['_M_p'] * 8 + finish['_M_offset']
47
            capacity = (end['_M_p'] - start['_M_p']) * 8
48
            return ('%s<bool> of length %d, capacity %d'
49
                    % (self.typename, int (length), int (capacity)))
50
        return ('%s of length %d, capacity %d'
51
                % (self.typename, int (finish - start), int (end - start)))
52

53
    def display_hint(self):
54
        return 'array'

핵심 패턴 셋.

__init__ — 타입 이름과 Value 저장.
to_string — 한 줄 요약 (“vector of length N”).
children — Iterator를 yield하면서 원소 emit.
_iterator — 별도 클래스로 상태 머신 보유 (vector 같은 특수 처리).
display_hint = 'array'.

GCC의 모든 STL printer가 같은 구조. unordered_map, list, map, set, multimap, …

#등록 — 한 줄

1
def build_libstdcxx_dictionary():
2
    libstdcxx_printer = Printer("libstdc++-v6")
3

4
    # Add all the templated types
5
    libstdcxx_printer.add_version('std::', 'vector', StdVectorPrinter)
6
    libstdcxx_printer.add_version('std::', 'map', StdMapPrinter)
7
    libstdcxx_printer.add_version('std::', 'unordered_map', Tr1UnorderedMapPrinter)
8
    libstdcxx_printer.add_version('std::', 'shared_ptr', SharedPointerPrinter)
9
    ...
10

11
def register_libstdcxx_printers(obj):
12
    gdb.printing.register_pretty_printer(obj, build_libstdcxx_dictionary())

수십 종류. 매 GCC 버전마다 추가·수정. 의외로 코드량 — printers.py가 수천 줄.

#libc++ printer

LLVM 소스 utils/gdb/libcxx/printers.py. 비슷한 구조지만 std::__1:: namespace.

1
class StdVectorPrinter(object):
2
    "Print a std::vector"
3

4
    class _VectorIterator(object):
5
        ...
6

7
    def __init__(self, val):
8
        self.val = val
9
        ...

macOS의 기본 표준 라이브러리는 libc++. clang 빌드도 보통 libc++. 두 printer를 함께 등록하면 어느 라이브러리의 vector든 잘 표시.

#디스플레이 옵션

1
(gdb) set print pretty on            # 들여쓰기
2
(gdb) set print elements 100         # 컨테이너 표시 한도
3
(gdb) set print array on             # 배열 한 줄로
4
(gdb) set print array-indexes on     # 인덱스 표시
5
(gdb) set print depth 5              # 중첩 깊이
6
(gdb) set print null-stop on         # NUL에서 string 자르기
7
(gdb) set print address on

pretty-printer가 동작해도 이 옵션들이 최종 표시에 영향.

#Type Printer — 타입 표시 자체 커스터마이즈

typedef나 긴 템플릿을 짧은 이름으로 표시.

1
import gdb, gdb.types
2

3
class SizeTPrinter:
4
    name = "size_t"
5
    enabled = True
6
    def __init__(self):
7
        pass
8
    def instantiate(self):
9
        return self.recognizer()
10
    class recognizer:
11
        def recognize(self, type_obj):
12
            if type_obj.tag == 'unsigned long':
13
                return 'size_t'
14
            return None
15

16
gdb.types.register_type_printer(gdb.current_objfile(), SizeTPrinter())

1
(gdb) ptype my_var
2
type = size_t          ← unsigned long 대신

std::__cxx11::basic_string<char, ...> 같은 지옥의 긴 이름을 std::string으로 단순화하는 데 활용.

#Xmethod — 가짜 C++ 메서드

C++ 객체에 가짜 메서드를 추가. 예: std::vector::size()가 실제 호출 없이 Python으로 평가.

1
import gdb.xmethod
2

3
class VectorSizeWorker(gdb.xmethod.XMethodWorker):
4
    def get_arg_types(self):
5
        return None
6
    def get_result_type(self, obj):
7
        return gdb.lookup_type('size_t')
8
    def __call__(self, obj):
9
        start = obj['_M_impl']['_M_start']
10
        finish = obj['_M_impl']['_M_finish']
11
        return int(finish - start)
12

13
class VectorSize(gdb.xmethod.XMethodMatcher):
14
    def __init__(self):
15
        super().__init__("vector_size")
16
    def match(self, class_type, method_name):
17
        if method_name != 'size': return None
18
        return VectorSizeWorker()
19

20
gdb.xmethod.register_xmethod_matcher(None, VectorSize())

1
(gdb) print v.size()
2
$1 = 3

실제 함수 호출 없이 Python으로 계산. print x.size()이 프로세스가 정지된 상태에서도 동작 (실제 호출은 인라인됐을 때).

#MI 출력 — IDE 트리

VSCode·Emacs gud 등 MI 프로토콜을 쓰는 프런트엔드에서 pretty-printer가 어떻게 트리로 보이는가.

1
(gdb) -var-create - * v
2
^done,name="var1",numchild="3",value="std::vector of size 3",
3
       type="std::vector<int, std::allocator<int> >",
4
       has_more="0",displayhint="array"
5

6
(gdb) -var-list-children var1
7
^done,numchild="3",children=[
8
  child={name="var1.0",exp="[0]",numchild="0",value="1",type="int"},
9
  child={name="var1.1",exp="[1]",numchild="0",value="2",type="int"},
10
  child={name="var1.2",exp="[2]",numchild="0",value="3",type="int"}
11
]

displayhint="array"가 IDE에게 트리 표시 방식을 알림.

-var-list-children은 재귀 호출 — 사용자가 트리 노드를 펼치면 그때 호출. 지연 로드 패턴.

#활용 — 도메인 객체

내 프로젝트의 핵심 객체에 printer를 만들면 디버깅이 훨씬 쉬워집니다.

1
class TaskPrinter:
2
    """RTOS Task 객체."""
3
    def __init__(self, val):
4
        self.val = val
5
    def to_string(self):
6
        name = self.val['name'].string()
7
        prio = int(self.val['priority'])
8
        state = int(self.val['state'])
9
        state_str = ['ready', 'running', 'blocked', 'suspended'][state]
10
        return f"Task '{name}' prio={prio} state={state_str}"
11
    def children(self):
12
        yield 'stack_used', self.val['stack_high_water_mark']
13
        yield 'tick_count', self.val['tick_count']
14
        yield 'name', self.val['name']
15

16
class QueuePrinter:
17
    def __init__(self, val):
18
        self.val = val
19
    def to_string(self):
20
        used = int(self.val['used'])
21
        cap = int(self.val['capacity'])
22
        return f"Queue {used}/{cap}"
23
    def children(self):
24
        used = int(self.val['used'])
25
        head = self.val['head']
26
        data = self.val['data']
27
        for i in range(used):
28
            idx = (head + i) % int(self.val['capacity'])
29
            yield f"[{i}]", data[idx]
30
    def display_hint(self):
31
        return "array"

1
(gdb) print *current_task
2
$1 = Task 'worker' prio=5 state=running = {
3
  stack_used = 1024,
4
  tick_count = 12345,
5
  name = "worker"
6
}
7

8
(gdb) print *queue
9
$2 = Queue 3/16 = {
10
  [0] = ...,
11
  [1] = ...,
12
  [2] = ...
13
}

팀 단위로 공통 printer를 두면 신입 개발자가 디버깅을 빠르게 시작할 수 있습니다.

#디버깅 — print-pretty-printer-info

1
(gdb) info pretty-printer
2
global pretty-printers:
3
  builtin
4
    mpx_bound128
5
  myproject
6
    Point
7
    MyClass
8

9
objfile /usr/lib/libstdc++.so.6 pretty-printers:
10
  libstdc++-v6
11
    __gnu_cxx::__normal_iterator
12
    __gnu_cxx::_Slist_iterator
13
    __gnu_debug::_Safe_iterator
14
    std::__1::shared_ptr
15
    std::__cxx11::basic_string
16
    std::__cxx11::list
17
    std::_Fwd_list_iterator
18
    std::_Fwd_list_const_iterator
19
    std::_List_iterator
20
    std::_List_const_iterator
21
    std::_Rb_tree_iterator
22
    std::_Rb_tree_const_iterator
23
    std::_Bit_iterator
24
    std::_Bit_const_iterator
25
    std::_Slist_iterator
26
    std::_Slist_const_iterator
27
    std::any
28
    std::array
29
    std::atomic
30
    std::basic_string
31
    std::bitset
32
    std::deque
33
    std::deque::iterator
34
    std::error_code
35
    std::experimental::any
36
    std::experimental::basic_string_view
37
    std::experimental::optional
38
    std::forward_list
39
    std::list
40
    std::map
41
    std::map::iterator
42
    std::multimap
43
    std::multimap::iterator
44
    std::multiset
45
    std::multiset::iterator
46
    std::optional
47
    std::pair
48
    std::priority_queue
49
    std::queue
50
    std::set
51
    std::set::iterator
52
    std::shared_ptr
53
    std::stack
54
    std::tuple
55
    std::unique_ptr
56
    std::unordered_map
57
    std::unordered_map::iterator
58
    std::unordered_multimap
59
    std::unordered_multimap::iterator
60
    std::unordered_multiset
61
    std::unordered_set
62
    std::variant
63
    std::vector
64
    std::vector::iterator
65
    std::weak_ptr

등록된 printer 전체. 이 목록을 보면 어떤 STL 타입이 지원되는지 한눈에.

#비활성화

특정 printer를 비활성화.

1
(gdb) disable pretty-printer global builtin
2
(gdb) disable pretty-printer .* std::vector
3
(gdb) print /r v       # 일시적 원시 출력

가끔 printer가 너무 적극적으로 줄여 정보가 사라질 때 (set print elements 0도 도움).

#정리

pretty-printer = Python 클래스. to_string + children + display_hint.
display_hint로 array/map/string 트리 모양.
regex로 타입 매칭 — 템플릿 인스턴스화 전부.
gdb.printing.register_pretty_printer로 objfile별 등록.
auto-load: libfoo.so-gdb.py가 자동 source.
libstdc++/libc++의 표준 printer는 GCC/LLVM 소스에.
Type printer로 긴 타입 이름 단축.
Xmethod로 가짜 메서드 (v.size() 등).
MI 출력의 트리 모양도 pretty-printer가 결정.
도메인 객체에 printer를 만들면 팀 디버깅이 훨씬 빨라짐.

#다음 장 예고

Ch 4 — FrameDecorator / Unwinder. 콜스택을 변형하고 JIT 코드도 풀어내기.

#관련 항목

GDB Extension and IDE · 3 of 6

GDB FrameDecorator·Unwinder — 콜스택 가공과 JIT 지원

Frame filter, FrameDecorator로 콜스택 변형, custom unwinder로 JIT 코드 추적.

2026년 5월 27일·gdb

GDB 커스텀 명령·Convenience Function·Event 훅·Breakpoint

사용자 정의 명령, $name(...) 함수, stop hook, 자동 BP 액션 패턴.

2026년 5월 27일·gdb

GDB Python API 입문 — Value·Type·Frame 객체 활용

GDB Python 인터프리터, 핵심 객체(Value/Type/Frame/Symbol), 디버기 데이터 조작.

2026년 5월 27일·gdb

GDB Pretty-Printer 심화 — STL·커스텀 타입 시각화

#Dispatch 메커니즘

#단순 printer

#매칭 — regex

#자식 노드 — children()

#display_hint 종류

#map printer

#String printer

#똑똑한 printer — 크기 제한

#auto-load — 라이브러리 따라가는 printer

#보안

#libstdc++ printer 내부

#등록 — 한 줄

#libc++ printer

#디스플레이 옵션

#Type Printer — 타입 표시 자체 커스터마이즈

#Xmethod — 가짜 C++ 메서드

#MI 출력 — IDE 트리

#활용 — 도메인 객체

#디버깅 — print-pretty-printer-info

#비활성화

#정리

#다음 장 예고

#관련 항목

GDB Extension and IDE · 3 of 6

관련 글

GDB FrameDecorator·Unwinder — 콜스택 가공과 JIT 지원

GDB 커스텀 명령·Convenience Function·Event 훅·Breakpoint

GDB Python API 입문 — Value·Type·Frame 객체 활용

이 글을 참조하는 글 (3)