perlapi - Perl 공개 API 레퍼런스

perlapi는 Perl 공개 API(Public API)의 자동 생성 문서예요. XS(Perl 확장) 작성자가 쓸 수 있는 함수, 매크로, 플래그, 변수의 목록이에요.

출처: perldoc - perlapi 관련 문서: perlintern(내부 API), config.h, perlguts

이 문서가 뭔지 (DESCRIPTION)

이 파일은 embed.pl이 생성한 Perl 공개 API 문서 대부분을 담고 있어요. 구체적으로 확장 작성자가 사용할 수 있는 함수·매크로·플래그·변수의 목록이에요. perlintern과 config.h 외에도, 일부 항목은 실제로 다른 pod에서 문서화되어 여기서는 참조로만 다뤄져요.

끝에 Undocumented elements 섹션은 아직 문서화되지 않은 함수 목록이에요. 패치를 환영해요! 이들의 인터페이스는 예고 없이 바뀔 수 있어요.

특정 요소가 어떤 릴리스에서 시작됐는지 알고 싶다면:

perl dist/ppport.h --api-info=element

패턴으로도 쓸 수 있어요:

perl dist/ppport.h --api-info=/./   # 가능한 모든 공개 API 요소 표시 (perlintern 항목 제외)

일부 요소는 Devel::PPPort에 백포트되어 원래보다 더 이른 버전에서도 쓸 수 있어요. 표시에는 해당 요소를 쓸 수 있는 가장 이른 버전 정보와 몇 가지 힌트·주의사항도 포함돼요.

통합 문서화

여기에 문서화된 함수 중 일부는 통합되어 있어서, 기본적으로 같은 일을 하지만 약간 다른 단일 항목이 여러 함수를 대신할 수 있어요. 예를 들어 어떤 형태는 magic을 처리하고 어떤 형태는 처리하지 않을 수 있어요. 각 변형의 이름은 단일 항목 맨 위에 나열돼요.

이름 접두사

모든 API 함수 이름은 Perl_ 접두사로 시작해요. 이는 여러분의 코드와의 이름 충돌을 막기 위함이에요. 하지만 코드 컴파일 시 -Accflags=-DPERL_NO_SHORT_NAMES를 지정하지 않았다면(참고: perlembed의 "Hiding Perl_"), 이 접두사가 없는 동의어 매크로도 쓸 수 있어요. 이 매크로는 스레드 컨텍스트 파라미터를 함수에 전달해야 하는지도 숨겨줘요. 일반적으로 짧은 형태가 쓰고 읽기 더 쉬워서 실제로는 그 컴파일 플래그를 잘 안 써요. 모든 함수에 짧은 형태가 있는 건 아니며, 둘 다 있을 때는 둘 다 여기에 나열돼요.

여기나 다른 언급된 pod에 나열되지 않은 것은 공개 API가 아니므로 확장 작성자가 전혀 사용해서는 안 돼요. 이런 이유로 확장을 작성할 때 proto.h에 나열된 함수를 무작정 사용하는 것은 피해야 해요.

문자열과 NUL

Perl에서는 C와 달리 문자 문자열이 일반적으로 내장 NUL 문자를 포함할 수 있어요. 문서에서 Perl 문자열을 C 문자열과 구별하기 위해 가끔 "버퍼(buffer)"라고 부르기도 하고, 둘 다 그냥 "문자열"이라고 부르기도 해요.

전역 변수

모든 Perl API 전역 변수는 PL_ 접두사로 참조해야 해요. 다시 말하지만 여기에 나열되지 않은 변수는 확장 작성자가 쓸 수 없고, 예고 없이 바뀌거나 제거될 수 있어요. 매크로도 마찬가지예요. 일부 매크로는 오래된 꾸미지 않은 이름과의 호환성을 위해 제공되지만, 이 지원은 미래 릴리스에서 꺼질 수 있어요.

ASCII와 인코딩

