perlintern — Perl 인터프리터 내부 전용 함수 문서

perlintern — Perl 인터프리터 내부 전용 함수 문서

문서 성격 안내: 이 문서는 원문 perlintern(autogenerated documentation of purely internal Perl functions)이 엄청나게 큰 자동생성 참조문서(섹션 수십 개, 항목 수백 개, 원문 약 13만 자)라서, 전체 항목 하나하나를 의역하는 대신 충실한 구조화 가이드로 정리했어요. 골격(섹션 목차·대표 항목 완역·원문 가는 길)은 그대로 담았고, 각 함수의 정확한 최신 설명은 원문을 직접 확인하는 걸 권장해요. 참고: 이 문서의 형제 문서 perlapi가 공개 API(익스텐션에서 써도 되는 함수)를 다룬다면, perlintern은 그 반대 — 내부 전용이에요. 두 문서를 함께 보면 그림이 완성돼요.

이 문서가 뭘 말하는 걸까요

Perl 인터프리터는 C로 쓰여 있고, 그 C 함수들 중 상당수는 Perl의 내부 문서 형식으로만 문서화되어 있어요. 그런데 그중 Perl API로 분류되지 않은 것들이 따로 있는데, 그 목록을 자동으로 뽑아 정리한 게 바로 이 perlintern 문서예요.

쉽게 말하면 이렇게 돼요.

  • perlapi → XS 익스텐션을 만들 때 밖에서 써도 되는 공개 함수 모음.
  • perlintern → 인터프리터 내부에서만 쓰는 함수 모음. 익스텐션에서 쓰면 안 돼요.

원문의 좀 단호한 표현을 그대로 옮겨볼게요.

This file is the autogenerated documentation of functions in the Perl interpreter that are documented using Perl's internal documentation format but are not marked as part of the Perl API. In other words, they are not for use in extensions!

즉, 이 문서에 나오는 함수들은 Perl 소스 자체를 고치거나 인터프리터 내부를 들여다보는 사람(코어 개발자)을 위한 거예요. 구조는 perlapi와 같은 섹션 구성을 갖지만, 일부 섹션은 비어 있을 수 있어요.

전체 섹션 목차(원문 그대로의 구조)

이 문서가 어떤 흐름으로 되어 있는지 한눈에 보는 게 중요하니까, 원문의 섹션 목록을 그대로 옮겨 놓을게요. 각 섹션은 비슷한 성격의 내부 함수들을 묶어요.

