GDB Extension and IDE · 1/6

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

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

GDB는 거의 모든 동작을 사용자 명령으로 제어할 수 있는 완전한 디버거 SDK입니다. 그 SDK의 핵심이 내장 Python 인터프리터. print 한 줄 매크로부터 STL pretty-printer, JIT 디버깅 지원, 자동화된 메모리 분석까지 — 모두 이 API 위에서 일어납니다.

이 시리즈는 GDB의 진짜 천장인 Python·MI·DAP·프런트엔드를 다룹니다. 첫 장은 Python API의 기본 — Value, Type, Frame, Symbol 같은 핵심 객체로 디버기 안의 데이터를 조작하는 법.

#활성화 확인

1
(gdb) python print("hello")
2
hello
3

4
(gdb) python import sys; print(sys.version)
5
3.11.5 (main, ...)

GDB 빌드 시 --with-python 옵션이 켜져 있어야 합니다. 모든 배포판의 기본 패키지가 켭니다. 안 켜진 GDB면 python 명령이 에러.

내장 Python의 버전은 GDB 빌드 시점에 결정. 외부 시스템 Python의 venv·third-party 패키지는 별도 설정 필요.

1
(gdb) python
2
>>> import sys
3
>>> sys.path.insert(0, '/home/me/venv/lib/python3.11/site-packages')
4
>>> import numpy   # 이제 외부 패키지 사용 가능
5
>>> end

#실행 방법

1
(gdb) python print(1 + 2)       # 한 줄
2
3
3

4
(gdb) python                     # 여러 줄
5
>import os
6
>print(os.getpid())
7
>end
8
12345
9

10
(gdb) source my_script.py        # 외부 파일

.gdbinit에 자동 로드:

1
python
2
import sys
3
sys.path.insert(0, '/home/me/gdb-helpers')
4
import myhelpers
5
myhelpers.register_all()
6
end

#핵심 객체 한 표

객체	역할
`gdb.Value`	디버기의 값 (int/string/struct/포인터)
`gdb.Type`	타입 정보 (size, fields, target)
`gdb.Frame`	콜스택의 한 프레임
`gdb.Symbol`	변수·함수 심볼
`gdb.Block`	스코프 블록
`gdb.Inferior`	프로세스
`gdb.Thread`	스레드
`gdb.Breakpoint`	브레이크포인트
`gdb.Objfile`	로드된 ELF/공유라이브러리
`gdb.Architecture`	아키텍처 (x86-64, ARM, …)
`gdb.Progspace`	프로그램 공간

#gdb.Value — 디버기의 값

가장 자주 다루는 객체. 디버기 메모리의 한 영역을 Python에서 다룰 수 있게 래핑한 핸들.

#만들기

1
import gdb
2

3
# 표현식 평가
4
v = gdb.parse_and_eval("my_var")
5
v2 = gdb.parse_and_eval("counter + 1")
6
v3 = gdb.parse_and_eval("(int *)0x600000")
7

8
# 직접 생성
9
n = gdb.Value(42)
10
s = gdb.Value("hello")

gdb.parse_and_eval("expr")이 핵심. GDB의 print 명령이 받는 어떤 표현식이든 받음 — C 문법 + GDB 확장 ($rax, $_thread, *((char *)0x1000)@10 등).

#멤버 접근

1
v = gdb.parse_and_eval("my_struct")
2

3
# 멤버
4
x = v['x']                    # struct.x
5
y = v['y']                    # struct.y
6

7
# 중첩
8
nested = v['inner']['count']
9

10
# 포인터 deref
11
p = gdb.parse_and_eval("ptr")
12
target = p.dereference()      # *ptr
13

14
# 배열 인덱스
15
arr = gdb.parse_and_eval("my_array")
16
first = arr[0]                # my_array[0]
17
slice = arr[0:10]             # 10개

#Python 타입으로

1
# 정수
2
n = int(v)
3
n = int(v['count'])
4

5
# 문자열 (C string)
6
s = v['name'].string()        # NUL까지
7
s = v.string(encoding='utf-8', length=20)
8

9
# 부동 소수
10
f = float(v['ratio'])
11

12
# byte buffer
13
buf = bytes(v['data'])

string()은 C 스타일 문자열 (NUL terminated 또는 길이 지정). bytes()는 raw 메모리.

#산술

1
v = gdb.parse_and_eval("a")
2
w = gdb.parse_and_eval("b")
3