Perl은 원래 US-ASCII(서수 0~~127)만 처리하도록 작성됐어요. 문서와 주석은 때로 ASCII라는 용어를 쓰는데, 실제로는 0~~255 전체 범위를 뜻할 수 있어요.

256 미만의 비ASCII 문자는 상황에 따라 다양한 의미를 가져요 (가장 주목할 만한 것은 perllocale). 보통은 전체 범위를 ISO-8859-1로 지칭할 수 있어요. 종종 "Latin-1"(또는 "Latin1")이라는 용어가 ISO-8859-1과 동등하게 쓰여요. 어떤 사람들은 "Latin1"을 128~~255 또는 160~~255 범위의 문자만 가리킨다고 보기도 해요. 이 문서에서는 "Latin1"과 "Latin-1"을 256개 전체 문자를 가리키는 데 사용해요.

Perl은 ASCII나 EBCDIC 어느 쪽에서도 컴파일·실행될 수 있어요 (perlebcdic 참고). 대부분의 문서(코드 주석조차도)는 EBCDIC 가능성을 무시해요. 거의 모든 용도에서 차이는 투명해요. 예를 들어 EBCDIC에서는 UTF-8 대신 UTF-EBCDIC으로 Unicode 문자열을 인코딩하므로, 문서가 utf8(함수 이름을 포함한 변형)을 가리킬 때 그것은 (본질적으로 투명하게) UTF-EBCDIC을 뜻해요. 하지만 문자의 서수는 ASCII, EBCDIC, UTF 인코딩 사이에서 서로 다르고, UTF-EBCDIC으로 인코딩된 문자열은 UTF-8과 다른 바이트 수를 차지할 수 있어요.

문서 구성

이 문서의 구성은 잠정적이며 바뀔 수 있어요. 제안과 패치는 [email protected]로 환영해요.

API 요소는 기능별로 섹션으로 묶여요. 섹션 안에서 요소는 대소문자를 무시한 알파벳순으로 정렬되고, 선행하지 않는 밑줄이 먼저, 선행 밑줄과 숫자가 마지막에 옵니다.

섹션 목차

API는 다음 67개 섹션으로 나뉘어요:

AV Handling · Callback Functions · Casting · Character case changing · Character classification · Compiler and Preprocessor information · Compiler directives · Compile-time scope hooks · Concurrency · COPs and Hint Hashes · Custom Operators · CV Handling · Debugging · Declaration and Initialization of Globals · Display functions · Embedding, Threads, and Interpreter Cloning · Errno · Exception Handling (simple) Macros · Filesystem configuration values · Floating point · General Configuration · Global Variables · GV Handling and Stashes · Hook manipulation · HV Handling · Input/Output · Integer · I/O Formats · Lexer interface · Locales · Magic · Memory Management · MRO · Multicall Functions · Numeric Functions · Optrees · Pack and Unpack · Pad Data Structures · Password and Group access · Paths to system commands · Prototype information · Reference-counted stack manipulation · REGEXP Functions · Reports and Formats · Signals · Site configuration · Sockets configuration values · Source Filters · Stack Manipulation Macros · String Handling · SV Flags · SV Handling · Tainting · Time · Typedef names · Unicode Support · Utility Functions · Versioning · Warning and Dieing · XS · Undocumented elements · AUTHORS · SEE ALSO

주요 섹션 소개와 대표 항목

이 문서는 방대한(수백 개 항목) 자동 생성 참조이므로, 여기서는 각 기능군의 성격과 대표적인 시그니처를 정리해요. 전체 목록은 원문 perldoc.perl.org/perlapi를 참고해요.

AV Handling (배열 처리)

Perl 배열(AV)을 조작하는 함수·매크로예요.