# 섹션 간단한 설명(가이드 제공용)
1 NAME 문서 이름과 한 줄 정의
2 DESCRIPTION 문서 성격 설명(이 글 앞부분과 같음)
3 AV Handling 배열(AV) 내부 조작 함수
4 Callback Functions 콜백 관련 내부 매크로/함수
5 Casting 타입 변환 관련
6 Character case changing 문자 대소문자 변환(현재 항목 없음)
7 Character classification 문자 분류 매크로(정규식 문자클래스류)
8 Compiler and Preprocessor information 컴파일러·전처리기 정보(현재 항목 없음)
9 Compiler directives 컴파일러 지시어류 매크로
10 Compile-time scope hooks 컴파일 타임 스코프 훅(BHK 구조)
11 Concurrency 실행 컨텍스트(CX/CVt) 관련 동시성 매크로
12 COPs and Hint Hashes 컨트롤 연산 포인터·힌트 해시(현재 항목 없음)
13 Custom Operators 사용자 정의 연산자/코어 프로토타입
14 CV Handling 서브루틴 값(CV) 처리
15 Debugging 디버깅용 함수
16 Declaration and Initialization of Globals 전역 선언·초기화
17 Display functions 표시(출력)용 함수
18 Embedding, Threads, and Interpreter Cloning 임베딩·스레드·인터프리터 클로닝
19 Errno errno 관련
20 Exception Handling (simple) Macros 간단 예외 처리 매크로
21 Filesystem configuration values 파일시스템 설정값
22 Floating point 부동소수점 처리
23 General Configuration 일반 설정값
24 Global Variables 전역 변수
25 GV Handling and Stashes glob(GV)·stash 처리
26 Hook manipulation 훅 조작
27 HV Handling 해시(HV) 내부 조작 함수
28 Input/Output 입출력 관련
29 Integer 정수 관련 매크로
30 I/O Formats I/O 포맷
31 Lexer interface 렉서(어휘 분석기) 인터페이스
32 Locales 로케일 지원
33 Magic magic 부착 처리
34 Memory Management 메모리 관리(Newx/Renew/Safefree 구현체 등)
35 MRO 메서드 해석 순서(Method Resolution Order)
36 Multicall Functions 멀티콜(XSUB 다중 호출)
37 Numeric Functions 수치 함수
38 Optrees op 트리 관련
39 Pack and Unpack pack/unpack 내부
40 Pad Data Structures 패드(pad) 구조체
41 Password and Group access 사용자·그룹 정보 접근
42 Paths to system commands 시스템 명령 경로
43 Prototype information 프로토타입 정보
44 Reference-counted stack manipulation 참조 카운트 스택 조작
45 REGEXP Functions 정규식 엔진 내부
46 Reports and Formats report·format
47 Signals 시그널 처리
48 Site configuration 사이트 설정값
49 Sockets configuration values 소켓 설정값
50 Source Filters 소스 필터
51 Stack Manipulation Macros 스택 조작 매크로
52 String Handling 문자열 처리
53 SV Flags SV 플래그
54 SV Handling 스칼라 값(SV) 처리
55 Tainting taint(오염) 처리
56 Time 시간 관련
57 Typedef names typedef 이름들
58 Unicode Support 유니코드 지원
59 Utility Functions 유틸리티 함수
60 Versioning 버전 관리
61 Warning and Dieing 경고·die 처리
62 XS XS 컴파일 관련
63 Undocumented elements 미문서화 요소 목록
64 AUTHORS 저자
65 SEE ALSO 관련 문서

몇몇 섹션(Character case changing, Compiler와 Preprocessor, COPs and Hint Hashes 등)은 원문 기준 현재 항목이 비어 있는 섹션이에요. API 세대에 따라 채워졌다 비워졌다 하니, 최신 원문을 확인하는 게 좋아요.

대표 항목 완역 — 핵심 섹션 들여다보기

전체를 다 번역하진 않지만, 가장 자주 들여다보게 될 핵심 섹션들의 대표 항목은 제대로 짚어줄게요. 이 패턴을 보면 나머지 항목들도 비슷한 틀로 읽으면 돼요.

각 항목은 보통 이렇게 구성돼요.

  1. 함수 이름(굵은 글씨)
  2. 한두 문단의 설명
  3. C 시그니처(코드 블록) — 두 줄로 나오는 경우가 많아요. Perl_xxx(pTHX_ ...)로 시작하는 건 인터프리터 스레드 문맥(pTHX)을 받는 내부 실제 구현이고, 위쪽 시그니처가 매크로로 쓰는 공용 형태예요.

AV Handling — 배열 다루기

배열(AV) 내부용 함수예요. 공개 API인 av_fetch/av_store의 가벼운 축약판들이 여기 있어요.

av_fetch_simple

av_fetch의 다이어트 버전이에요. 매직(magic)이 없고, 읽기전용이 아니고, AvREAL이고, key가 음수가 아니라는 '단순함'을 전제로 해요. 이 전제 중 하나라도 어긋날 수 있는 상황에서는 절대 쓰면 안 돼요.

배열의 지정 인덱스 위치의 SV를 돌려줘요. lval이 참이면 실제 SV를 돌려받는 게 보장되고, 그걸 수정할 수 있어요. 돌려받은 값을 SV*로 역참조하기 전에 null이 아닌지 먼저 확인하세요.

대략 Perl로는 $myarray[$key]에 해당해요.

SV **       av_fetch_simple(      AV *av, SSize_t key, I32 lval)
SV **  Perl_av_fetch_simple(pTHX_ AV *av, SSize_t key, I32 lval)

av_new_alloc

perlapi의 newAV_alloc_x / newAV_alloc_xz를 내부에서 구현하는 함수예요. 새 AV를 만들고 SV* 배열을 할당해요. 아래처럼 쓰는 것보다 더 효율적이에요.

