GDB Extension and IDE · 2/6

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

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

GDB 명령을 내가 만든다는 것이 Python API의 두 번째 즐거움입니다. 단순 매크로부터 자동 BP 액션, 정지마다 떨어지는 통계까지 — 모두 같은 패턴 (gdb.Command / gdb.Function / gdb.Breakpoint / 이벤트 hook)으로 가능합니다.

#gdb.Command — 사용자 명령

1
import gdb
2

3
class HelloCmd(gdb.Command):
4
    """간단한 인사 명령."""
5
    def __init__(self):
6
        super().__init__("hello", gdb.COMMAND_USER)
7
    def invoke(self, arg, from_tty):
8
        argv = gdb.string_to_argv(arg)
9
        name = argv[0] if argv else "world"
10
        gdb.write(f"hello, {name}\n")
11

12
HelloCmd()

gdb.string_to_argv(arg)가 셸 스타일 파싱 — quote·escape 처리.

1
(gdb) hello
2
hello, world
3
(gdb) hello "Mr. Smith"
4
hello, Mr. Smith

#COMMAND_* 카테고리

help <category>로 분류 보기.

1
COMMAND_NONE        분류 없음
2
COMMAND_RUNNING     run, step, continue 류
3
COMMAND_DATA        print, x 류
4
COMMAND_STACK       bt, frame 류
5
COMMAND_FILES       file, load 류
6
COMMAND_SUPPORT     set, show 류
7
COMMAND_STATUS      info 류
8
COMMAND_BREAKPOINTS break, watch 류
9
COMMAND_TRACEPOINTS tracepoint
10
COMMAND_USER        사용자
11
COMMAND_OBSCURE
12
COMMAND_MAINTENANCE

내 명령이 어디 보일지를 결정. 진단 명령은 COMMAND_STATUS, 트리거는 COMMAND_BREAKPOINTS 같은 식으로.

#Completion

탭 자동 완성을 켜려면.

1
class MyCmd(gdb.Command):
2
    def __init__(self):
3
        super().__init__("mycmd", gdb.COMMAND_USER, gdb.COMPLETE_SYMBOL)

종류	설명
COMPLETE_NONE	없음
COMPLETE_FILENAME	파일명
COMPLETE_LOCATION	위치 (`function`, `file:line`)
COMPLETE_COMMAND	GDB 명령
COMPLETE_SYMBOL	심볼 이름
COMPLETE_EXPRESSION	표현식

#Custom completion

1
class MyCmd(gdb.Command):
2
    def __init__(self):
3
        super().__init__("mycmd", gdb.COMMAND_USER, gdb.COMPLETE_NONE)
4
    def complete(self, text, word):
5
        candidates = ['foo', 'bar', 'baz']
6
        return [c for c in candidates if c.startswith(word)]
7
    def invoke(self, arg, from_tty):
8
        ...

도구 안에 제한된 옵션이 있을 때 (예: mycmd start | stop | status).

#Prefix 명령 — 서브 명령 트리

1
class MyTop(gdb.Command):
2
    def __init__(self):
3
        super().__init__("my", gdb.COMMAND_USER, prefix=True)
4
    def invoke(self, arg, from_tty):
5
        gdb.execute("help my")
6

7
class MyList(gdb.Command):
8
    def __init__(self):
9
        super().__init__("my list", gdb.COMMAND_USER)
10
    def invoke(self, arg, from_tty):
11
        gdb.write("listing...\n")
12

13
class MyStop(gdb.Command):
14
    def __init__(self):
15
        super().__init__("my stop", gdb.COMMAND_USER)
16
    def invoke(self, arg, from_tty):
17
        gdb.write("stopping...\n")
18

19
MyTop(); MyList(); MyStop()

my list, my stop 같은 서브 명령. 큰 도구 묶음을 깔끔하게.

#Parameter — 사용자 설정 가능 옵션

1
import gdb
2

3
class MyVerbosity(gdb.Parameter):
4
    """my-verbose: 도구의 출력 상세도."""
5
    def __init__(self):
