Lua 5.4 中文参考手册

Appearance

4.6 - 函数及类型列表 ​

在这里我们列出了C API中所有的函数和类型，其按照字母顺序排列。每个函数都有一个像右侧这样的标注：[-o, +p, x]

其中第一个属性o表示这个函数会从栈上弹出多少个元素。第二个属性p表示这个函数会把多少个元素压入栈。（任何函数都会在弹出其参数后再把其结果压入栈中。）x|y的形式的属性表示会压入（弹出）x个或者y个元素；其依情况为定；一个问号?表示不知道这个函数会压入（弹出）多少个元素，这取决于它们的参数。（例如依赖了栈内的什么值。）第三个属性x会告知这个函数有没有可能抛出错误：'-'意味着函数不会抛出任何错误；'m'意味着可能会抛出内存溢出的错误；'v'意味着这个函数可能会抛出在下文中解释的错误；'e'意味着这个函数可以运行任意Lua代码，无论是直接执行还是通过调用元函数，因此可能会抛出任何错误。

lua_absindex ​

[-o, +0, -]

int lua_absindex (lua_State *L, int idx);

将一个可接收索引idx转换到一个等效的绝对索引（即不依赖栈大小来表示）。

lua_Alloc ​

typedef void * (*lua_Alloc) (void *ud,
                             void *ptr,
                             size_t osize,
                             size_t nsize);

由Lua状态机使用的内存分配函数类型。这个分配函数必须提供像realloc类似的功能，但不用完全一致。参数ud，为lua_newstate所传递而来的一个不透明指针；参数ptr，为需要被分配/再分配/释放的内存；参数osize，为之前分配的内存块的原本大小；以及参数nsize，为新的内存块所需的大小。

当ptr不为NULL时，osize就是ptr所指向的内存块大小，即之前分配或再分配时所给的大小。

当ptr为NULL时，osize为Lua需要分配的对象种类编码。osize的可能为这些值：LUA_TSTRING、LUA_TTABLE、LUA_TFUNCTION、LUA_TUSERDATA或者LUA_TTHREAD；这些值就是Lua正在创建的新对象的类型。当osize是其他值时，表明Lua在分配其他的东西。

Lua假定所给的分配函数有以下的行为：

当nsize为零时，分配函数必须有类似free的行为且返回NULL。

当nsize非零时，分配函数的行为必须类似realloc。尤其是当其不能满足分配请求时应当返回NULL。

这里是分配函数的一个简单实现。它被luaL_newstate用在辅助库中：

C
static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) {
  (void)ud;  (void)osize;  /* not used */
  if (nsize == 0) {
    free(ptr);
    return NULL;
  }
  else
    return realloc(ptr, nsize);
}

注意ISO标准下的C会确保free(NULL)是没有影响的且realloc(NULL, size)等效于malloc(size)。

lua_arith ​

[-(2|1), +1, e]

void lua_arith (lua_State *L, int op);

对处在栈顶上的两个值（或一个，例如取负操作）做算术或位运算，其中顶部的值是第二个参数，操作会弹出这两个值然后再将结果压入到栈中。函数遵循Lua操作符的相关语法（即有可能会调用元函数）。

参数op的值必须为以下情况之一：

  • LUA_OPADD: 加法
  • LUA_OPSUB: 减法
  • LUA_OPMUL: 乘法
  • LUA_OPDIV: 小数除法
  • LUA_OPIDIV: 整除
  • LUA_OPMOD: 取余
  • LUA_OPPOW: 幂运算（^）
  • LUA_OPUNM: 取负（一元操作 -）
  • LUA_OPBNOT: 按位否（~）
  • LUA_OPBAND: 按位与（&）
  • LUA_OPBOR: 按位或 （|）
  • LUA_OPBXOR: 按位异或 （~）
  • LUA_OPSHL: 左移（<<）
  • LUA_OPSHR: 右移（>>）

lua_atpanic ​

[-0, +0, e]

lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);

返回旧的并设置新的panic函数。

lua_call ​

[-(nargs+1), +nresults, e]

void lua_call (lua_State *L, int nargs, int nresults);

调用函数。和一般的Lua调用异常，lua_call也遵循__call元方法。所以这里“函数”一词意思是任何可被调用的值。

你必须通过这样的协议来完成调用：首先将被调用函数压入栈；接着按序压入调用参数，即第一个参数首先被压入栈。最终你调用了lua_call；nargs为你压入栈的参数数量。当函数返回时，之前所有被压入栈的函数以及参数列表都被弹出了，所有的调用结果都被压入栈中。结果数量取决于nresults，除非nresults为LUA_MULTRET。在这种情况下，来自函数的所有结果都被压入栈；Lua会保证栈空间足以容纳返回值，但不会确保任何额外的栈空间。函数结果也是按序压入栈中的（第一个结果会首先入栈），所以在调用完成后最后一个结果会在栈顶上。

调用及运行过程中发生的任何错误都会向上传播（通过longjmp）。

下面的示例展示了在宿主程序中如何得到这段Lua代码的效果：

lua
a = f("how", t.x, 14)

这是C代码：

C
lua_getglobal(L, "f");      /* 要调用的函数 */
lua_pushliteral(L, "how");  /* 第一个调用参数 */
lua_getglobal(L, "t");      /* 索引这个表 */
lua_getfield(L, -1, "x");   /* 压入't.x'的结果并作为第二个调用参数 */
lua_remove(L, -2);          /* 将't'移出栈 */
lua_pushinteger(L, 14);     /*第三个调用参数 */
lua_call(L, 3, 1);          /* 调用'f'，其中包含三个参数和一个结果值 */
lua_setglobal(L, "a");      /* 设为全局变量'a' */

注意以上代码是平衡的 balanced：即在执行的最后，栈回到了一开始的状态。这被认为是一种良好的编程实现。

lua_callk ​

[-(nargs+1), +nresults, e]

