C++ 구조체를 Go로 옮길 때 바이트 맞추기: 패딩·정렬·엔디언·비트필드 직접 실험

이 글의 핵심

C++의 구조체를 그대로 파일이나 소켓에 쓰던 코드를 Go로 옮기면 헤더 몇 바이트가 어긋나서 값이 엉뚱하게 읽힙니다. 같은 헤더를 C++에서 만든 파일을 Go로 읽어 보니, 구조체 레이아웃 규칙은 거의 같았지만 binary.Read는 패딩을 건너뛰지 않았고, packed 구조체와 비트필드는 Go에 대응이 없어 직접 풀어야 했습니다.

C++로 짠 서버가 구조체를 fwrite나 send로 그대로 내보내고, 그 데이터를 Go 프로그램이 읽어야 하는 상황은 흔합니다. 헤더에 uint16 magic, uint8 kind, uint32 len, uint64 seq를 둔 아주 평범한 구조체인데도, Go에서 읽으면 len이 엉뚱한 값으로 나옵니다. 원인은 대개 “바이트가 어디에 놓였는가”에 대한 가정이 두 언어에서 다르다는 것입니다.

이 글은 같은 헤더를 C++로 쓴 파일을 만들고 Go로 읽어 보면서, 옮길 때 확인해야 할 것들을 실행 결과로 정리한 것입니다. 모든 실험은 Apple clang 21.0.0, Go 1.22.4, macOS arm64(리틀 엔디언)에서 했습니다. 리눅스 x86-64, 윈도, GCC, MSVC에서는 돌려 보지 못했습니다. 그런 부분은 “확인하지 못했다”고 따로 적었습니다.

먼저 알아 둘 것: 구조체 레이아웃 규칙은 거의 같다

C++과 Go는 구조체 필드를 선언한 순서대로 배치하고, 각 필드를 자기 정렬 단위(보통 크기와 같은 값)의 배수 위치에 놓습니다. 그 결과 구조체 전체 크기는 가장 큰 정렬 단위의 배수가 됩니다. 아래 구조체를 두 언어에서 같은 순서로 선언했습니다.

struct Hdr { uint16_t magic; uint8_t kind; uint32_t len; uint64_t seq; };
type Hdr struct {
	Magic uint16
	Kind  uint8
	Len   uint32
	Seq   uint64
}

C++에서는 sizeof와 offsetof, Go에서는 unsafe.Sizeof와 unsafe.Offsetof로 같은 값을 뽑아 비교했습니다.

C++ (clang, arm64)Go 1.22 (arm64)
전체 크기1616
magic / kind / len / seq 오프셋0 / 2 / 4 / 80 / 2 / 4 / 8

kind(1바이트) 뒤에는 len을 4의 배수 위치에 맞추려고 1바이트 패딩이 들어가서 len이 3이 아니라 4에서 시작합니다. 두 언어가 같은 규칙을 쓰기 때문에, 같은 아키텍처에서 같은 필드 순서와 같은 크기의 정수 타입이라면 레이아웃도 같았습니다. cgo로 C 구조체를 가져와 비교해도 C.sizeof_Hdr가 16으로, Go 구조체 크기와 같았습니다.

필드 순서가 크기를 바꾼다 (Go는 순서를 바꿔 주지 않는다)

Go 컴파일러는 필드를 재배치하지 않습니다. 필드 순서를 잘못 잡으면 크기가 커진다는 점은 C++과 같습니다.

type Bad struct {   // bool, int64, bool, int32, bool
	A bool; B int64; C bool; D int32; E bool
}
type Good struct {  // int64, int32, bool, bool, bool
	B int64; D int32; A bool; C bool; E bool
}