AV *av = newAV();
av_extend(av, key);

size는 0..(size-1) 요소를 담을 수 있도록 SV* 배열을 미리 할당하는 크기고, 최소 1이어야 해요. zeroflag가 배열을 NULL로 초기화할지 결정해요.

AV *       av_new_alloc(SSize_t size, bool zeroflag)
AV *  Perl_av_new_alloc(pTHX_ SSize_t size, bool zeroflag)

AvFILLp

배열 av가 비어 있으면 -1을, 아니면 현재 정의된 요소들의 최대 인덱스를 돌려줘요. magic을 처리하지 않기 때문에 이름에 p(private)가 붙었어요.

SSize_t  AvFILLp(AV* av)

HV Handling — 해시 다루기

HV 구조는 Perl 해시를 나타내요. 포인터 배열로 되어 있고, 각 포인터는 HE 구조의 연결리스트를 가리켜요. 배열 인덱스는 키의 해시 함수값이라서, 같은 해시값을 가진 항목들이 한 리스트에 묶여요. 각 HE는 실제 값 포인터 + 키와 해시값을 담는 HEK 구조 포인터를 가져요.

대표로 hv_eiter_p/hv_eiter_set 같은 항목이 있는데, 이들은 공개 매크로 HvEITER/HvEITER_set의 내부 구현이에요.

HE **  Perl_hv_eiter_p(pTHX_ HV *hv)

SV Handling — 스칼라 값 다루기

sv_grow

SV 안의 문자 버퍼를 확장해요. 필요하면 sv_unref를 쓰고 SV를 SVt_PV로 승격시켜요. 문자 버퍼 포인터를 돌려줘요. 직접 쓰기보다 SvGROW 래퍼를 쓰는 걸 권장해요.

char *       sv_grow(      SV * const sv, STRLEN newlen)
char *  Perl_sv_grow(pTHX_ SV * const sv, STRLEN newlen)

sv_grow_fresh

sv_grow의 축약판인데, 갓 만든(fresh) SVt_PV/SVt_PVIV/SVt_PVNV/SVt_PVMG에만 쓸 수 있어요. 즉 기본 플래그만 있고, 다른 타입이었던 적이 없고, 기존 문자열이 없는 SV요. 기본적으로 문자 버퍼만 할당하고 포인터를 돌려줘요.

sv_clean_all

남아 있는 각 SV의 refcnt를 감소시키며, 필요하면 정리(cleanup)를 트리거해요. 복잡한 자기참조 계층에 있는 SV들은 한 번으로 안 풀릴 수 있어서 여러 번 호출해야 할 수도 있어요.

SSize_t       sv_clean_all()
SSize_t  Perl_sv_clean_all(pTHX)

Memory Management — 메모리 관리

이 섹션에 있는 것들은 전부 공개 매크로의 내부 구현이에요. 즉 익스텐션에서는 이걸 직접 부르지 말고 아래 공개 매크로를 쓰라는 뜻이에요.

내부 함수 대신 쓸 공개 매크로 역할
Perl_calloc Newxz 메모리 할당(0 초기화)
Perl_malloc Newx 메모리 할당
Perl_realloc Renew 메모리 재할당
Perl_mfree Safefree 메모리 해제

예를 들어 원문은 이렇게만 적혀 있어요.

Malloc_t  Perl_malloc(MEM_SIZE nbytes)   /* Newx를 쓰세요 */
Malloc_t  Perl_realloc(Malloc_t where, MEM_SIZE nbytes)  /* Renew를 쓰세요 */
Free_t    Perl_mfree(Malloc_t where)     /* Safefree를 쓰세요 */

Character classification — 문자 분류 매크로

이 섹션은 조금 특별해요. 함수(사실상 매크로)가 문자 타입을 분류해요 — 구두점인지, 알파벳인지 등. 대부분 정규식 문자클래스(perlrecharclass의 POSIX 클래스)와 비슷해요.