void lua_callk (lua_State *L,
                int nargs,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

此函数的行为完全类似于lua_call，但是允许被调用的函数让出（参见4.5）。

lua_CFunction ​

typedef int (*lua_CFunction) (lua_State *L);

C函数的类型。

为了和Lua合理交流，C函数必须遵循一些约定，其必须定义传递参数和结果的方法：C函数按序从Lua的栈中接收参数（第一个参数首先入栈）。所以当函数开始时，会通过lua_gettop(L)函数来接收一定量的参数。第一个参数（如果有的话）位于索引1且最后一个参数位于lua_gettop(L)。为了给Lua返回值，C函数只需要把它们按序压入栈（第一个结果首先压入），然后在C代码中返回结果的数量。在栈中其他位于结果下边的值都会被Lua直接抛弃。和Lua函数类似，由Lua调用的C函数也可以反返回多个结果。

作为示例，以下函数接收一定量的数字参数并且返回它们的平均值与和。

C
static int foo (lua_State *L) {
  int n = lua_gettop(L)     /* 参数数量 */
  lua_Number sum = 0.0;
  int i;
  for (i = 1; i <= n; i++) {
    if (!lua_isnumber(L, i)) {
      lua_pushliteral(L, "incorrect argument");
      lua_error(L);
    }
    sum += lua_tonumber(L, i);
  }
  lua_pushnumber(L, sum/n); /* 第一个结果 */
  lua_pushnumber(L, sum);   /* 第二个结果 */
  return 2;                 /* 结果个数*/
}

lua_checkstack ​

[-0, +0, -]

int lua_checkstack (lua_State *L, int n);

确保栈中最少有n个额外的空间，即你可以安全地压入n个值。如果不能满足要求它会返回false，要么是因为其所要求的大小大于一个固定的最大值（通常至少允许有几千个元素），要么是因为它不能为额外的空间分配内存了。这个函数永远不会收缩栈；如果栈已经有足够的空间容纳额外元素了，那么它会保持不变。

lua_close ​

[-0, +0, -]

void lua_close (lua_State *L);

在Lua主线程中关闭所有待关闭变量，在给定的Lua状态机上释放所有变量（如果有的话，调用相关的GC元函数），然后释放由这个状态所使用的所有动态内存。

在一些平台上，你也许不需要调用此函数，因为在宿主程序结束的时候会自然释放所有的资源。另一方面，而创建了多个状态机的长时间运行的程序，例如守护精华曾或者Web服务，可能要在不需要的时候晶块关闭状态机。

lua_closeslot ​

[-0, +0, e]

void lua_closeslot (lua_State *L, int index);

关闭所给索引处的待关闭插槽并设置其值为nil。索引必须是之前被标记为要关闭（参见lua_toclose）的最后一个，但其仍然存活（即尚未关闭）。

通过此函数调用时的__close元函数不可以让出。

（此函数于版本5.4.3引入。）

lua_closethread ​

[-0, +?, -]

int lua_closethread (lua_State *L, lua_State *from);

重置一个Lua线程，清理器调用栈并关闭所有的待关闭变量。最后返回一个状态码：LUA_OK表示在这个Lua线程中没有错误（要么是因为线程已经停止了或者在关闭函数中本身发生的错误），或者一个其他的错误状态码。在发生错误的情况下，会将错误对象保留在栈顶。

参数from表示正在重置L的协程。如果没有这个协程，此参数可以为NULL。

（此函数于版本5.4.6引入。）

lua_compare ​

[-0, +0, e]

int lua_compare (lua_State *L, int index1, int index2, int op);

比较两个Lua值。处于index1的值和index2的值比较后能满足op的话就会返回1，否则返回0；并且遵循Lua操作符的相关语法约定（即可能会调用元表）。任何无效索引也会导致返回0。

op值必须为以下常量：

  • LUA_OPEQ：比较是否相等（==）
  • LUA_OPLT：比较是否小于（<）
  • LUA_OPLE：比较是否小于等于（<=）

lua_concat ​

[-n, +1, e]

void lua_concat (lua_State *L, int n);

连接在栈顶上的n个值，弹出这些值并将结果放到栈顶上。如果n为1，则结果就是在栈中的单一值（即此函数什么都不会干）；如果n为0，则结果为空字符串。连接操作遵循之前提到的一般Lua语法（参见3.4.6）。

lua_copy ​

[-0, +0, -]

void lua_copy (lua_State *L, int fromidx, int toidx);

拷贝fromidx索引处的值到有效索引toidx处的值，并替换掉这个位置上的值。其他位置上的值不受影响。

lua_createtable ​

[-0, +1, m]

void lua_createtable (lua_State *L, int narr, int nrec);

创建一个空表并压入栈中。参数narr指出表将会是个序列且有多少个元素；参数nrec指出此表将会有多少个元素。Lua可能会使用这些指示值来提前分配内存给新表。当你提前知道表中会有多少个元素时，提前分配内存有助于性能提升。否则你可以使用lua_newtable函数。

lua_dump ​

[-0, +0, -]

int lua_dump (lua_State *L,
                        lua_Writer writer,
                        void *data,
                        int strip);

将Lua函数转存为一个二进制块。从栈顶上接收一个函数并产生其二进制块，如果之后加载这个块，那么会产生一个转存的函数相等效的函数。每产出一部分二进制块，lua_dump都会调用writer（参见lua_Writer）并使用所给的data参数指向的缓冲块来写入。

如果strip为true，则表示二进制块可能不会包含所有与函数相关的调试信息，以节省存储空间。

返回值时最后一次调用writer所返回的错误码；0表示无错误。

此接口不会弹出在栈上的Lua函数。

lua_error ​

[-1, +0, v]

int lua_error (lua_State *L);

抛出一个Lua错误，使用栈顶上的值作为错误对象。此函数会发生long jump，因此永不返回（参见luaL_error）。

lua_gc ​

[-0, +0, -]

int lua_gc (lua_State *L, int what, ...);

GC行为控制。

此函数会执行一些任务，任务通过参数what的值来指定。下面列出了各选项以及对应所需的额外函数。

  • LUA_GCCOLLECT：执行一次完整的GC循环。
  • LUA_GCSTOP：停止GC。
  • LUA_GCRESTART：重启GC。
  • LUA_GCCOUNT：返回Lua当前使用的内存量（单位Kbytes）。
  • LUA_GCSTEP(int stepsize):：执行步进GC的一小步，步长为stepsize（Kbytes）。
  • LUA_GCISRUNNING：返回一个布尔值以表明收集器是否在运行中。
  • LUA_GCINC (int pause, int stepmul, stepsize)：根据所给参数将GC变为步进模式（参见2.5.1）。并返回之前使用的模式（LUA_GCGEN 或是 LUA_GCINC）。
  • LUA_GCGEN (int minormul, int majormul)：根据所给参数将GC变为代际模式（参见2.5.1）。并返回之前使用的模式（LUA_GCGEN 或是 LUA_GCINC）。

更多细节请参见collectgarbage。

此函数不应当在终结器中调用。

lua_getallocf ​

[-0, +0, -]

lua_Alloc lua_getallocf (lua_State *L, void **ud);

返回所给状态机使用的内存分配函数。当ud不为NULL时，Lua会将对应状态机所使用的内存分配函数存到*ud中。

lua_getfield ​

[-0, +1, e]

int lua_getfield (lua_State *L, int index, const char *k);

将t[k]的值压入栈中，此处t为给出的索引所处的值。和在Lua代码中一样，此函数可能会触发"index"事件的元函数（参见2.4）。

返回值为压入栈中的值的类型。

lua_getextraspace ​

[-0, +0, -]

void *lua_getextraspace (lua_State *L);

返回指向所给Lua状态机中一块原始内存区域的指针。程序将这块区域用于任何目的，Lua不会将其用在任何事上。

每个Lua线程都有这块区域，其由Lua主线程的区域拷贝而来。

默认情况下，这块内存的大小为void指针的大小，不过你可以使用不同的大小来重新编译Lua(参见 luaconf.h 中的 LUA_EXTRASPACE)。

lua_getglobal ​

[-0, +1, e]

int lua_getglobal (lua_State *L, const char *name);

将名为name的全局变量的值压入栈中。返回值为这个全局变量的类型。

lua_geti ​

[-0, +1, e]

int lua_geti (lua_State *L, int index, lua_Integer i);

将t[i]的值压入栈中，这里的t为给出索引的值。和在Lua代码中一样，此函数可能会触发"index"事件的元函数（参见2.4）。

lua_getmetatable ​

[-0, +(0|1), -]

int lua_getmetatable (lua_State *L, int index);

如果给出索引的值中含有元表，那么此函数会将其元表压入栈中然后返回1。否则，此函数返回且不会向栈中压入任何值。

lua_gettable ​

[-1, +1, e]

int lua_gettable (lua_State *L, int index);

将t[k]的值压入栈中，这里的t为给出索引的值，k为栈顶上的值。

此函数从栈中弹出键，再将结果压入同样的位置。和在Lua中一样，此函数可能会触发"index"事件的元函数（参见2.4）。

lua_gettop ​

[-0, +0, -]

int lua_gettop (lua_State *L);

返回栈顶元素的索引。因为索引是从1开始的，所以这里的结果就是栈中元素的数量；特殊情况下是0，表明栈是空的。

lua_getiuservalue ​

[-0, +1, -]

int lua_getiuservalue (lua_State *L, int index, int n);

将给出索引处的 full userdata 关联的第n个user值压入栈中，并且返回此值的类型。

如果这个 userdata 没有这个值，则压入nil并且返回LUA_TNONE。

lua_insert ​

[-1, +1, -]

void lua_insert (lua_State *L, int index);

将栈顶元素移动到有效的index处，上移其上边的元素到空出来的位置。此函数不可以使用虚拟索引，因为虚拟索引并不真实存在于栈上。

lua_Integer ​

typedef ... lua_Integer;

Lua中的整数类型。

此类型默认为 long long，（通常是一个64位整数），但是其可以改为 long 或者 int (通常是一个32位整数)。（参见 luaconf.h 中的 LUA_INT_TYPE 。）

Lua还定义了常量 LUA_MININTEGER 和 LUA_MAXINTEGER，用于表示此类型的最大值和最小值。

lua_isboolean ​

[-0, +0, -]

int lua_isboolean (lua_State *L, int index);

当给出索引的值为布尔类型时则返回1，否则返回0。

lua_iscfunction ​

[-0, +0, -]

int lua_iscfunction (lua_State *L, int index);

当给出索引的值为C函数类型时则返回1，否则返回0。

lua_isinteger ​

[-0, +0, -]

int lua_isinteger (lua_State *L, int index);

当给出索引的值为整数类型时则返回1，否则返回0。

lua_islightuserdata ​

[-0, +0, -]

int lua_islightuserdata (lua_State *L, int index);

当给出索引的值为 light userdata 时则返回1，否则返回0。

lua_isnil ​

[-0, +0, -]

int lua_isnil (lua_State *L, int index);

当给出索引的值为nil时则返回1，否则返回0。

lua_isnone ​

[-0, +0, -]

int lua_isnone (lua_State *L, int index);

当给出索引的值无效时则返回1，否则返回0。

lua_isnoneornil ​

[-0, +0, -]

int lua_isnoneornil (lua_State *L, int index);

当给出索引的值无效或为nil时则返回1，否则返回0。

lua_isnumber ​

[-0, +0, -]

int lua_isnumber (lua_State *L, int index);

当给出索引的值为数字类型或是可转换为数字的字符串类型时则返回1，否则返回0。

lua_isstring ​

[-0, +0, -]

int lua_isstring (lua_State *L, int index);

当给出索引的值为字符串类型或数字类型（数字必然可以转换为字符串）时则返回1，否则返回0。

lua_istable ​

[-0, +0, -]

int lua_istable (lua_State *L, int index);

当给出索引的值为表类型时则返回1，否则返回0。

lua_isthread ​

[-0, +0, -]

int lua_isthread (lua_State *L, int index);

当给出索引的值为Lua线程（协程）类型时则返回1，否则返回0。

lua_isuserdata ​

[-0, +0, -]

int lua_isuserdata (lua_State *L, int index);

当给出索引的值为 (full/light) user data 类型时则返回1，否则返回0。

lua_isyieldable ​

[-0, +0, -]

int lua_isyieldable (lua_State *L);

当所给的协程（即传入的lua_State类型）可以让出时则返回1，否则返回0。

lua_KContext ​

typedef ... lua_KContext;

延续函数的上下文类型。其必须是一个数字类型。当 intptr_t 可用时，此类型被定义为 intptr_t 类型，所以它也可以存指针。否则，其被定义为 ptrdiff_t 类型。

lua_KFunction ​

typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);

