C API — 함수와 타입

C API — 함수와 타입 (The Application Program Interface — Functions and Types)

이 절에서는 루아 C API의 핵심 타입과 함수 그룹을 설명해요. 실제 각 함수의 정확한 시그니처와 동작은 루아 5.4 매뉴얼 4.6 절에 있는 것은 물론, 헤더 파일 lua.h, lauxlib.h에 정의되어 있어요.

주요 타입

  • lua_State — 루아 실행 상태(컨텍스트). 모든 C API 함수가 첫 인자로 받는 타입이에요. 내부에 스택과 전역 정보를 담아요.
  • lua_CFunction — C 함수 타입. int (*)(lua_State *L). 스택에서 인자를 받고, 반환 개수를 돌려줘요.
  • lua_KFunction — 연속(continuation) 함수 타입. 양보/재개를 지원하는 C 함수의 연속 지점이에요. int (*)(lua_State *L, int status, lua_KContext ctx).
  • lua_KContext — lua_KFunction에 전달되는 컨텍스트 정수 타입.
  • lua_Integer — 루아 정수 타입 (보통 long long 또는 ptrdiff_t).
  • lua_Number — 루아 실수 타입 (보통 double).
  • lua_Unsigned — 부호 없는 루아 정수 타입.
  • lua_Alloc — 메모리 할당자 함수 타입: void *(*)(void *ud, void *ptr, size_t osize, size_t nsize).
  • lua_Reader — 청크를 조각별로 읽는 함수 타입.
  • lua_Writer — 바이너리 청크를 쓰는 함수 타입.
  • lua_WarnFunction — 경고를 받는 함수 타입.
  • lua_Debug — 디버그 정보를 담는 구조체.
  • lua_Hook — 디버그 후크 함수 타입.

상수들

  • LUA_VERSION / LUA_VERSION_NUM / LUA_RELEASE — 버전 정보.
  • LUA_VERSION_MAJOR / LUA_VERSION_MINOR / LUA_VERSION_RELEASE.
  • LUA_OK, LUA_YIELD, LUA_ERRRUN, LUA_ERRSYNTAX, LUA_ERRMEM, LUA_ERRERR, LUA_ERRFILE — 상태 코드.
  • LUA_REGISTRYINDEX — 레지스트리 가상 인덱스.
  • LUA_TNIL, LUA_TBOOLEAN, LUA_TLIGHTUSERDATA, LUA_TNUMBER, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA, LUA_TTHREAD — 타입 상수.
  • LUA_MULTRET — 다중 반환을 나타내는 특수값.

스택 조작 함수

  • lua_absindex(L, idx) — 상대 인덱스를 절대 인덱스로 변환.
  • lua_gettop(L) — 스택 요소 수.
  • lua_settop(L, idx) — 스택 크기 설정.
  • lua_pushvalue(L, idx) — 값 복사해서 밀어 올림.
  • lua_remove(L, idx), lua_insert(L, idx), lua_replace(L, idx), lua_rotate(L, idx, n) — 이동/교체.
  • lua_copy(L, fromidx, toidx) — 값 복사.
  • lua_checkstack(L, n) — 스택 확장 시도.
  • lua_xmove(from, to, n) — 스택 간 값 이동.

접근 함수 (Access)

  • lua_isnumber, lua_isstring, lua_iscfunction, lua_isuserdata, lua_isinteger, lua_isboolean, lua_isfunction, lua_istable, lua_isthread, lua_isnil, lua_isnone, lua_isnoneornil, lua_islightuserdata, lua_isyieldable — 타입 검사.
  • lua_typename(L, tp), lua_type(L, idx) — 타입 이름/번호.
  • lua_toboolean, lua_tocfunction, lua_tointeger, lua_tointegerx, lua_tonumber, lua_tonumberx, lua_tolstring, lua_tostring, lua_tothread, lua_topointer, lua_touserdata — 값 읽기/변환.
  • lua_arith(L, op), lua_compare(L, idx1, idx2, op), lua_concat(L, n), lua_len(L, idx) — 산술/비교/연결/길이 연산.

push 계열 함수

  • lua_pushnil, lua_pushboolean, lua_pushnumber, lua_pushinteger, lua_pushstring, lua_pushlstring, lua_pushliteral(마크로), lua_pushfstring, lua_pushvfstring, lua_pushcclosure, lua_pushcfunction, lua_pushlightuserdata, lua_pushglobaltable, lua_pushthread, lua_pushvalue — 값을 스택에 밀어 올려요.