4
result = v + w               # 디버기 안에서 평가 안 됨, Python 측 산술
5
result = v * 2
6

7
# 디버기 안에서 평가
8
result = gdb.parse_and_eval(f"({v}) + ({w})")

gdb.Value 끼리의 산술은 Python 측에서 일어남. 디버기 측 함수 호출은 gdb.parse_and_eval 안에서.

#Cast

1
p = gdb.parse_and_eval("(void *)0x600000")
2
t = gdb.lookup_type("MyStruct")
3
pp = p.cast(t.pointer())          # (MyStruct *)0x600000
4
val = pp.dereference()
5
print(val['field'])

gdb.lookup_type("name")이 타입을 찾고, t.pointer()로 포인터 타입, .cast(t)로 변환.

#dynamic_cast (C++ vtable 기반)

1
base_ptr = gdb.parse_and_eval("base")
2
derived_t = gdb.lookup_type("Derived").pointer()
3
derived = base_ptr.dynamic_cast(derived_t)  # 또는 None

set print object on 효과의 프로그램적 버전.

#gdb.Type

1
t = gdb.lookup_type("MyStruct")
2
print(t.sizeof)               # 바이트 크기
3
print(t.tag)                  # 태그 이름
4
print(t.code)                 # gdb.TYPE_CODE_STRUCT 등
5

6
# 필드 순회
7
for f in t.fields():
8
    print(f.name, f.type, f.bitpos)

#TYPE_CODE 카탈로그

1
gdb.TYPE_CODE_PTR        # 포인터
2
gdb.TYPE_CODE_ARRAY      # 배열
3
gdb.TYPE_CODE_STRUCT     # struct
4
gdb.TYPE_CODE_UNION
5
gdb.TYPE_CODE_ENUM
6
gdb.TYPE_CODE_TYPEDEF
7
gdb.TYPE_CODE_FUNC
8
gdb.TYPE_CODE_INT
9
gdb.TYPE_CODE_FLT
10
gdb.TYPE_CODE_BOOL
11
gdb.TYPE_CODE_REF        # T&
12
gdb.TYPE_CODE_VOID

타입 검사:

1
if v.type.code == gdb.TYPE_CODE_PTR:
2
    target = v.dereference()
3
elif v.type.code == gdb.TYPE_CODE_STRUCT:
4
    for f in v.type.fields():
5
        print(f.name, v[f.name])

#typedef 풀기

1
t = gdb.lookup_type("size_t")
2
print(t)                     # "size_t"
3
print(t.strip_typedefs())    # "unsigned long"
4
print(t.unqualified())       # const/volatile 제거
5
print(t.target())            # 포인터/typedef의 base

pretty-printer에서 자주 — 같은 컨테이너의 다양한 typedef 변형을 한 패턴으로 처리.

#template parameter

1
t = gdb.lookup_type("std::vector<int>")
2
for i in range(t.target_type.fields().__len__()):
3
    pass
4

5
# 또는 template 인자 직접
6
print(t.template_argument(0))   # 첫 template 인자 (예: int)

std::vector<int> → template_argument(0) = int 타입. STL pretty-printer가 이걸로 원소 타입을 알아냄.

#gdb.Frame — 콜스택

1
frame = gdb.selected_frame()         # 현재 프레임
2
print(frame.name())                   # 함수 이름 또는 None
3
print(frame.pc())                     # PC
4
print(frame.function())               # gdb.Symbol
5
print(frame.find_sal())               # gdb.Symtab_and_line (file/line)

#위/아래 이동

1
older = frame.older()                 # 호출자
2
newer = frame.newer()                 # 피호출자

순회.

1
f = gdb.newest_frame()
2
depth = 0
3
while f is not None:
4
    print(f"#{depth}  {f.name() or '??'}")
5
    f = f.older()
6
    depth += 1

#프레임 안의 변수

1
frame = gdb.selected_frame()
2
var = frame.read_var("local_var")     # 변수 read
3
print(var)

또는 gdb.parse_and_eval이 현재 프레임 컨텍스트에서 평가.

#블록 순회

1
block = frame.block()
2
while block:
3
    for sym in block:
4
        if sym.is_variable or sym.is_argument:
5
            try:
6
                value = sym.value(frame)
7
                print(f"{sym.name} = {value}")
8
            except gdb.error:
9
                pass            # optimized out
10
    block = block.superblock

스코프 nested 전부 — 함수 인자, 지역 변수, 정적, 전역. info locals/info args의 Python 버전.

#gdb.Inferior