延续函数的类型（参见4.5）。

lua_len ​

[-0, +1, e]

void lua_len (lua_State *L, int index);

返回给出索引的值的长度。其等效于Lua代码中的"#"操作（参见3.4.7），可能会触发"length"事件的元函数（参见2.4）。结果会被压入到栈中。

lua_load ​

[-0, +1, -]

int lua_load (lua_State *L,
              lua_Reader reader,
              void *data,
              const char *chunkname,
              const char *mode);

加载Lua代码块但不运行。如果没有错误发生，lua_load会将编译后的块作为一个Lua函数压入栈中。否则，它将压入错误对象。

lua_load函数通过用户提供的reader函数来读取代码块（参见lua_Reader）。data参数是一个要传递给reader的不透明值。

参数chunkname是所给代码块的名称，会被用在错误消息和调试信息中（参见4.7）。

lua_load会自动检测传入的代码块是文本还是二进制格式然后用合适的方式加载它（参见 luac 程序）。字符串参数mode的工作方式和load函数中的相同，另有不同的是，当mode值为NULL时等效于字符串"bt"。

lua_load内部也使用了栈，所以reader函数在返回是必须使得栈保持不变。

lua_load可能返回 LUA_OK、 LUA_ERRSYNTAX 或是 LUA_ERRMEM （此函数也可能返回与read函数所产生错误相关的值，参见4.4.1）。