6
        super().__init__("my-verbose",
7
                         gdb.COMMAND_SUPPORT,
8
                         gdb.PARAM_INTEGER)
9
        self.value = 1
10
    def get_set_string(self):
11
        return f"my-verbose set to {self.value}"
12
    def get_show_string(self, value):
13
        return f"my-verbose is currently {value}"
14

15
MyVerbosity()

1
(gdb) set my-verbose 3
2
my-verbose set to 3
3
(gdb) show my-verbose
4
my-verbose is currently 3

gdb.PARAM_* 종류: BOOLEAN, AUTO_BOOLEAN, INTEGER, UINTEGER, STRING, FILENAME, ENUM, …

도구가 사용자 옵션을 가질 때.

1
# 다른 곳에서 접근
2
v = gdb.parameter("my-verbose")
3
if v > 1:
4
    gdb.write("verbose info\n")

#gdb.Function — Convenience function

$<name>(...) 형태로 표현식 안에서 호출 가능한 함수.

1
import gdb
2

3
class StrLen(gdb.Function):
4
    """문자열 길이 반환."""
5
    def __init__(self):
6
        super().__init__("strlen2")
7
    def invoke(self, str_arg):
8
        s = str_arg.string()
9
        return len(s)
10

11
StrLen()

1
(gdb) print $strlen2(msg)
2
$1 = 12
3

4
(gdb) break process if $strlen2(buffer) > 100

조건부 BP에서 매우 강력. 복잡한 조건을 함수로 캡슐화.

#이벤트 훅

1
import gdb
2

3
def on_stop(event):
4
    if isinstance(event, gdb.BreakpointEvent):
5
        bps = event.breakpoints
6
        gdb.write(f"stopped at BP #{bps[0].number}\n")
7
    elif isinstance(event, gdb.SignalEvent):
8
        gdb.write(f"stopped by signal {event.stop_signal}\n")
9

10
def on_exited(event):
11
    gdb.write(f"exit code {event.exit_code}\n")
12

13
def on_new_obj(event):
14
    gdb.write(f"loaded {event.new_objfile.filename}\n")
15

16
def on_cont(event):
17
    gdb.write("continuing...\n")
18

19
gdb.events.stop.connect(on_stop)
20
gdb.events.exited.connect(on_exited)
21
gdb.events.new_objfile.connect(on_new_obj)
22
gdb.events.cont.connect(on_cont)

이벤트 종류.

이벤트	의미
`gdb.events.stop`	정지 (BP, signal, watch)
`gdb.events.cont`	continue
`gdb.events.exited`	프로세스 종료
`gdb.events.new_objfile`	새 ELF 로드
`gdb.events.free_objfile`	ELF unload
`gdb.events.clear_objfiles`	모든 ELF 클리어
`gdb.events.new_inferior`	새 인페리어 (fork 등)
`gdb.events.inferior_deleted`	인페리어 제거
`gdb.events.new_thread`	새 스레드
`gdb.events.gdb_exiting`	GDB 종료
`gdb.events.before_prompt`	프롬프트 표시 전
`gdb.events.memory_changed`	메모리 쓰기
`gdb.events.register_changed`	레지스터 쓰기
`gdb.events.breakpoint_created/modified/deleted`	BP 관리

#활용 — 특정 라이브러리 로드 시 자동 셋업

1
def on_new_obj(event):
2
    name = event.new_objfile.filename
3
    if 'libmylib.so' in name:
4
        gdb.execute("source /opt/mylib/gdb-helpers.py")
5
        gdb.write(f"loaded mylib helpers\n")
6

7
gdb.events.new_objfile.connect(on_new_obj)

#활용 — 매 정지마다 통계

1
class StopCounter:
2
    def __init__(self):
3
        self.count = 0
4
        gdb.events.stop.connect(self.on_stop)
5
    def on_stop(self, event):
6
        self.count += 1
7
        gdb.write(f"\n--- stopped {self.count} times so far ---\n")
8

9
StopCounter()

#활용 — 무한 루프 진단

별도 스레드에서 1초마다 info threads.

1
import threading, time, gdb
2