테이블/레지스트리 접근

  • lua_createtable(L, narr, nrec) — 새 테이블 생성.
  • lua_newtable(L) — 빈 테이블.
  • lua_gettable, lua_getfield, lua_geti, lua_getglobal, lua_getmetatable, lua_getuservalue, lua_rawget, lua_rawgeti, lua_rawgetp — 읽기.
  • lua_settable, lua_setfield, lua_seti, lua_setglobal, lua_setmetatable, lua_setuservalue, lua_rawset, lua_rawseti, lua_rawsetp — 쓰기.
  • lua_next(L, idx) — 테이블 순회.
  • lua_rawlen(L, idx) — 원시 길이.

userdata

  • lua_newuserdatauv(L, size, nuvalue) — 새 full userdata 생성 (nvvalue개 사용자 값).
  • lua_newuserdata, lua_newuserdatauv — userdata 생성.
  • lua_touserdata, lua_getuservalue, lua_setuservalue.
  • lua_closeslot(L, idx) — userdata의 __close를 호출(닫기).

함수/호출

  • lua_call(L, nargs, nresults) — 보호되지 않은 호출.
  • lua_callk(L, nargs, nresults, ctx, k) — 연속 지원 호출.
  • lua_pcall(L, nargs, nresults, errfunc) — 보호된 호출.
  • lua_pcallk — 연속 지원 보호 호출.
  • lua_load(L, reader, data, chunkname, mode) — 청크 로드.
  • lua_dump(L, writer, data, strip) — 함수의 바이너리 덤프.
  • lua_yield(L, nresults), lua_yieldk — 양보.
  • lua_resume(L, from, nargs, *nres), lua_resetthread(L) — 코루틴 재개/초기화.
  • lua_status(L) — 상태 코드.
  • lua_isyieldable(L) — 양보 가능 여부.
  • lua_version(L) — 버전.
  • lua_error(L) — 오류 던짐.
  • lua_gc(L, what, ...) — 가비지 컬렉터 제어.
  • lua_stringtonumber(L, s) — 문자열→숫자.
  • lua_toclose(L, idx) — 값을 to-be-closed로 표시 (5.4).
  • lua_closethread(L, co) — 스레드 닫기.
  • lua_numbertointeger — 실수→정수 변환 (매크로/함수).

상태/메모리

  • lua_newstate(allocf, ud) — 상태 생성.
  • lua_close(L) — 상태 파괴.
  • lua_newthread(L) — 새 스레드.
  • lua_getallocf(L), lua_setallocf(L, f, ud) — 할당자 조회/설정.
  • lua_atpanic(L, panicf) — 패닉 함수 설정.
  • lua_getextraspace(L) — 상태의 추가 공간.
  • lua_getfield, lua_geti 등은 레지스트리/전역 접근에도 사용돼요.

경고/정보

  • lua_setwarnf(L, f, ud) — 경고 함수 설정.
  • lua_warning(L, msg, tocont) — 경고 발생.
  • lua_version(L) — 루아 버전.

상태 코드와 오류 처리

C API 함수는 일반적으로 상태 코드나 값을 반환해요. lua_pcall은 LUA_OK, 오류 코드 등을 반환하고, 루아 값 함수는 스택을 통해 결과를 전달해요. C 함수는 luaL_error나 lua_error로 오류를 즉시 날 수 있어요.

예시 — 스택과 호출

#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

int main(void) {
  lua_State *L = luaL_newstate();
  luaL_openlibs(L);

  lua_pushinteger(L, 10);
  lua_pushinteger(L, 20);
  lua_setglobal(L, "b");       // b = 20
  lua_setglobal(L, "a");       // a = 10

  luaL_loadstring(L, "return a + b");
  lua_pcall(L, 0, 1, 0);
  long long sum = lua_tointeger(L, -1);
  printf("a + b = %lld\n", sum);

  lua_close(L);
  return 0;
}

타입 상세

  • **lua_Integer**는 보통 64비트 정수이고, **lua_Number**는 64비트 배정밀도 부동소수점이에요. 플랫폼/빌드 설정으로 크기를 조정할 수 있어요 (작은 임베디드용 32비트 등).
  • lua_Unsigned는 부호 없는 lua_Integer이고, lua_Integer와 같은 크기예요.
  • lua_Number와 lua_Integer 사이의 변환은 lua_Number → 정수는 lua_numbertointeger로, 정수 → 실수는 자동 승격으로 이뤄져요.

출처: 응용 프로그램 인터페이스 — 함수와 타입 (The Application Program Interface — Functions and Types)

본문

함수 이름 규칙

  • lua_ 접두사 — 기본 C API (lua.h).
  • luaL_ 접두사 — 보조 라이브러리 (lauxlib.h), 편의 함수.
  • luaopen_* — 라이브러리를 여는 함수 (모듈 정의에 사용).

반환 규칙

대부분의 lua_* 함수는 성공 시 값을 반환하고, lua_State* 관련 함수는 보통 상태를 통해 결과를 전달해요. C 함수에서 오류를 만들려면 luaL_error/lua_error를 사용해요.

더 알아보기