如果加载得到的函数有上值，那么第一个上值就会设在全局环境中的值中，全局环境被存在注册表中的 LUA_RIDX_GLOBALS 索引处（参见4.3）。加载主代码块时，这个上值会是变量 _ENV（参见2.2）。其他上值会被初始化为nil。

lua_newstate ​

[-0, +0, -]

lua_State *lua_newstate (lua_Alloc f, void *ud);

创建一个独立的Lua状态机并返回其Lua主协程。如果不能创建状态机（可能是因为内存不足）时返回 NULL 。参数 f 为内存分配函数；Lua在这个状态机中的所有内存分配都将使用这个函数（参见lua_Alloc）。第二个参数 ud 是一个不透明指针，Lua每次调用内存分配时都会将其传入。

lua_newtable ​

[-0, +1, m]

void lua_newtable (lua_State *L);

创建一个表并将其压入栈中。等效于 lua_createtable(L, 0, 0) 。

lua_newthread ​

[-0, +1, m]

lua_State *lua_newthread (lua_State *L);

创建一个Lua线程，并将其压入栈中，然后返回一个代表这个新Lua线程的lua_State指针。所返回的新Lua线程与传递进来的原线程共享同一个全局环境，但是有独立执行栈。

Lua线程和其他Lua对象一样，也受GC的管理。

lua_newuserdatauv ​

[-0, +1, m]

void *lua_newuserdatauv (lua_State *L, size_t size, int nuvalue);

此函数会创建一个新的 full userdata 并将其压入栈中。其引用了 nuvalue 个Lua值，称为 user value，加上引用了一块 size 字节的原始内存。（这些 user value 可以通过lua_setiuservalue和lua_getiuservalue函数来设置或读取。）

此函数返回关联内存块的地址。Lua会确保在 userdata 活跃期间其关联的内存块不会失效（参见2.5）。此外，如果 userdata 被标记为可终结的（参见2.5.3），那么这个地址会被保留到调用终结器为止。

lua_next ​

[-0, +(2|0), v]

int lua_next (lua_State *L, int index);

从栈中弹出一个键，然后从给出索引处的table中取出一对键值压入栈中，这个键值对就在之前弹出的键后边的位置。如果表中没有更多的元素，那么lua_next返回0并且不会压栈。

通常表的遍历会像这样：

C
/* 表在栈中't'索引的位置 */
lua_pushnil(L);  /* 第一个键 */
while (lua_next(L, t) != 0) {
  /* 键在-2索引上，键值在-1索引上 */
  printf("%s - %s\n",
         lua_typename(L, lua_type(L, -2)),
         lua_typename(L, lua_type(L, -1)));
  /* 移走键值引用；留着键给下一轮迭代使用 */
  lua_pop(L, 1);
}

当遍历表时应当避免直接对键调用lua_tolstring，除非你知道键确实是个字符串。lua_tolstring可能会改变给出索引处的值；这样会和下一次调用lua_next混淆在一起。

当给的键既不是nil也不存在于表中时，此函数可能会抛出错误。与在遍历过程中更改表相关的注意事项请参见next函数。

lua_Number ​

typedef ... lua_Number;

Lua中的浮点数类型。

默认为 double 类型，但是你可以改为 float 或 long double 。（参见 luaconf.h 中的 LUA_FLOAT_TYPE 。）

lua_numbertointeger ​

int lua_numbertointeger (lua_Number n, lua_Integer *p);

常见将Lua浮点数转换为Lua整数；浮点数 n 一定有整数值。如果这个整数值在Lua整数的取值范围内，那么会将此浮点数转换为一个整数并赋值给 *p 。这个宏的结果是个布尔值，以表示转换是否成功。（要知道，由于四舍五入，没有这个宏很难正确执行范围测试。）

此宏可能会多次计算其参数。

lua_pcall ​

[-(nargs+1), +(nresults|1), -]

int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);

在保护模式下调用函数（或者可调用的对象）。

nargs 和 nresults 参数的含义与lua_call中一样。如果在调用期间没有发生错误，那么lua_pcall的行为会和lua_call类似。然而，如果发生了任何错误，lua_pcall会捕获它，并将一个值（即错误对象）压入到栈中，然后返回一个错误码。和lua_call类似，lua_pcall通常会把这个函数和它的参数从栈上移除。