3
class ThreadDumper:
4
    def __init__(self):
5
        self.stop_event = threading.Event()
6
        self.thread = threading.Thread(target=self.loop)
7
        self.thread.daemon = True
8
    def start(self):
9
        self.thread.start()
10
    def stop(self):
11
        self.stop_event.set()
12
    def loop(self):
13
        while not self.stop_event.wait(1.0):
14
            gdb.post_event(lambda: gdb.execute("info threads"))

gdb.post_event(...)이 GDB 메인 스레드에서 콜백 실행 — GDB API는 main thread only.

#gdb.Breakpoint — Python 서브클래스

브레이크포인트의 행동을 Python으로 정의.

1
import gdb
2

3
class LogAllocs(gdb.Breakpoint):
4
    def __init__(self):
5
        super().__init__("malloc")
6
    def stop(self):
7
        size = int(gdb.parse_and_eval("$rdi"))   # x86-64 첫 인자
8
        gdb.write(f"malloc({size})\n")
9
        return False    # False = 정지하지 않고 continue
10

11
LogAllocs()

stop() 반환값.

True → 정지 (사용자에게 제어).
False → 자동 continue.

기본 commands silent printf의 효과지만 Python의 모든 표현력.

#조건부 자동 액션

1
class BigMalloc(gdb.Breakpoint):
2
    def __init__(self):
3
        super().__init__("malloc")
4
    def stop(self):
5
        size = int(gdb.parse_and_eval("$rdi"))
6
        if size > 1024 * 1024:
7
            gdb.write(f"big malloc: {size} bytes\n")
8
            gdb.execute("bt 5")
9
            return True   # 정지
10
        return False
11

12
BigMalloc()

#Watchpoint 서브클래스

1
class TrackWrites(gdb.Breakpoint):
2
    def __init__(self, expr):
3
        super().__init__(expr, gdb.BP_WATCHPOINT, gdb.WP_WRITE)
4
    def stop(self):
5
        val = gdb.parse_and_eval(self.location)
6
        gdb.write(f"{self.location} = {val}\n")
7
        return False
8

9
TrackWrites("g_counter")

GDB의 watch g_counter를 프로그램 측에서 설치.

#Internal vs User

1
super().__init__("malloc", internal=True)

internal=True면 사용자 BP 목록에 안 보임. 자동화 도구가 몰래 BP 설치할 때.

#.gdbinit으로 자동 로드

1
set history save on
2
set print pretty on
3

4
python
5
import sys
6
sys.path.insert(0, '/home/me/gdb-helpers')
7
import myhelpers
8
myhelpers.register_all()
9
end

또는 프로젝트별 .gdbinit (GDB 8.0+, 보안상 add-auto-load-safe-path).

1
add-auto-load-safe-path .
2
source ./gdb-helpers/init.py

1
(gdb) set auto-load local-gdbinit on

#자주 쓰는 패턴

#1. 메모리 누수 추적

1
import gdb
2
from collections import defaultdict
3

4
alloc_table = {}
5
alloc_count = defaultdict(int)
6

7
class MallocTrack(gdb.Breakpoint):
8
    def __init__(self):
9
        super().__init__("malloc", internal=True)
10
    def stop(self):
11
        size = int(gdb.parse_and_eval("$rdi"))
12
        # rax는 return 후 — finish 사용
13
        gdb.events.stop.connect(self._capture_return)
14
        self.size = size
15
        return False
16
    def _capture_return(self, event):
17
        addr = int(gdb.parse_and_eval("$rax"))
18
        alloc_table[addr] = self.size
19
        alloc_count[self.size] += 1
20
        gdb.events.stop.disconnect(self._capture_return)
21

22
class FreeTrack(gdb.Breakpoint):
23
    def __init__(self):
24
        super().__init__("free", internal=True)
25
    def stop(self):
26
        addr = int(gdb.parse_and_eval("$rdi"))
27
        if addr in alloc_table:
28
            del alloc_table[addr]
29
        return False
30

31
MallocTrack(); FreeTrack()
32