AV*   newAV();
AV*   newAV_mortal();
void  av_clear(AV *av);
SSize_t av_top_index(const AV *av);   // av_tindex, av_len
SV**  av_fetch(const AV *av, SSize_t key, I32 lval);
SV**  av_store(AV *av, SSize_t key, SV *val);
bool  av_exists(const AV *av, SSize_t key);
SV*   av_delete(AV *av, SSize_t key, I32 flags);
void  av_push(AV *av, SV *val);
SV*   av_pop(AV *av);
void  av_unshift(AV *av, SSize_t num);
SV*   av_shift(AV *av);
AV*   get_av(const char *name, I32 flags);   // @이름 가져오기

배열 요소 접근 매크로: AvARRAY, AvALLOC, AvFILL, av_len, av_count, 참조 카운트 증가 매크로 AvREFCNT_inc 등.

Callback Functions (콜백 함수)

C에서 Perl 서브루틴을 호출하는 call_* 함수들과 그 파라미터·관련 변수예요. perlcall 문서와 밀접.

I32 call_sv(SV* sv, I32 flags);
I32 call_pv(char *subname, I32 flags);
I32 call_method(char *methname, I32 flags);
I32 call_argv(char *subname, I32 flags, char **argv);
void eval_pv(const char* p, I32 croak_on_error);
I32 eval_sv(SV* sv, I32 flags);

플래그: G_VOID, G_SCALAR, G_LIST, G_DISCARD, G_NOARGS, G_EVAL, G_KEEPERR. 컨텍스트 결정 매크로: GIMME_V(구식 GIMME). 오류 변수: PL_errgv($@에 해당하는 GV). 임시값 범위: ENTER, LEAVE, SAVETMPS, FREETMPS. 기타 저장/복원 매크로: SAVEINT, SAVEIV, SAVEBOOL, SAVEPPTR, SAVESTRLEN, SAVEFREESV, SAVEDESTRUCTOR 등.

Casting (형 변환)

포인터와 정수 사이 변환 등 안전한 캐스팅 매크로예요.

#define INT2PTR(any, i)     // 정수를 포인터로
#define PTR2IV(p)  PTR2nat(p)   // 포인터를 IV로
#define PTR2UV(p)  (UV)PTR2nat(p)
#define PTR2NV(p)  ...
#define cBOOL(cbool)         // 값을 boolean으로

Character case changing (대소문자 변환)

toUPPER, toLOWER, toTITLE, toFOLD 계열. 버전별로 _A(ASCII), _L1, _LC(로케일), _utf8, _utf8_safe, _uvchr 변형이 있어요. 또한 컨트롤 문자 변환 매크로 toCTRL/fromCTRL.

Character classification (문자 분류)

isALPHA, isDIGIT, isSPACE, isUPPER, isLOWER, isALNUM(영숫자), isALPHANUMERIC, isASCII, isBLANK, isCNTRL, isGRAPH, isIDCONT, isIDFIRST, isOCTAL, isPRINT, isPSXSPC, isPUNCT, isWORDCHAR, isXDIGIT 등. 각각 _A, _L1, _LC, _LC_utf8_safe, _LC_uvchr, _utf8, _utf8_safe, _uvchr 변형이 있어요.

Compiler and Preprocessor information / Compiler directives

컴파일러 기능 감지 매크로(HAS_BUILTIN_ADD_OVERFLOW, HAS_STATIC_INLINE, HAS_ATTRIBUTE_*, HAS_C99_VARIADIC_MACROS 등)와 전처리기 지시문 관련. PERL_STATIC_INLINE, PERL_THREAD_LOCAL, MEM_ALIGNBYTES 등.

Compile-time scope hooks / Concurrency / COPs and Hint Hooks

컴파일 타임 스코프 훅, 동시성 기본 요소(잠금/원자 연산), COP(control op)와 힌트 해시 관련.

Custom Operators / CV Handling / Debugging

사용자 정의 연산자, CV(name=코드값/서브루틴) 처리, 디버깅 함수들.

Display functions

sv_dump, Perl_sv_dump, dump_sv, dump_mm 등 디버그 출력 함수.

Embedding, Threads, and Interpreter Cloning