如果 msgh 为0，那么返回的错误对象会被原样放在栈中。否则，msgh 为错误处消息理函数在栈中的索引位置（此索引不可以是虚拟索引）。在运行时发生错误的情况下，将会带上错误对象一起调用处理函数，调用结果会通过lua_pcall返回到栈上。

通常此处理函数被用来给错误对象添加更多的错误信息，例如栈的回溯。这些信息不能在lua_pcall返回后再收集，因为那个时候栈已经展开。

lua_pcall函数会返回这些状态码中的一个：LUA_OK、LUA_ERRRUN、LUA_ERRMEM或者LUA_ERRERR。

lua_pcallk ​

[-(nargs+1), +(nresults|1), -]

int lua_pcallk (lua_State *L,
                int nargs,
                int nresults,
                int msgh,
                lua_KContext ctx,
                lua_KFunction k);

此函数的行为类似于lua_pcall，不同在于它允许调用的函数让出（参见4.5）。

lua_pop ​

[-n, +0, e]

void lua_pop (lua_State *L, int n);

从栈上弹出 n 个元素。其实现为一个用宏包装起来的 lua_settop 调用。

lua_pushboolean ​

[-0, +1, -]

void lua_pushboolean (lua_State *L, int b);

将一个布尔值 b 压入栈中。

lua_pushcclosure ​

[-n, +1, m]

void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);

将一个C闭包压入栈中。此函数接收一个指向C函数的指针并将其作为 function 类型的Lua值压入栈中，当这个值被调用的时候会触发相关的C函数。参数 n 表示这个函数将会有多少个上值（参见4.2）。

任何可以被Lua调用的函数都必须正确遵循传参和返回的协议（参见lua_CFunction）。

当一个C函数被创建，它可能会关联一些值，所以被称为上值 upvalues ；这些上值可以在调用期间被函数访问。这种关联关系被称为C闭包（参见4.2）。要创建一个C闭包，首先就必须将上值的初始值压入栈中。（当存在多个上值得时候，第一个上值首先压入，以此类推。）然后调用lua_pushcclosure来创建C函数并压入栈中，其中参数 n 指出了函数有多少个关联的值。lua_pushcclosure会将这些值从栈上弹出。

n 的最大值为255。

当 n 为零时，此函数创建的是一个轻量级C函数 light C function ，其只是一个C函数指针。这种情况下永远不会抛出内存错误。

lua_pushcfunction ​

[-0, +1, -]

void lua_pushcfunction (lua_State *L, lua_CFunction f);

将一个C函数压入栈中。此函数等效于不带上值的lua_pushcclosure调用。

lua_pushfstring ​

[-0, +1, v]

const char *lua_pushfstring (lua_State *L, const char *fmt, ...);

将一个格式化字符串压入到栈中并返回这个字符串的指针（参见4.1.3）。其和ISO标准下的C函数 sprintf 类似，但是有两点不同之处。第一点，你无需为结果分配空间；这个结果是一个Lua字符串所以会由Lua来管理它的内存分配（以及通过GC释放内存）。第二点，其转义符有很多限制。不支持标志、宽度或是精度。转义符只支持'%%'（插入一个百分号字符）、'%s'（插入一个C风格字符串，即以0为结尾，不限制大小）、'%f'（插入一个lua_Number）、'%I'（插入一个lua_Integer）、'%p'（插入一个指针值）、'%d'（插入一个 int ）、'%c'（插入一个由 int 值表示编码值的字符）、以及'%U'（插入一个 long int 作为一个UTF-8的字节序）。

此函数会在内存溢出或者发生了无效转义的时候抛出错误。

lua_pushglobaltable ​

[-0, +1, -]

void lua_pushglobaltable (lua_State *L);

将全局环境压入栈中。

lua_pushinteger ​

[-0, +1, -]

void lua_pushinteger (lua_State *L, lua_Integer n);

压入一个值为 n 的整数到栈中。

lua_pushlightuserdata ​

[-0, +1, -]

void lua_pushlightuserdata (lua_State *L, void *p);

压入一个 light userdata 到栈中。

userdata 在Lua中表示一个C值。一个 light userdata 表示一个 *void 类型的指针。它是个值（和 number 一样）：你不需要专门创建它，它没有独立的元表并且不会被GC清理（因为它没有经历创建的过程）。任何 light userdata 之间，只要它们指向相同的C地址，那么它们就是相等的。

lua_pushliteral ​

[-0, +1, m]

const char *lua_pushliteral (lua_State *L, const char *s);

这个宏等效于lua_pushstring，但只应该在 s 是一个字面量时使用。

lua_pushlstring ​

[-0, +1, m]

const char *lua_pushlstring (lua_State *L, const char *s, size_t len);

将一个指向长度为 len 的字符串的指针 s 压入到栈中。Lua将新建或重用所给字符串的拷贝，所以 s 所指向的内存可以在函数返回后立刻释放或者继续复用。这个字符串可以包含任何二进制数据，包括嵌入的零值。

返回一个指向此字符串的内部拷贝的指针（参见4.1.3）。

lua_pushnil ​

[-0, +1, -]

void lua_pushnil (lua_State *L);

将压入一个nil值到栈中。

lua_pushnumber ​

[-0, +1, -]

void lua_pushnumber (lua_State *L, lua_Number n);

压入一个值为 n 的浮点数到栈中。

lua_pushstring ​

[-0, +1, m]

const char *lua_pushstring (lua_State *L, const char *s);

将一个以零为终止符的字符串指针 s 压入到栈中。Lua将新建或重用所给字符串的拷贝，所以 s 所指向的内存可以在函数返回后立刻释放或者继续复用。

返回一个指向此字符串的内部拷贝的指针（参见4.1.3）。

如果 s 为 NULL ，则会将nil压入栈中并返回 NULL 。

lua_pushthread ​

[-0, +1, -]

int lua_pushthread (lua_State *L);

将 L 所表示的Lua线程压入到栈中。如果这个状态机的Lua线程是主线程则会返回1。

lua_pushvalue ​

[-0, +1, -]

void lua_pushvalue (lua_State *L, int index);