33
def dump_leaks(_evt=None):
34
    if not alloc_table:
35
        gdb.write("no leaks\n"); return
36
    total = sum(alloc_table.values())
37
    gdb.write(f"{len(alloc_table)} allocations leaked, {total} bytes\n")
38

39
gdb.events.exited.connect(dump_leaks)

운영에는 ASan을 쓰지만 원리 학습에 매우 유용.

#2. 함수 호출 통계

1
class CountCalls(gdb.Breakpoint):
2
    def __init__(self, fn):
3
        super().__init__(fn, internal=True)
4
        self.count = 0
5
        self.name = fn
6
    def stop(self):
7
        self.count += 1
8
        return False
9

10
watchers = []
11
for fn in ['process_request', 'handle_packet', 'send_response']:
12
    watchers.append(CountCalls(fn))
13

14
def report(_evt=None):
15
    for w in watchers:
16
        gdb.write(f"{w.name}: {w.count} calls\n")
17
gdb.events.exited.connect(report)

perf로 할 수도 있지만 정확한 조건부 카운트는 GDB가 유리.

#3. 표현식 추적 (display의 자동화)

1
class Tracer:
2
    def __init__(self, exprs):
3
        self.exprs = exprs
4
        gdb.events.stop.connect(self.on_stop)
5
    def on_stop(self, _evt):
6
        for e in self.exprs:
7
            try:
8
                v = gdb.parse_and_eval(e)
9
                gdb.write(f"  {e} = {v}\n")
10
            except gdb.error:
11
                gdb.write(f"  {e} = <error>\n")
12

13
Tracer(['counter', 'state', 'queue.size()'])

매 정지마다 지정 표현식들 출력. display의 Python 버전.

#헤드리스 모드 — batch

1
$ gdb -batch -ex 'source script.py' -ex 'run' -ex 'quit' --args ./prog

-batch로 사용자 입력 없이 스크립트 실행. CI 자동화의 표준.

1
# segfault된 바이너리를 자동으로 분석
2
$ gdb -batch \
3
    -ex 'run' \
4
    -ex 'bt' \
5
    -ex 'info threads' \
6
    -ex 'thread apply all bt' \
7
    --args ./buggy_prog

#정리

gdb.Command 서브클래스로 새 명령. COMMAND_* 카테고리·completion·prefix.
gdb.Parameter로 사용자 옵션.
gdb.Function으로 $name(...) convenience function — 조건부 BP에 강력.
gdb.events.*로 stop / cont / new_objfile / exited 등 hook.
gdb.Breakpoint 서브클래스 + stop() 반환값으로 자동 액션.
internal=True로 사용자 비가시 BP.
.gdbinit에 모두 등록.
gdb -batch로 헤드리스 자동화.

#다음 장 예고

Ch 3 — Pretty-printer 깊이. to_string/children/display_hint, MI 출력, auto-load.

#관련 항목

GDB Extension and IDE · 2 of 6

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

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

2026년 5월 27일·gdb

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

to_string / children / display_hint, MI 출력, auto-load, libstdc++ printer 분석.

2026년 5월 27일·gdb

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

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

2026년 5월 27일·gdb

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

#gdb.Command — 사용자 명령

#COMMAND_* 카테고리

#Completion

#Custom completion

#Prefix 명령 — 서브 명령 트리

#Parameter — 사용자 설정 가능 옵션

#gdb.Function — Convenience function

#이벤트 훅

#활용 — 특정 라이브러리 로드 시 자동 셋업

#활용 — 매 정지마다 통계

#활용 — 무한 루프 진단

#gdb.Breakpoint — Python 서브클래스

#조건부 자동 액션

#Watchpoint 서브클래스

#Internal vs User

#.gdbinit으로 자동 로드

#자주 쓰는 패턴

#1. 메모리 누수 추적

#2. 함수 호출 통계

#3. 표현식 추적 (display의 자동화)

#헤드리스 모드 — batch

#정리

#다음 장 예고

#관련 항목

GDB Extension and IDE · 2 of 6

관련 글

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

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

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

이 글을 참조하는 글 (3)