각 클래스마다 변형(variant)이 여럿 있어서 이것만 제대로 이해하면 나머지는 금방 읽혀요.

  • 기본형(예: isALPHA()) — 부호 있든 없든 정수 값을 코드 포인트로 보고, 그 문자가 해당 ASCII 클래스에 속하는지 bool로 돌려줘요. 옥텟(1바이트)에 안 들어가는 숫자면 FALSE.
  • _A 변형(예: isALPHA_A()) — 기본형과 동일하지만 ASCII 범위 문자만 TRUE가 될 수 있음을 이름으로 강조.
  • _L1 변형(예: isWORDCHAR_L1()) — Latin-1(또는 EBCDIC 대응) 문자집합을 강제 적용. ASCII는 Latin-1의 부분집합이라 영향 없고, 비-ASCII 코드 포인트는 Latin-1으로 취급. 예: isWORDCHAR_L1(0xDF)는 ASCII/EBCDIC 모두에서 참.
  • _uvchr 변형(예: isWORDCHAR_uvchr()) — 256 미만이면 _L1과 같고, 255 초과면 유니코드 규칙으로 판정. isWORDCHAR_uvchr(0x100)은 0x100이 'LATIN CAPITAL LETTER A WITH MACRON'(단어 문자)이므로 TRUE.
  • _utf8 / _utf8_safe 변형 — UTF-8로 인코딩된 문자열용. s가 가리키는 첫 문자를 분류하고, e는 문자열 끝(첫 문자 이후 어디든)을 가리켜요. _safe 접미사는 s <= e일 때 e - 1을 넘어 읽지 않음을 강조.
  • _LC 변형 — 현재 로케일 기준. UTF-8 로케일이면 유니코드 규칙, 아니면 C 라이브러리 함수(예: isdigit()).
  • _LC_uvchr / _LC_utf8 / _LC_utf8_safe — 그 조합류.

내부 구현 함수도 몇 개 있어요.

CC_mask_ — classnum을 비트 패턴으로 바꿔 PL_charclass[]와 함께 쓰게 해요. classnum은 handy.h에 정의된 클래스 중 하나예요.

U32  CC_mask_(U8 c, U8 classnum)

Perl_isCC_by_bit — Latin1 범위의 문자 c가 CC_mask_로 만든 bit_pattern의 클래스에 속하는지 bool로 돌려줘요.

bool  Perl_isCC_by_bit(U8 c, U32 bit_pattern)

MRO — 메서드 해석 순서

클래스의 메서드 해석 순서 관련 함수들이에요. 자세한 건 perlmroapi도 함께 봐요.

mro_get_linear_isa_dfs — 주어진 stash의 @ISA를 깊이 우선 탐색(DFS) 으로 선형화한 결과를 돌려줘요. 반환값은 클래스 이름 문자열 SV로 이뤄진 **읽기전용 AV***이에요. level은 0을 주면 돼요(내부 재귀용). 반환값을 반영구적으로 저장할 거면 SvREFCNT_inc()로 참조 카운트를 올려야 해요(다음 캐시 무효화 때 삭제될 수 있으니까요).

AV *  mro_get_linear_isa_dfs(HV *stash, U32 level)

mro_isa_changed_in — 주어진 패키지의 @ISA가 바뀌었을 때 필요한 조치(주로 캐시 무효화)를 해요. setisa 매직이 호출하므로 직접 부를 일은 거의 없어요.

void  Perl_mro_isa_changed_in(pTHX_ HV *stash)

Compiler directives — 컴파일러 지시어

PREVENT_LVALUE — 입력 x를 그대로 돌려주되, lvalue 컨텍스트에서 호출하면 컴파일 에러를 강제로 내는 매크로예요. 주로 x의 값을 바꿀 수도 있는 매크로 안에 넣어서, 값 변경을 막을 때 써요. getter와 setter가 있고 setter에 에러 체크가 있을 때 getter에서 이걸로 x를 감싸면, x를 바꾸려면 반드시 setter를 쓰도록 강제할 수 있어요.

bool  PREVENT_LVALUE(x)

Compile-time scope hooks — 컴파일 타임 스코프 훅

블록 훅(BHK) 구조를 다루는 내부 매크로들이에요. 대부분 실험적(experimental) 이라 언제 바뀌거나 사라질 수 있어요.

  • BhkENTRY — BHK 구조에서 항목 하나를 돌려줘요. 해당 플래그가 안 세워져 있으면 NULL. 반환 타입은 요청 항목에 따라 달라요.
  • BhkFLAGS — BHK의 플래그를 돌려줘요.
  • CALL_BLOCK_HOOKS — 해당 타입의 등록된 블록 훅을 전부 호출해요.