拷贝给出索引处的值，并将其压入栈中。

lua_pushvfstring ​

[-0, +1, v]

const char *lua_pushvfstring (lua_State *L,
                              const char *fmt,
                              va_list argp);

等效于lua_pushfstring，不同在于它最后一个参数类型是 va_list 而不是可变参。

lua_rawequal ​

[-0, +0, -]

int lua_rawequal (lua_State *L, int index1, int index2);

当两个值直接相等时（即用不着调用元函数 __eq 来判断）会返回1。否则返回0。如果两者之间有任何的非法索引也会返回0。

lua_rawget ​

[-1, +1, -]

int lua_rawget (lua_State *L, int index);

和lua_gettable类似，但是执行的是直接访问（即不通过元函数访问）。索引处的值必须是个表。

lua_rawgeti ​

[-0, +1, -]

int lua_rawgeti (lua_State *L, int index, lua_Integer n);

将 t[n] 的值压入栈中，这里的 t 为给出索引处的表。这也是直接访问的，即不使用元值 ___index 。

返回值为这个值的类型。

lua_rawgetp ​

[-0, +1, -]

int lua_rawgetp (lua_State *L, int index, const void *p);

将 t[k] 的值压入栈中，这里的 t 为给出索引处的表，且 k 为表示指针 p 的一个 light userdata 。这也是直接访问的，即不使用元值 ___index 。

返回值为这个值的类型。

lua_rawlen ​

[-0, +0, -]

lua_Unsigned lua_rawlen (lua_State *L, int index);

返回索引处值的“直接长度”：对于字符串，就是其字符串长度；对于表，就是执行取长操作符（'#'）的结果，但是不会调用元函数；对于 userdata，就是 userdata 关联的内存块大小。对于其他的值，此调用都返回0。

lua_rawset ​

[-2, +0, m]

void lua_rawset (lua_State *L, int index);

类似于lua_settable，但执行的是直接赋值（即不调用元函数）。索引处的值必须是一个表。

lua_rawseti ​

[-1, +0, m]

void lua_rawseti (lua_State *L, int index, lua_Integer i);

等效于执行 t[i] = v ，这里的 t 是索引处的表，v 是放在栈顶上的值。

此函数将值从栈上弹出。此处是直接赋值，即不会调用元值 __newindex 。

lua_rawsetp ​

[-1, +0, m]

void lua_rawsetp (lua_State *L, int index, const void *p);

等效于执行 t[p] = v ，这里的 t 是索引处的表，p 是转换后的 light userdata，且 v 是处于栈顶上的值。

此函数将值从栈上弹出。此处是直接赋值，即不会调用元值 __newindex 。

lua_Reader ​

typedef const char * (*lua_Reader) (lua_State *L,
                                    void *data,
                                    size_t *size);

用于lua_load的 reader 函数。每当lua_load需要代码块中的下一小块时，其会调用 reader，并接着传递参数 data 。这个 reader 必须返回指向代码块的新部分的指针，并且将 *size 设为这块内存的大小。这块内存必须直到下一次调用 reader 前都存在。为了表示代码块结束了，reader 必须返回 NULL 并将 *size 设为零。reader函数可以返回任意长度大于0的块。

lua_register ​

[-0, +0, e]

void lua_register (lua_State *L, const char *name, lua_CFunction f);

将全局变量 name 的值设为给出的C函数。这个宏是这样定义的：

C
#define lua_register(L,n,f) \
        (lua_pushcfunction(L, f), lua_setglobal(L, n))

lua_remove ​

[-1, +0, -]

void lua_remove (lua_State *L, int index);

从栈上移除给出的有效索引的元素，空出来的位置由上边的元素依次下移填充。此函数不可以用虚拟索引调用，因为虚拟索引并不实际存在于栈上。

lua_replace ​

[-1, +0, -]

void lua_replace (lua_State *L, int index);

将栈顶的值移动到给出索引的位置（原文为 moves，但其实这个栈顶的元素还在），但是不下移任何元素（于是就替换了索引处的值），然后弹出栈顶的值。

lua_resetthread ​

[-0, +?, -]

int lua_resetthread (lua_State *L);

此函数已废弃；其等效于 from 参数为 NULL 的lua_closethread调用。

lua_resume ​

[-？, +?, -]

int lua_resume (lua_State *L, lua_State *from, int nargs,
                          int *nresults);

开始或重启给定的Lua线程所指的协程 L 。（本质上是一回事）

如需启动一个协程，你必须将主函数和其所有参数都压入到这个Lua线程的空栈中。然后你再调用lua_resume，其参数 nargs 为主函数的参数数量。此调用会在协程执行完成或者被挂起时返回。当它返回时，由lua_yield或主函数返回的值会被放到栈顶上，*nresult 会变更为这些返回值的数量。当协程让出时lua_resume会返回LUA_YIELD，如果协程执行完成并未发生任何错误则返回LUA_OK。在发生错误的情况下，错误对象会被放在协程L的栈顶中（而不是执行这个协程的主体线程）。

如需重启一个协程，你必须把在栈上的 *nresults 个让出返回值移除，将结果值压入栈中以传递给让出的地方，然后再调用lua_resume。

参数 from 表示执行重启的协程 L 的主体，其也是一个协程。如果不存在这样的协程，此参数可以是 NULL。

lua_rotate ​

[-0, +0, -]

void lua_rotate (lua_State *L, int idx, int n);

旋转/回绕给定索引处到栈顶之间的元素。当 n 是正数时，这些元素会向顶部方向旋转 n 个位置；如果是一个负值 -n ，那么会向栈底方向旋转 n 个位置。n 的绝对值不能大于需要旋转的元素数量。不可以使用虚拟索引来调用这个函数，因为虚拟函数实际上并不存在于栈上。

lua_setallocf ​

[-0, +0, -]

void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);

将内存分配函数改为 f 并带上用户数据 ud。

lua_setfield ​

[-1, +0, e]

void lua_setfield (lua_State *L, int index, const char *k);

等效于执行 t[k] = v，这里的 t 为给定索引处的表，v 为栈顶上的值。