1
inferior = gdb.selected_inferior()
2
print(inferior.pid)
3
print(inferior.num)              # GDB의 인페리어 번호
4

5
# 모든 스레드
6
for thread in inferior.threads():
7
    print(thread.num, thread.name, thread.is_stopped())
8

9
# 메모리 read / write
10
buf = inferior.read_memory(0x600000, 100)
11
print(bytes(buf).hex())
12

13
inferior.write_memory(0x600000, b'\x01\x02\x03')
14

15
# 메모리 검색
16
found = inferior.search_memory(0x400000, 0x100000, b'hello')
17
if found:
18
    print(f"found at {found:#x}")

read_memory/write_memory가 디버기 메모리에 직접 접근. pretty-printer 같은 곳에서 struct 안의 raw 데이터를 빠르게 가져올 때.

#모든 인페리어

1
for inf in gdb.inferiors():
2
    print(inf.num, inf.pid)

set follow-fork-mode child + detach-on-fork off로 fork된 자식까지 추적할 때 여러 인페리어가 있음.

#gdb.Symbol

1
# 이름으로 lookup
2
sym, is_field = gdb.lookup_symbol("main")
3
print(sym.name, sym.type, sym.value())
4

5
# 전역 심볼
6
sym = gdb.lookup_global_symbol("g_config")

#속성

1
sym.name             # 이름
2
sym.linkage_name     # C++ mangled name
3
sym.print_name       # 사용자 표시용 (demangled)
4
sym.type             # gdb.Type
5
sym.symtab           # 정의된 소스 파일
6
sym.line             # 정의 줄
7
sym.addr_class       # gdb.SYMBOL_LOC_REGISTER, ...
8

9
sym.is_argument
10
sym.is_function
11
sym.is_variable
12
sym.is_constant
13
sym.is_valid()

#addr_class

1
gdb.SYMBOL_LOC_STATIC      # 정적 (전역, .data/.bss)
2
gdb.SYMBOL_LOC_REGISTER    # 레지스터
3
gdb.SYMBOL_LOC_ARG         # 함수 인자
4
gdb.SYMBOL_LOC_REF_ARG     # reference 인자
5
gdb.SYMBOL_LOC_LOCAL       # 지역 변수
6
gdb.SYMBOL_LOC_TYPEDEF
7
gdb.SYMBOL_LOC_BLOCK       # 함수
8
gdb.SYMBOL_LOC_CONST       # 상수
9
gdb.SYMBOL_LOC_OPTIMIZED_OUT
10
gdb.SYMBOL_LOC_COMPUTED    # 위치가 DWARF expression

SYMBOL_LOC_OPTIMIZED_OUT이면 <optimized out>. pretty-printer에서 변수를 못 읽는 상황을 우아하게 처리.

#gdb.execute — 임의 명령

1
output = gdb.execute("info threads", to_string=True)
2
print(output)
3

4
gdb.execute("break main")
5
gdb.execute("continue")

to_string=True로 출력을 캡처. 출력 분석이 필요한 자동화에 핵심.

#묶어 보기

1
def list_all_breakpoints():
2
    out = gdb.execute("info breakpoints", to_string=True)
3
    for line in out.splitlines():
4
        if line.strip().startswith(tuple("0123456789")):
5
            print(line)

GDB 명령 출력을 Python에서 후처리.

#단순 출력

1
gdb.write("hello\n")                   # stdout
2
gdb.write("error\n", gdb.STDERR)
3
gdb.flush()

print()도 동작하지만 gdb.write가 GDB 출력 시스템과 매끄러움 (TUI 모드 등).

#Exception

1
try:
2
    v = gdb.parse_and_eval("nonexistent_var")
3
except gdb.error as e:
4
    gdb.write(f"error: {e}\n")

gdb.error가 모든 GDB API 오류의 base.

#무한 정지 방지

1
def safe_eval(expr):
2
    try:
3
        return gdb.parse_and_eval(expr)
4
    except gdb.error:
5
        return None

pretty-printer에서 없는 멤버 접근이 흔하므로 wrapper로 보호.

#디버깅 — print-stack

1
(gdb) set python print-stack full

이후 Python 예외의 전체 traceback이 콘솔에 출력. 자체 스크립트 디버깅에 필수.

1
(gdb) python my_buggy_code()
2
Traceback (most recent call last):
3
  File "<string>", line 1, in <module>
4
  File "/path/to/script.py", line 42, in my_buggy_code
5
    x = v['nonexistent']