실행 결과 Bad는 32바이트(오프셋 A=0, B=8, C=16, D=20, E=24), Good은 16바이트(B=0, D=8, A=12, C=13, E=14)였습니다. 같은 필드를 가졌는데 순서만 달라서 크기가 두 배가 되었습니다. 큰 타입부터 작은 타입 순으로 선언하면 대개 패딩이 줄어듭니다. 다만 이 순서를 지키면 읽기 좋은 논리 순서(예: 헤더 필드 순서)와 충돌할 수 있어서, 파일이나 네트워크 포맷을 맞추는 구조체라면 포맷 순서를 먼저 지키고 크기는 신경 쓰지 않는 편이 낫습니다.

같은 이름의 타입이라도 크기가 다르다

이식에서 가장 먼저 부딪히는 문제입니다. 이 맥(arm64, Apple clang)에서 sizeof와 unsafe.Sizeof를 찍어 본 값입니다.

타입C++Go
int48
long8(대응 없음. int64처럼 크기를 직접 지정)
long long8int64 8
size_t8uint, uintptr 8
bool11
wchar_t4rune(int32) 4
long double8 (이 환경)(대응 없음. complex128은 16으로 다른 타입)
포인터88
std::string24 (libc++)string 16 (포인터 + 길이)
슬라이스-24 (포인터 + 길이 + 용량)

가장 위험한 줄은 int입니다. C++에서 4바이트인 int를 Go의 int로 옮기면 64비트 환경에서 8바이트가 됩니다. 구조체가 외부 포맷과 연결된다면 int32, uint32처럼 크기가 정해진 타입으로 옮겨야 합니다. 실제로 int 필드를 가진 구조체를 binary.Read에 넘기면 binary.Read: invalid type *main.WithInt 에러로 거부됩니다. 문자열 필드도 같은 에러였습니다. 즉 binary.Read는 크기가 정해진 타입(고정 크기 정수·부동소수점·bool, 이를 담은 배열과 구조체)만 받습니다.

C++의 long과 wchar_t, long double은 플랫폼마다 크기가 다릅니다. 이 맥에서 long은 8이었지만, 윈도에서는 4라고 알려져 있습니다. 저는 윈도에서 확인하지 못했습니다. long double도 이 환경에서는 double과 같은 8바이트였지만, 다른 플랫폼에서는 더 큰 확장 정밀도일 수 있어서 Go로 옮길 때 대응 타입이 없습니다. 파일 포맷이나 프로토콜에 이런 타입이 들어 있으면, 먼저 C++ 쪽을 int32_t, uint64_t 같은 고정 폭 타입으로 바꿔 두는 것이 가장 확실합니다.

binary.Read는 패딩을 건너뛰지 않는다

핵심 실험입니다. C++에서 Hdr를 memset(&h, 0xAA, sizeof h)로 채운 뒤 필드를 설정하고 fwrite로 16바이트를 썼습니다. 덤프하면 아래와 같습니다.

00000000: feca 07aa 0403 0201 8877 6655 4433 2211

fe ca가 magic(리틀 엔디언), 07이 kind, 그다음 aa가 패딩, 04 03 02 01이 len, 88 ... 11이 seq입니다. 패딩 위치(오프셋 3)에는 memset으로 채운 값(aa)이 그대로 남아 있습니다. 이는 C++에서 구조체를 통째로 내보내면 패딩에 있던 쓰레기 값도 같이 나간다는 뜻이기도 합니다. 초기화하지 않은 구조체를 보냈다면 스택에 남아 있던 값이 노출될 수 있습니다.

이 16바이트를 Go에서 binary.Read로 읽으면 어떻게 될까요.

var h Hdr
binary.Read(bytes.NewReader(pad), binary.LittleEndian, &h)

binary.Size(Hdr{})가 15를 돌려줍니다. binary.Read는 필드를 순서대로 이어 붙인 15바이트를 읽을 뿐 패딩 1바이트를 건너뛰지 않습니다. 그래서 16바이트 파일에서는 len을 패딩 aa부터 읽어 버립니다.