此函数会从栈上弹出这个值。和在Lua代码中一样，此函数可能会触发"newindex"事件对应的元函数（参见2.4）。

lua_setglobal ​

[-1, +0, e]

void lua_setglobal (lua_State *L, const char *name);

从栈上弹出一个值并将其赋值到全局变量 name 中。

lua_seti ​

[-1, +0, e]

void lua_seti (lua_State *L, int index, lua_Integer n);

等效于执行 t[n] = v，这里的 t 为给定索引处的表，v 为栈顶上的值。

此函数会从栈上弹出这个值。和在Lua代码中一样，此函数可能会触发"newindex"事件对应的元函数（参见2.4）。

lua_setiuservalue ​

[-1, +0, -]

int lua_setiuservalue (lua_State *L, int index, int n);

从栈上弹出一个值，将这个值设为给出索引处的 full userdata 的第 n 个 user value。当 userdata 中没有这个值时会返回0。

lua_setmetatable ​

[-1, +0, -]

int lua_setmetatable (lua_State *L, int index);

从栈上弹出一个表或者nil，并将其设置为给出索引处的值的新元表。（nil意味着没有元表。）

（因为一些历史原因，此函数返回值类型为 int ，现在返回值已经无任何指示意义，总是会返回1。）

lua_settable ​

[-2, +0, e]

void lua_settable (lua_State *L, int index);

等效于执行 t[k] = v ，这里的 t 为给出索引处的值，v 是栈顶上的值，k 是紧跟在栈顶下边位置上的值。

此函数会从栈上弹出键和键值。和Lua代码中一样，此函数可能会触发 "newindex" 事件对应的元函数。

lua_settop ​

[-?, +?, e]

void lua_settop (lua_State *L, int index);

接受一个任意索引或者0，然后将栈顶增长或下降到这个索引的位置，即扩张或收缩栈的大小。如果新的栈顶位置大于原来的，那么新的元素都使用nil值填充。如果给出索引为0，那么所有栈元素都被移除。

此函数在移除的索引处为待关闭变量时可能会运行任意的代码（因为可能触发 __close 元函数）。

lua_setwarnf ​

[-0, +0, -]

void lua_setwarnf (lua_State *L, lua_WarnFunction f, void *ud);

设置供Lua发出警告时使用的警告函数（参见lua_WarnFunction）。参数 ud 为每次调用此函数时需要传递给警告函数的特定数据。

lua_State ​

typedef struct lua_State lua_State;

该结构体并不透明，它指向一个Lua线程及（通过Lua线程）间接指向Lua解释器的一个完整的状态机。Lua库是完全可重入的，就是因为这个结构体没有使用全局变量。所有关于状态机的信息都可以通过这个结构体访问到。

库中的每个函数都需要将一个指向这个结构体的指针作为第一个参数传入，除了lua_newstate，它是从头创建一个Lua状态机。

lua_status ​

[-0, +0, -]

int lua_status (lua_State *L);

返回给出的Lua线程 L 的状态。

这个状态可以是表示正常的LUA_OK、由lua_resume唤醒的Lua线程在执行时发生错误后的错误码、或是表示Lua线程已经被挂起的LUA_YIELD。

你只能在LUA_OK状态中的线程中调用这个函数。你可以唤醒处在LUA_OK状态（会启动新协程）或LUA_YIELD状态（会唤醒协程）下的线程。

lua_stringtonumber ​

[-0, +1, -]

size_t lua_stringtonumber (lua_State *L, const char *s);

将以零为终止符的字符串 s 转换为一个 number ，并将其压入到栈中，然后返回字符串的完整大小——即长度加一。根据Lua中的词法转换，此转换的结果可能是整数或浮点数（参见3.1）。字符串前边或后边可以有空白字符或符号。如果字符串内容不是一个有效的数字，此函数会返回0且不会做压栈操作。（注意此返回结果可以作为布尔值使用，转换成功即为true。）

lua_toboolean ​

[-0, +0, -]

int lua_toboolean (lua_State *L, int index);

将给定索引处的Lua值转换为一个C布尔值（0或1）。和Lua中所有的真假值测试类似，lua_toboolean对于任何不同于false和nil的Lua值都返回true；否则返回false。（如果你只想接收Lua布尔值，可以使用lua_isboolean来探测类型。）

lua_tocfunction ​

[-0, +0, -]

lua_CFunction lua_tocfunction (lua_State *L, int index);

将给定索引处的Lua值转换为一个C函数，此值必须本就是C函数，否则返回NULL。

lua_toclose ​

[-0, +0, m]

void lua_toclose (lua_State *L, int index);

将在栈中的给定索引标记为待关闭槽位（参见3.3.8）。和Lua中的待关闭变量类似，栈上在该槽中的值将会在其超出作用域后被关闭。在这里的C函数上下文中，超出作用域指的是函数执行返回到Lua中了、或者发生了错误、或者通过lua_settop或lua_pop将该槽位从栈上移除了、或者调用了lua_closeslot。被标记位待关闭的槽位不应当使用除了lua_settop和lua_pop之外的任何API函数将其移除，除非提前通过lua_closeslot使之都失活了。

传入此函数的索引不应当等于或低于其他的待关闭槽位（原文没有解释原因，从源码看应当是为了保证析构的顺序）。

注意当 __close 元函数运行时，其无论是发生了错误还是正常返回，C调用栈都已经展开了，所以在调用函数时自动声明的C变量（例如某个缓冲区）都将超出作用域。

lua_tointeger ​

[-0, +0, -]

lua_Integer lua_tointeger (lua_State *L, int index);

等效于 isnum 参数为NULL调用lua_tointegerx。

lua_tointegerx ​

[-0, +0, -]

lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);

将给定索引处的Lua值转换为有符号整数类型lua_Integer。给出的Lua值必须是整数、或是一个 number 、或是一个内容为可转换为整数的数字字符串（参见3.4.3）；否则lua_tointegerx返回0。

如果参数 isnum 不为NULL，则会被赋值为一个布尔值以表明转换是否成功。

lua_tolstring ​

[-0, +0, m]