perl_alloc, perl_construct, perl_parse, perl_run, perl_destruct, perl_free 등 인터프리터 생명주기와 스레드·복제(cloning) 관련.

PerlInterpreter* perl_alloc(void);
void  perl_construct(PerlInterpreter* interp);
int   perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env);
int   perl_run(PerlInterpreter* interp);
void  perl_destruct(PerlInterpreter* interp);
void  perl_free(PerlInterpreter* interp);

Errno / Exception Handling (simple) Macros

errno 관련 상수, 예외 처리 단순 매크로(dXCPT, XCPT_TRY, XCPT_CATCH, XCPT_RETHROW 등).

Floating point / General Configuration / Filesystem configuration

부동소수점 유틸리티, 일반 구성 값(PERL_REVISION, PERL_VERSION, PERL_SUBVERSION, PERL_USE_SAFE_PUTENV 등), 파일시스템 구성 값(PERL_ACCESS_R_OK 등).

Global Variables / GV Handling and Stashes

Perl 전역 변수(PL_argv0, PL_curcop, PL_curstash, PL_tainting, PL_ppaddr 등)와 GV(glob) 및 stash(심볼 테이블) 처리 함수.

Hook manipulation

훅 조작: wrap_op_checker, cv_set_call_checker 등.

HV Handling (해시 처리)

Perl 해시(HV) 함수예요.

HV*   newHV();
SV**  hv_fetch(HV *hv, const char* key, I32 klen, I32 lval);
SV**  hv_store(HV *hv, const char* key, I32 klen, SV* val, U32 hash);
bool  hv_exists(HV *hv, const char* key, I32 klen);
SV*   hv_delete(HV *hv, const char* key, I32 klen, I32 flags);
HV*   get_hv(const char *name, I32 flags);   // %이름 가져오기

Input/Output / Integer / I/O Formats

I/O 함수, 정수 처리(SvIV, SvUV 등), form/sv_catpvf 계열 포맷 함수.

Lexer interface / Locales / Magic

렉서 인터페이스(lex_start, lex_next_chunk, lex_peek, lex_read 등), 로케일 관련, magic 처리(sv_magic, sv_unmagic, mg_find 등).

Memory Management

Newx, Renew, Safefree, safemalloc, safecalloc, saferealloc, safefree, Move, Copy, Zero, struct_copy 등 메모리 매크로·함수.

MRO / Multicall Functions / Numeric Functions

메서드 해석 순서(MRO) 함수, 멀티콜(dMULTICALL, MULTICALL, MULTICALL_END 등), 수치 함수(grok_number, scan_num, isnan, Perl_signbit 등).

Optrees / Pack and Unpack / Pad Data Structures

옵트리(OP 트리) 구성 함수(newSVOP, newBINOP, newUNOP, newLISTOP, op_free, op_convert_list, op_linklist 등), pack/unpack 함수(packlist, unpack_str 등), 패드(Pad) 데이터 구조.

Password and Group access / Paths to system commands

getpwnam 등 패스워드·그룹 접근, 시스템 명령 경로 변환 매크로(BIN_EXE_EXT 등).

Prototype information / Reference-counted stack manipulation

프로토타입 함수(sv_2pv_flags의 프로토타입 처리, gv_fetchmethod, cv_set_call_checker 등), 참조 카운트 스택 조작 매크로(dRCPUSH, RCPUSHx, RCPOPx, RCPOP_NN 등).

REGEXP Functions / Reports and Formats / Signals

정규식 엔진 인터페이스(pregcomp, pregexec, pregfree, re_compile, Perl_re_intuit_start 등), format/보고 함수, 시그널 처리.

Site configuration / Sockets configuration values / Source Filters

사이트 구성 관련, 소켓 구성 값, 소스 필터(filter_add, filter_del, filter_read 등).

Stack Manipulation Macros