읽는 방법읽은 Len맞는 값은 0x01020304
binary.Read(Hdr)로 패딩 있는 16바이트 파일을 읽음33752234 (0x0203 04aa)틀림
binary.Read(Hdr)로 패딩 없는 15바이트 파일(#pragma pack(1))을 읽음16909060 (0x01020304)맞음
패딩 필드를 명시한 HdrPad(_ uint8)로 16바이트 파일을 읽음0x01020304맞음
unsafe.Pointer로 16바이트를 *Hdr로 변환해 읽음0x01020304맞음
오프셋을 직접 지정해 binary.LittleEndian.Uint32(b[4:])로 읽음0x01020304맞음

세 번째 줄의 방법이 가장 읽기 쉽습니다. Go는 구조체에 _ 이름의 필드를 두면 그 자리를 건너뛰고 읽습니다.

type HdrPad struct {
	Magic uint16
	Kind  uint8
	_     uint8 // C++ 쪽 패딩 1바이트
	Len   uint32
	Seq   uint64
}

binary.Size(HdrPad{})는 16이고, 읽은 결과도 Magic=0xcafe Kind=7 Len=0x1020304 Seq=0x1122334455667788로 정확했습니다. binary.Write도 같은 구조체에서 _ 필드 자리에 0을 써 넣었습니다. 다만 이 방식은 C++ 쪽 패딩 위치를 직접 계산해서 _ 필드로 적어야 하므로, 필드가 많으면 실수하기 쉽습니다. 크기가 중요하면 unsafe.Sizeof(HdrPad{}) == 16과 unsafe.Offsetof로 단언하는 테스트를 같이 두는 것이 좋습니다. C++ 쪽에서도 같은 값을 static_assert와 offsetof로 고정해 둘 수 있습니다.

속도: binary.Read는 느리다

같은 16바이트를 읽는 세 가지 방법을 Go 벤치마크로 쟀습니다(go test -bench, 1초, 한 번 실행).

방법1회당 시간
binary.Read + bytes.NewReader약 150ns
오프셋 직접 지정(binary.LittleEndian.Uint64(b[8:]) 등)약 1.2ns
unsafe.Pointer 변환약 1.1ns

binary.Read는 리플렉션을 쓰기 때문에 100배 이상 느렸습니다. 헤더 하나를 가끔 읽는 정도면 문제가 없지만, 패킷을 초당 수백만 번 읽는 경로라면 필드를 직접 읽는 쪽이 낫습니다. 이 측정은 측정 코드가 최적화로 일부 사라졌을 가능성이 있어 절대값보다 자릿수 차이만 참고하세요.

#pragma pack과 비트필드: Go에는 대응이 없다

packed 구조체

#pragma pack(push, 1)을 적용한 C++ 구조체는 같은 필드인데도 sizeof가 15, len 오프셋이 3, seq 오프셋이 7이었습니다. Go에는 이런 지시자가 없습니다. 그래서 필드마다 패딩 없이 읽는 쪽으로 풀어야 합니다.

magic := binary.LittleEndian.Uint16(b[0:])
kind  := b[2]
length := binary.LittleEndian.Uint32(b[3:]) // 정렬되지 않은 위치
seq   := binary.LittleEndian.Uint64(b[7:])

binary.LittleEndian.Uint32는 정렬되지 않은 위치에서도 바이트 단위로 읽어서 조립하므로 안전합니다. 위 코드로 15바이트 파일을 읽은 결과가 Len=0x1020304, Seq=0x1122334455667788로 맞았습니다.

cgo로 C의 packed 구조체를 가져오면 어떻게 보일까요. Go가 정렬되지 않은 필드에는 접근할 수 없으므로, 보이는 필드는 magic과 kind뿐이고 나머지는 이름 없는 [12]uint8 덩어리로만 나왔습니다. 리플렉션으로 확인한 결과는 [magic ushort off=0] [kind uchar off=2] [_ [12]uint8 off=3]이었습니다. 즉 packed 구조체의 정렬되지 않은 필드는 cgo에서 직접 읽을 수 없고, 바이트 배열로 받아 직접 풀어야 합니다.

비트필드

C++의 비트필드도 Go에 대응이 없습니다. 아래 구조체를 clang으로 만들어 써 봤습니다.

struct Flags { uint8_t a:3; uint8_t b:5; uint16_t c:10; uint16_t d:6; };
// a=5, b=17, c=0x2A5, d=0x15

sizeof(Flags)는 4였고, 덤프는 8d 00 a5 56이었습니다. a와 b가 첫 바이트(5 | 17<<3 = 0x8d)에, c와 d가 새 2바이트 단위(0x2a5 | 0x15<<10 = 0x56a5)에 들어갔고 두 번째 바이트는 패딩으로 비어 있었습니다. Go에서는 마스크와 시프트로 풀었습니다.

a := fl[0] & 0x7
b := fl[0] >> 3
w := binary.LittleEndian.Uint16(fl[2:])
c := w & 0x3FF
d := w >> 10

결과는 a=5 b=17 c=0x2a5 d=0x15로 C++ 값과 같았습니다. 다만 비트필드가 어느 비트부터 채워지는지, 다음 필드를 새 저장 단위에 놓을지는 C++ 표준이 구현에 맡긴 부분입니다. 이 결과는 이 컴파일러에서 얻은 것이라, 다른 컴파일러에서 만든 데이터를 읽으려면 그쪽 레이아웃을 따로 확인해야 합니다. cgo도 이 구조체는 필드를 노출하지 못하고 _ [4]uint8로만 보여 줬습니다. 가능하면 비트필드를 쓰는 대신 명시적인 바이트와 마스크로 바꾼 뒤 옮기는 편이 안전합니다.

엔디언: 구조체를 통째로 읽으면 가정이 숨어 있다

unsafe.Pointer로 구조체를 변환한 읽기는 이 맥에서 맞았지만, 이는 C++ 코드가 쓴 환경과 읽는 환경이 모두 리틀 엔디언이어서입니다. 호스트 바이트 순서가 다르면 값이 뒤집힙니다. 같은 len 바이트를 일부러 binary.BigEndian으로 읽으면 0x4030201이 나왔습니다. 네트워크 프로토콜이라면 명세가 정한 순서(보통 빅 엔디언)로 읽고 쓰도록 binary.BigEndian을 명시해야 합니다. binary.Read와 binary.Write는 항상 바이트 순서를 인자로 받으므로 이 면에서는 안전합니다. 이식하는 쪽에서 해야 할 일은 C++ 쪽이 htons, htonl 같은 변환을 했는지 확인하는 것입니다.

unsafe로 구조체 변환할 때 알아 둘 것

(*Hdr)(unsafe.Pointer(&b[0]))는 복사가 없어 빠르지만, 몇 가지를 알고 써야 합니다.

  • 바이트 슬라이스의 시작 주소가 구조체의 정렬 단위로 정렬되어 있어야 합니다. 일부러 1바이트 어긋난 위치(buf[1:])를 *Hdr로 변환해 읽어 봤는데, 이 맥(arm64)에서는 값이 맞게 읽혔습니다. 하지만 Go 언어 명세가 이를 보장하는 것은 아니며, 정렬되지 않은 접근을 허용하지 않는 다른 환경에서는 실패할 수 있습니다. 이 맥에서는 -gcflags=all=-d=checkptr를 켜도 오류가 나지 않았고, 다른 아키텍처에서는 확인하지 못했습니다.
  • 패딩 바이트는 C++이 쓴 값 그대로(위 실험에서는 aa)입니다. 비교나 해시에 구조체 전체를 쓰면 패딩 값이 영향을 줄 수 있습니다.
  • 엔디언이 다른 호스트에서는 결과가 다릅니다.

외부에서 들어오는 데이터라면, 아주 빠른 경로가 아닌 이상 필드를 직접 읽는 쪽을 권합니다. 위 벤치마크에서 직접 읽기는 unsafe 변환과 거의 같은 속도(약 1ns)였기 때문에 unsafe를 쓸 이유가 크지 않았습니다.

32비트 환경에서는 int64 정렬이 달라진다

Go 표준 라이브러리의 go/types는 아키텍처별 크기와 오프셋을 계산해 줍니다. 같은 구조체 { uint8 A; int64 B; uint8 C }를 types.SizesFor("gc", arch)로 계산한 결과입니다. 이 값은 직접 실행하지 않고 컴파일러 규칙으로 계산한 것이며, 32비트 바이너리는 이 맥에서 실행하지 못했습니다.

아키텍처크기오프셋 A/B/CHdr(앞의 헤더 구조체) 크기
amd64240 / 8 / 1616
arm64240 / 8 / 1616
386160 / 4 / 1216
arm160 / 4 / 1216

32비트 아키텍처에서는 int64가 4바이트 경계에만 놓이므로 같은 구조체가 8바이트 작아졌습니다. 즉 같은 Go 소스라도 구조체 크기는 대상 아키텍처에 따라 달라집니다. 32비트도 지원해야 한다면 크기가 고정되어야 하는 구조체에는 unsafe.Sizeof 단언을 두거나, 처음부터 필드 단위로 읽고 써서 구조체 레이아웃에 의존하지 않는 편이 안전합니다. 길이가 0인 타입도 주의할 점이 있었습니다. struct{}의 크기는 0이지만, 구조체의 마지막 필드로 두면 패딩이 붙어서 struct{ X int64; E struct{} }가 16바이트(E가 처음이면 8바이트)였습니다.

옮길 때의 체크리스트

실험을 정리하면 옮기기 전에 확인할 항목은 다음과 같았습니다.

  1. 타입 폭 고정: C++ 쪽 int, long, wchar_t, long double을 int32_t, int64_t 같은 고정 폭 타입으로 바꾸고, Go에서는 int32, int64, uint32로 옮깁니다. Go의 int는 쓰지 않습니다.
  2. 크기와 오프셋 단언: C++에는 static_assert(sizeof(Hdr) == 16)과 offsetof, Go에는 unsafe.Sizeof/unsafe.Offsetof 검사 테스트를 둡니다. 두 쪽이 같은 값을 찍는 것을 CI에서 확인합니다.
  3. 패딩 처리: 패딩이 들어 있는 포맷이면 _ 필드로 명시하거나 오프셋을 직접 지정해 읽습니다. binary.Read를 패딩 있는 구조체에 그냥 쓰면 값이 틀어집니다.
  4. packed·비트필드: Go에는 대응이 없으므로 바이트와 마스크로 직접 풀고, cgo로 가져오면 정렬되지 않은 필드와 비트필드가 보이지 않는다는 점을 기억합니다.
  5. 엔디언: 프로토콜이 정한 순서를 binary.BigEndian 또는 binary.LittleEndian으로 명시합니다.
  6. 패딩 쓰레기 값: C++ 쪽에서 구조체를 memset으로 초기화한 뒤 보내지 않으면 패딩에 이전 값이 실려 나갑니다. 필드 단위로 직렬화하면 이 문제도 없어집니다.
  7. 빠른 경로 점검: binary.Read는 약 150ns(이 환경)로 느립니다. 병목이 확인될 때만 직접 읽기로 바꿉니다.

확인하지 못한 것

  • 리눅스 x86-64, 윈도, GCC, MSVC에서의 레이아웃과 long, long double 크기(이 글의 값은 모두 Apple clang + arm64)
  • 빅 엔디언 호스트에서의 unsafe 변환 결과
  • 정렬되지 않은 포인터 변환이 다른 아키텍처에서 실패하는지
  • 32비트 바이너리의 실제 실행 결과(go/types 계산값만 확인)
  • Go 구조체 정렬 검사 도구(fieldalignment)의 출력

C++ 쪽 직렬화 방법 자체는 C++ 바이너리 직렬화 글에서 다룹니다. 이 글의 실험 코드는 모두 한 번 실행한 결과이므로, 자기 환경에서 sizeof와 unsafe.Sizeof부터 직접 찍어 비교해 보는 것이 가장 확실합니다.