6
gdb.error: There is no member named nonexistent.

#한 예 — 짧은 진단 명령

1
import gdb
2

3
class WhereAmI(gdb.Command):
4
    """현재 위치 종합 정보."""
5

6
    def __init__(self):
7
        super().__init__("whereami", gdb.COMMAND_USER)
8

9
    def invoke(self, arg, from_tty):
10
        try:
11
            frame = gdb.selected_frame()
12
        except gdb.error:
13
            gdb.write("no frame (process not running?)\n")
14
            return
15

16
        pc = int(frame.pc())
17
        name = frame.name() or '??'
18
        sal = frame.find_sal()
19
        file = sal.symtab.filename if sal.symtab else '??'
20
        line = sal.line
21

22
        thread = gdb.selected_thread()
23
        tid = thread.num
24

25
        gdb.write(f"thread {tid}, PC = {pc:#x}\n")
26
        gdb.write(f"function: {name}\n")
27
        gdb.write(f"location: {file}:{line}\n")
28

29
        # 인자
30
        block = frame.block()
31
        gdb.write("args:\n")
32
        for sym in block:
33
            if sym.is_argument:
34
                try:
35
                    val = sym.value(frame)
36
                    gdb.write(f"  {sym.name} = {val}\n")
37
                except gdb.error:
38
                    gdb.write(f"  {sym.name} = <optimized out>\n")
39

40
WhereAmI()

(gdb) source whereami.py → (gdb) whereami → 한 화면에 모든 정보. 일상 디버깅에 매우 유용.

#메모리 검색 — 한 예

1
import gdb
2

3
class FindStr(gdb.Command):
4
    """프로세스 메모리에서 문자열 검색."""
5

6
    def __init__(self):
7
        super().__init__("findstr", gdb.COMMAND_USER)
8

9
    def invoke(self, arg, from_tty):
10
        inf = gdb.selected_inferior()
11
        pattern = arg.encode()
12
        # vmap에서 모든 R/W 영역 (info proc mappings 필요)
13
        mappings = gdb.execute("info proc mappings", to_string=True)
14
        for line in mappings.splitlines():
15
            parts = line.split()
16
            if len(parts) < 5: continue
17
            try:
18
                start = int(parts[0], 16)
19
                end = int(parts[1], 16)
20
            except ValueError:
21
                continue
22
            size = end - start
23
            if size > 100*1024*1024: continue   # skip huge
24
            try:
25
                found = inf.search_memory(start, size, pattern)
26
                if found:
27
                    gdb.write(f"found at {found:#x}\n")
28
            except gdb.error:
29
                pass
30

31
FindStr()

1
(gdb) findstr password
2
found at 0x7ffff7d2c8a0
3
found at 0x55555556a280

#정리

GDB 내장 Python으로 디버기 데이터에 접근.
핵심 객체: Value, Type, Frame, Symbol, Inferior, Thread.
gdb.parse_and_eval(expr)이 만능 진입점.
gdb.execute(..., to_string=True)로 명령 출력 캡처.
inferior.read_memory/write_memory/search_memory로 raw 메모리.
예외는 gdb.error. set python print-stack full로 디버깅.
짧은 명령 한 두 개로도 일상 디버깅 효율이 크게 늘어남.

#다음 장 예고

Ch 2 — 커스텀 명령, Convenience function, Event hook, Breakpoint subclass.

#관련 항목

Ch 2: 커스텀 명령과 이벤트
GDB Python API 공식 문서
Ch 6: 프런트엔드
set python print-stack full — 스크립트 디버깅

#활성화 확인

#실행 방법

#핵심 객체 한 표

#gdb.Value — 디버기의 값

#만들기

#멤버 접근

#Python 타입으로

#산술

#Cast

#dynamic_cast (C++ vtable 기반)

#gdb.Type

#TYPE_CODE 카탈로그

#typedef 풀기

#template parameter

#gdb.Frame — 콜스택

#위/아래 이동

#프레임 안의 변수

#블록 순회

#gdb.Inferior

#모든 인페리어

#gdb.Symbol

#속성

#addr_class

#gdb.execute — 임의 명령

#묶어 보기

#단순 출력

#Exception

#무한 정지 방지

#디버깅 — print-stack

#한 예 — 짧은 진단 명령

#메모리 검색 — 한 예

#정리

#다음 장 예고

#관련 항목

GDB Extension and IDE · 1 of 6

관련 글

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

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

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

이 글을 참조하는 글 (5)