void *  BhkENTRY(BHK *hk, token which)
U32     BhkFLAGS(BHK *hk)
void    CALL_BLOCK_HOOKS(token which, arg)

XS — XS 컴파일 관련

xsubpp가 XS 코드를 C로 컴파일해요(perlutil의 xsubpp 참고).

api_version_assert — PERL_API_VERSION_CHECK 매크로가 써서, 객체를 빌드한 perl과 libperl을 빌드한 perl의 버전이 맞는지 비교해요. 버전이 안 맞으면 무작위 크래시나 이상 동작 대신 더 진단하기 쉬운 에러를 만들 수 있어요.

void  Perl_api_version_assert(size_t interp_size, void *v_my_perl, const char *api_version)

my_cxt_init — perlxs의 MY_CXT_INIT 매크로를 구현한 함수예요. 모듈이 처음 로드될 때 전역 PL_my_cxt_index를 증가시키고 그 값을 모듈의 정적 my_cxt_index에 할당해요. 그리고 각 인터프리터에 대해 PL_my_cxt_list 배열을 늘려 정적 데이터를 걸 수 있는 void* 슬롯을 확보해요.

void *  Perl_my_cxt_init(pTHX_ int *indexp, size_t size)

Undocumented elements — 미문서화 요소

아직 문서화되지 않은 요소들의 목록이에요. 이 중 하나를 쓰게 된다면, 문서를 만들어 기여하는 걸 고려하라고 원문이 권해요. 실험적·폐기 예정인 미문서화 요소는 목록 끝에 따로 구분돼 있어요. (예: abort_execution, add_above_Latin1_folds …)

이 문서를 어떻게 읽어야 하나요 (원문 가는 길)

이 가이드는 골격과 대표 예시니까, 전체 목록은 반드시 원문에서 확인하세요.

  • 원문(온라인): https://perldoc.perl.org/perlintern
  • 원문(텍스트/소스): 같은 페이지의 perlintern.txt(source) 또는 CPAN(https://metacpan.org/pod/perlintern)
  • 형제 문서: 공개 API 쪽은 perlapi(https://perldoc.perl.org/perlapi)를 봐요. 같은 섹션 구조를 공유하니 둘을 나란히 두고 읽으면 어떤 함수가 내부용이고 어떤 게 공개용인지 한눈에 대조돼요.
  • 더 깊은 배경: 인터프리터 내부 구조 자체(SV/AV/HV 등)는 perlguts가, XS 작성법은 perlxs/perlxstut가 다뤄요.

읽는 요령

  1. 이 문서의 함수는 전부 내부 전용이에요. 익스텐션에 쓰면 안 된다는 건 거의 모든 항목의 공통 전제예요.
  2. 항목마다 C 시그니처가 진짜 핵심이에요. 두 줄이 나오면 Perl_xxx(pTHX_ ...)가 실제 구현이고 위쪽이 매크로형 공용 시그니처예요.
  3. 여러 함수가 "Implements xxx in perlapi which you should use instead"(perlapi의 xxx 구현체 — 그 매크로를 쓰세요)라고 적혀 있어요. 그런 항목은 그 공개 매크로를 대신 쓸 것을 안내하는 거예요.
  4. 섹션마다 "There are currently no internal API items in …"(현재 항목 없음)인 곳이 있어요. 이는 버전에 따라 달라질 수 있어요.

마무리

perlintern은 Perl 인터프리터 내부 전용 C 함수들의 자동생성 참조예요. 확장(익스텐션)을 만들 때는 perlapi의 공개 함수를 쓰고, 인터프리터 코어를 만지는 개발자가 진짜 시그니처와 동작을 확인할 때 이 문서(perlintern)를 뒤져보면 돼요.

이 글은 거대한 원문 대신 구조화된 안내·색인 역할을 하도록 만든 거고, 각 함수의 완전한 최신 설명은 위 원문 링크에서 직접 확인해 주세요.