const char *lua_tolstring (lua_State *L, int index, size_t *len);

将给定索引处的字符串转换为C字符串。如果 len 为NULL，其会将 *len 设为字符串长度。给出索引处的值必须是字符串或 number ，否则此函数返回NULL。如果是 number ，lua_tolstring会将栈上的实际值改为字符串。（通过lua_next遍历表时对键使用lua_tolstring时会因为这里的改变而混淆遍历。）

lua_tolstring返回值为在Lua状态机内部的一个字符串指针。此字符串总是以零（'\0'）结尾（即C风格字符串），但是可以在其正文中包含其他的零。

lua_tonumber ​

[-0, +0, -]

lua_Number lua_tonumber (lua_State *L, int index);

等效于 isnum 参数为NULL调用lua_tonumberx。

lua_tonumberx ​

[-0, +0, -]

lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);

将给定索引处的Lua值转换为C类型lua_Number。给出的Lua值必须为一个 number 或一个可转换为number的字符串（参见3.4.3）；否则lua_tonumberx返回0。

如果参数 isnum 不为NULL，则会被赋值为一个布尔值以表明操作是否成功。

lua_topointer ​

[-0, +0, -]

const void *lua_topointer (lua_State *L, int index);

将给定索引处的Lua值转换为一个通用C指针（void*）。给出的值必须为 userdata、表、Lua线程、字符串或函数中的一种；否则lua_topointer将返回 NULL。不同的对象会得到不同的指针。并且无法将指针转换为原始值。

通常此函数只用于哈希和调试信息中。

lua_tostring ​

[-0, +0, m]

const char *lua_tostring (lua_State *L, int index);

等效于 len 参数为NULL时调用lua_tolstring。

lua_tothread ​

[-0, +0, -]

lua_State *lua_tothread (lua_State *L, int index);

将给定索引处的值转换为Lua线程（用 lua_State* 类型表示）。给出的值必须为一个Lua线程；否则此函数返回NULL。

lua_touserdata ​

[-0, +0, -]

void *lua_touserdata (lua_State *L, int index);

如果给出索引处的值为一个 full userdata，则返回其内存块的地址。如果这个值为一个 light userdata，则直接返回值（light userdata 本就是个指针）。否则返回NULL。

lua_type ​

[-0, +0, -]

int lua_type (lua_State *L, int index);

返回给定索引处值的类型，或者返回 LUA_TNONE 表示无效但可接受的索引。由lua_type返回的类型在源代码 lua.h 文件中定义：LUA_TNIL、LUA_TNUMBER、LUA_TBOOLEAN、LUA_TSTRING、LUA_TTABLE、LUA_TFUNCTION、LUA_TUSERDATA、LUA_TTHREAD、以及 LUA_TLIGHTUSERDATA 。

lua_typename ​

[-0, +0, -]

const char *lua_typename (lua_State *L, int tp);

返回类型值 tp 对应的类型名，其必须是可以由lua_type返回的值。

lua_Unsigned ​

typedef ... lua_Unsigned;

lua_Integer的无符号版本。

lua_upvalueindex ​

[-0, +0, -]

int lua_upvalueindex (int i);

返回此刻在运行的函数的第 i 个上值的虚拟索引（参见4.2）。i 必须在区间[1, 256]内。

lua_version ​

[-0, +0, -]

lua_Number lua_version (lua_State *L);

返回Lua版本。

lua_WarnFunction ​

typedef void (*lua_WarnFunction) (void *ud, const char *msg, int tocont);

警告函数的类型，由Lua发出警告时调用。第一个参数是由lua_setwarnf设置的一个不透明指针。第二个参数是警告消息。第三个参数是个布尔值，用以表示是否会在下一次调用时继续重复这个警告消息。

关于警告的更多细节请参见warn。

lua_Writer ​

typedef int (*lua_Writer) (lua_State *L,
                           const void* p,
                           size_t sz,
                           void* ud);

由lua_dump使用的写入函数。每次lua_dump需要读到代码块中的下一部分时都会调用它，调用时传入写入缓冲区（p）、大小（sz）以及提供给lua_dump的参数（ud）。

此函数会返回一个错误码：0意味着没有错误；其他的值意味着有错误且在下次调用前停止lua_dump。

lua_xmove ​

[-?, +?, -]

void lua_xmove (lua_State *from, lua_State *to, int n);

在同一个状态机中的不同Lua线程间交换值。

此函数会从 from 的栈上弹出n个值，并将其压入到 to 的栈中。

lua_yield ​

[-?, +?, v]

int lua_yield (lua_State *L, int nresults);

此函数等效于lua_yieldk，但是它没有延续函数（参见4.5）。因此，当唤醒Lua线程时，其会从之前调用lua_yield的地方开始执行。为避免意外，此函数应当在尾调用中使用。

lua_yieldk ​

[-?, +?, v]

int lua_yieldk (lua_State *L,
                int nresults,
                lua_KContext ctx,
                lua_KFunction k);

让出一个协程（Lua线程）。

当C函数中调用lua_yieldk时，正在运行的协程会被挂起，通过调用lua_resume可以启动这个协程并继续返回。参数 nresults 表示当使用 lua_resume唤醒是将会从栈上返回多少个值。

当协程被再次唤醒，Lua会调用给出的延续函数 k 以在C函数中让出后继续执行（参见4.5）。这个延续函数会接收和之前的函数相同的栈，并将 n 个结果替换传递给 lua_resume。此外，延续函数还会接收由lua_yieldk传递的值 ctx 。

通常这个函数不会返回；当协程最终被恢复时，它会继续执行延续函数。然而有一种特殊情况：当其在行内或计数 hook 中被调用时（参见4.7）。在这种情况下，lua_yieldk应当不使用延续函数（索性使用lua_yield）且无结果返回，hook 也应当在此函数调用后立刻返回。Lua会让出，并当其再次唤醒时将继续执行并触发 hook 的函数。

当其由一个Lua线程中的一个挂起的C调用且没有延续函数时（被称为C调用边界），此函数可能会抛出错误，或者在一个无法在运行时挂起的Lua线程中调用时（通常是Lua主线程）。