스택 조작 매크로: dSP, SP, PUSHMARK, PUTBACK, SPAGAIN, dMARK, dORIGMARK, MARK, PUSHs, PUSHu, PUSHi, PUSHn, PUSHp, mPUSHs, mPUSHp, POPs, POPp, POPi, POPn, POPu, TOPs, TOPp, TOPn, EXTEND, XPUSHs, XPUSHi, XPUSHp, XPUSHu, XPUSHn, XPUSHmortal, mXPUSHp, mXPUSHi, mXPUSHn, mXPUSHu, XPUSHs_force 등.

String Handling

문자열 처리: sv_catpvn, sv_catsv, sv_catpv, sv_setpvn, sv_setpv, sv_setiv, sv_setuv, SvPV, SvPVX, SvLEN, SvCUR, SvCUR_set, SvPVutf8, sv_len 등.

SV Flags / SV Handling

SV 플래그 매크로(SvROK, SvOK, SvIV, SvNV, SvPV, SvTRUE, SvIVX, SvNVX, SvPVX, SvREFCNT, SvREFCNT_inc, SvREFCNT_dec, SvTYPE, SvOOK, SvUTF8, SvPOK, SvIOK, SvNOK 등)와 SV 생성·조작 함수(newSV, newSViv, newSVuv, newSVnv, newSVpv, newSVpvn, newSVsv, sv_newmortal, sv_2mortal, sv_setsv, sv_catsv, sv_catpvn, sv_len, sv_utf8_upgrade, sv_isbool 등).

Tainting / Time / Typedef names

테인팅 함수(taint_proper, tainted, TAINT, TAINT_NOT, sv_tainted, sv_taint 등), 시간 함수(my_strftime 계열, sv_strftime_*, Perl_my_localtime, Perl_my_gmtime, Perl_my_mktime 등), typedef 이름(I32, IV, UV, NV, AV, HV, CV, GV, SV, STRLEN, pTHX 등).

Unicode Support

Unicode 지원: uvchr_to_utf8, utf8_to_uvchr, uvuni_to_utf8_flags, utf8_to_uvuni(구식), bytes_to_utf8, bytes_from_utf8, utf8n_to_uvchr, sv_utf8_upgrade, sv_utf8_upgrade_nomg, foldEQ_utf8, is_utf8_string, UTF8_SAFE_SKIP, utf8_distance 등.

U8*   uvchr_to_utf8(U8 *d, UV uv);
UV    utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen);

Utility Functions

여러 유틸리티: grok_bin, grok_hex, grok_oct, grok_number, grok_numeric_radix, scan_version, str_to_version, savepv, savesharedpv, savepvn, new_version, del_sv 등.

Versioning / Warning and Dieing / XS

버전 함수(new_version, upg_version, vcmp, vnormal, vnumify, vstringify, prescan_version, scan_version 등), 경고·dieing 함수(warn, croak, die, ck_warner, Perl_warner, Perl_croak, Perl_die, sv_2pv 등), XS 매크로(XS, dXSARGS, dXSI32, dAX, dITEMS, items, ax, XSRETURN_EMPTY, XSRETURN, XSRETURN_IV, XSRETURN_NV, XSRETURN_PV, XSRETURN_UNDEF, XSRETURN_YES, XSRETURN_NO, RETVAL, PPCODE, CODE, CLEANUP, BOOT, INIT, POSTCALL, INTERFACE 등).

Undocumented elements / AUTHORS / SEE ALSO

아직 문서화되지 않은 함수 목록, 저자, 관련 문서.

사용 유의사항

확장 작성자는 여기에 나열된 함수만 쓰고, proto.h의 함수를 무작정 쓰지 마세요.
전역 변수는 반드시 PL_ 접두사로 참조하세요.
모든 API 함수 이름은 Perl_로 시작하며, 대부분 짧은 이름 동의어가 제공돼요.
이 문서는 자동 생성이라 구성이 잠정적이에요. 특정 요소의 도입 릴리스는 perl dist/ppport.h --api-info=element로 확인 가능해요.