The Application Program Interface

4 – The Application Program Interface

本节描述 Lua 的 C API，即主机程序可用于与 Lua 通信的一组 C 函数。所有的 API 函数以及相关的类型和常量都在头文件中声明lua.h。

即使我们使用术语“功能”，API中的任何工具都可以作为宏提供。除非另有说明，否则所有这些宏都只使用它们的每个参数一次（除了第一个参数，它总是一个Lua状态），所以不会产生任何隐藏的副作用。

和大多数C库一样，Lua API函数也不检查参数的有效性或一致性。但是，您可以通过使用LUA_USE_APICHECK定义的宏编译Lua来更改此行为。

Lua库是完全可重入的：它没有全局变量。它将所需的所有信息保存在一个称为Lua状态的动态结构中。

每个Lua状态都有一个或多个线程，这些线程对应于独立的合作执行线。类型lua_State（尽管它的名称）是指一个线程。（间接地，通过线程，它也指与线程关联的Lua状态。）

一个指向线程的指针必须作为第一个参数传递给库中的每个函数，除了lua_newstate从头创建一个Lua状态并返回一个指向新状态主线程的指针。

4.1 – The Stack

Lua使用虚拟堆栈向C传递值和从C传递值。此堆栈中的每个元素表示一个Lua值（零，数字，字符串等）。API中的函数可以通过它们接收的Lua状态参数访问此堆栈。

每当Lua调用C时，被调用的函数都会得到一个新的堆栈，它独立于先前的堆栈和仍然处于活动状态的C函数堆栈。此堆栈最初包含C函数的任何参数，并且它是C函数可以存储临时Lua值的位置，并且必须将其结果返回给调用方（请参阅参考资料lua_CFunction）。

为方便起见，API中的大多数查询操作都不遵循严格的堆栈规则。相反，他们可以使用索引引用堆栈中的任何元素：正数索引表示绝对堆栈位置（从1开始）; 负索引表示相对于堆栈顶部的偏移量。更具体地说，如果堆栈有n个元素，则索引1表示第一个元素（即，先推入堆栈的元素），而索引n表示最后一个元素; 索引-1也表示最后一个元素（即顶部的元素）和索引-n表示第一个元素。

4.2 – Stack Size

当您与 Lua API 交互时，您有责任确保一致性。特别是，你负责控制堆栈溢出。您可以使用该函数lua_checkstack确保堆栈有足够的空间来推送新元素。

每当 Lua 调用 C 时，它都会确保堆栈至少有LUA_MINSTACK额外的插槽空间。LUA_MINSTACK被定义为20，所以通常你不必担心堆栈空间，除非你的代码有循环将元素推入堆栈。

当你调用没有固定数量结果的Lua函数时（参见lua_call参考资料），Lua确保堆栈为所有结果提供了足够的空间，但它不能确保有任何额外的空间。所以，在这样的通话之后，在推动任何东西之前，你应该使用lua_checkstack。

4.3 – Valid and Acceptable Indices

接收堆栈索引的API中的任何函数只能使用有效的索引或可接受的索引。

有效的索引是指存储可修改的Lua值的位置的索引。它包含1和堆栈顶部（1 ≤ abs(index) ≤ top）之间的堆栈索引以及伪代码，它们代表C代码可访问但不在堆栈中的某些位置。伪索引用于访问注册表（请参阅第4.5节）和C函数的高价值（请参阅第4.4节）。

函数不需要特定的可变位置，但只有一个值（例如查询函数），可以用可接受的索引来调用。一个可接受的索引可以是任何有效的索引，但它也可以是在为该堆栈分配的空间内的堆栈顶部之后的任何正数索引，即，索引直至堆栈大小。（请注意，0永远不是可接受的索引。）除非另有说明，API中的函数可以使用可接受的索引。

查询堆栈时，可接受的索引用于避免对堆栈顶部进行额外的测试。例如，一个C函数可以查询它的第三个参数，而不需要先检查是否有第三个参数，也就是说，不需要检查3是否是一个有效的索引。

对于可以用可接受索引调用的函数，任何无效索引都被视为包含虚拟类型的值LUA_TNONE，其行为类似于零值。

4.4 – C Closures

当创建一个C函数时，可以将一些值与它关联，从而创建一个C闭包（参见lua_pushcclosure）; 这些值被称为upvalues，并且只要被调用就可以被该函数访问。

无论何时调用C函数，它的upvalues都位于特定的伪索引处。这些伪指数是由宏产生的lua_upvalueindex。与函数关联的第一个upvalue位于索引处lua_upvalueindex(1)，依此类推。任何访问，其中n大于当前函数的upvalues数（但不大于256，这是一个加上闭包中upvalues的最大数），产生一个可接受但无效的索引。lua_upvalueindex(n)

4.5 – Registry

Lua提供了一个注册表，这是一个预定义的表，任何C代码都可以使用它来存储它需要存储的任何Lua值。注册表表格始终位于伪索引处LUA_REGISTRYINDEX。任何C库都可以将数据存储到此表中，但必须注意选择与其他库所使用的不同的密钥，以避免冲突。通常，您应该使用包含您的库名称的字符串或代码中具有C对象地址的轻型用户数据或由您的代码创建的任何Lua对象作为关键字。与变量名一样，以下划线开头的字符串键后跟大写字母保留给Lua。

注册表中的整数键由引用机制（请参阅luaL_ref）和一些预定义的值使用。因此，整数键不能用于其他目的。

当你创建一个新的Lua状态时，它的注册表带有一些预定义的值。这些预定义值使用定义为常量的整数键索引lua.h。定义了以下常量：

• LUA_RIDX_MAINTHREAD： 在这个索引处，注册表具有状态的主线程。（主线程是与状态一起创建的主线程。）

4.6 – Error Handling in C

在内部，Lua 使用C longjmp工具来处理错误。（如果将它编译为C ++，Lua将使用异常; LUAI_THROW有关详细信息，请在源代码中进行搜索。）当Lua面临任何错误（例如内存分配错误或类型错误）时，会引发错误; 也就是说，它跳远了。一个受保护的环境使用setjmp设置一个恢复点; 任何错误都会跳转到最近的活动恢复点。

在 C 函数内部，您可以通过调用来引发错误lua_error。

API中的大多数函数都可能引发错误，例如由于内存分配错误。每个函数的文档都指出它是否会引发错误。

如果在任何受保护的环境之外发生错误，Lua会调用panic函数（请参阅lua_atpanic）然后调用abort，从而退出主机应用程序。你的恐慌功能可以通过永不返回来避免这种退出（例如，在Lua之外跳转到自己的恢复点）。

正如其名称所暗示的，恐慌功能是一种最后的手段。程序应该避免它。一般来说，当Lua调用一个Lua状态的C函数时，它可以在Lua状态下做任何事情，因为它应该已经被保护了。但是，当C代码运行在其他Lua状态（例如，函数的Lua参数，存储在注册表中的Lua状态或结果lua_newthread）时，它应该只在不会引发错误的API调用中使用它们。

恐慌函数就像是一个消息处理程序一样运行（请参阅第2.3节）; 特别是，错误对象位于堆栈的顶部。但是，堆栈空间不能保证。要推动堆栈中的任何内容，恐慌功能必须首先检查可用空间（请参阅第4.2节）。

4.7 – Handling Yields in C

在内部，Lua 使用C longjmp工具来产生协程。因此，如果一个C函数foo调用一个API函数并且这个API函数产生（通过调用另一个产生的函数直接或间接产生），Lua不能再返回foo，因为longjmp它从C栈中移除了它的框架。

为了避免这样的问题，提出的Lua每当它试图跨越API调用来产生，除了三个功能错误：lua_yieldk，lua_callk，和lua_pcallk。所有这些函数都会收到一个继续函数（作为一个名为参数k）以在yield之后继续执行。

我们需要设置一些术语来解释延续。我们有一个从 Lua 调用的 C 函数，我们将其称为原始函数。这个原始函数然后调用 C API 中的三个函数之一，我们将调用被调用函数，然后产生当前线程。（这可能发生在被调用函数时lua_yieldk，或者当被调用函数是lua_callk或者lua_pcallk并且由它们调用的函数产生时）。

假设正在运行的线程在执行被调用函数时产生。线程恢复后，它最终将完成运行被调用函数。但是，被调用函数无法返回到原始函数，因为C堆栈中的框架被yield损坏了。相反，Lua调用一个继续函数，它被作为被调用函数的参数给出。顾名思义，继续功能应该继续原有功能的任务。

作为说明，请考虑以下功能：

int original_function (lua_State *L) {
  ...     /* code 1 */
  status = lua_pcall(L, n, m, h  /* calls Lua */
  ...     /* code 2 */
}

现在我们要允许运行的Lua代码lua_pcall生成。首先，我们可以像这样重写我们的功能：

int k (lua_State *L, int status, lua_KContext ctx) {
  ...  /* code 2 */
}

int original_function (lua_State *L) {
  ...     /* code 1 */
  return k(L, lua_pcall(L, n, m, h), ctx
}

在上面的代码中，新函数k是一个继承函数（带有类型lua_KFunction），它应该完成原函数在调用之后所做的所有工作lua_pcall。现在，我们必须告诉Lua，k如果被执行的Lua代码lua_pcall以某种方式被中断（错误或屈服），它必须调用，所以我们在这里重写代码，替换lua_pcall为lua_pcallk：

int original_function (lua_State *L) {
  ...     /* code 1 */
  return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1
}

请注意对延续的外部显式调用：只有在需要时，Lua才会调用延续，也就是说，如果发生错误或者在yield之后恢复。如果被调用的函数正常返回而没有屈服，lua_pcallk（和lua_callk）也将正常返回。（当然，不是在这种情况下调用延续，而是直接在原始函数内执行等效工作。）

除了Lua状态之外，continuation函数还有两个其他参数：调用的最终状态和ctx最初传递给的上下文值（）lua_pcallk。（Lua没有使用这个上下文值，它只是将原始函数中的值传递给继续函数）。因为lua_pcallk，状态与返回的值相同lua_pcallk，只不过它是LUA_YIELD在yield之后执行的（而不是的LUA_OK）。对于lua_yieldk和lua_callk，LUA_YIELD当Lua称为延续时，状态总是如此。（对于这两个函数，如果发生错误，Lua将不会调用延续，因为它们不会处理错误。）类似地，使用时lua_callk，您应该LUA_OK以状态的形式调用延续函数。（对于lua_yieldk，直接调用继续函数没有太大意义，因为lua_yieldk通常不会返回。）

Lua 将延续功能看作是原始功能。continuation函数从原始函数接收相同的Lua堆栈，处于与被调用函数返回时相同的状态。（例如，lua_callk函数及其参数从堆栈中移除并由调用的结果替换后）。它也具有相同的upvalues。无论它返回的是由Lua处理，就好像它是原始函数的返回一样。

4.8 – Functions and Types-o, +p, x

这里我们按字母顺序列出C API中的所有函数和类型。每个功能都有一个像这样的指示器：

第一个字段o是函数从堆栈中弹出多少个元素。第二个字段p是函数将多少元素压入堆栈。（任何函数在弹出其参数后总是推送其结果。）表单中的字段x|y表示该函数可以推送（或弹出）x或y元素，具体取决于具体情况; 一个询问标记“ ?'意味着我们无法通过仅查看其参数（例如，它们可能取决于栈上的内容）来知道该函数弹出/推动多少个元素。第三个字段x告诉函数是否会引发错误：' -'表示函数不会引发任何错误; ' m'表示该函数可能引发运行元方法的内存__gc不足错误和错误; “e'表示该函数可能引发任何错误（它可以直接或通过元方法运行任意Lua代码）; ' v'表示该功能可能会故意提出错误。

lua_absindex-0, +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当且仅当它不能满足请求时，分配器才返回。Lua认为分配器从不失败时osize >= nsize。

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

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
}

请注意，标准C确保free(NULL)没有任何影响，这realloc(NULL,size)相当于malloc(size)。此代码假定realloc缩小块时不会失败。（虽然标准C不能确保这种行为，但这似乎是一个安全的假设。）

lua_arith-(2|1), +1, e

void lua_arith (lua_State *L, int op

对堆栈顶部的两个值（或一个，如果是否定）执行算术运算或按位运算，顶部的值为第二个操作数，弹出这些值并推送操作结果。该函数遵循相应的Lua运算符的语义（也就是说，它可能调用metamethods）。

值op必须是以下常量之一：

• LUA_OPADD： 执行addition（+）

lua_atpanic-0, +0, –

lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf

设置一个新的恐慌函数并返回旧函数（参见§4.6）。

lua_call-(nargs+1), +nresults, e

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

调用一个函数。

要调用函数，您必须使用以下协议：首先，要调用的函数被压入堆栈; 然后，函数的参数按直接顺序推入; 也就是说，第一个参数是先推。最后你打电话lua_call; nargs是您推入堆栈的参数的数量。函数被调用时，所有参数和函数值都从堆栈弹出。当函数返回时，函数结果被压入堆栈。结果的数量调整为nresults，除非nresults是LUA_MULTRET。在这种情况下，该功能的所有结果都会被推送; Lua注意返回值适合堆栈空间，但它不能确保堆栈中有任何额外的空间。函数结果按直接顺序压入堆栈（第一个结果先被压入），这样在调用后最后的结果位于堆栈的顶部。

被调用函数中的任何错误都向上传播（使用a longjmp）。

以下示例显示主机程序如何执行与此Lua代码等效的操作：

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

这里是在C：

lua_getglobal(L, "f"                  /* function to be called */
lua_pushliteral(L, "how"                       /* 1st argument */
lua_getglobal(L, "t"                    /* table to be indexed */
lua_getfield(L, -1, "x"        /* push result of t.x (2nd arg) */
lua_remove(L, -2                  /* remove 't' from the stack */
lua_pushinteger(L, 14                          /* 3rd argument */
lua_call(L, 3, 1     /* call 'f' with 3 arguments and 1 result */
lua_setglobal(L, "a"                         /* set global 'a' */

请注意，上面的代码是平衡的：在最后，堆栈恢复到原来的配置。这被认为是很好的编程习惯。

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.7）。

lua_CFunction

typedef int (*lua_CFunction) (lua_State *L

输入C函数。

为了与Lua进行正确的通信，C函数必须使用以下协议，该协议定义了传递参数和结果的方式：C函数以直接顺序（第一个参数先被压入）从Lua堆栈中直接接收它的参数。所以，当函数启动时，lua_gettop(L)返回函数收到的参数个数。第一个参数（如果有）位于索引1，最后一个参数位于索引处lua_gettop(L)。为了将值返回给Lua，C函数只是将它们按顺序推送到堆栈中（第一个结果被首先推送），然后返回结果的数目。结果下方的任何其他值将被Lua正确丢弃。像Lua函数一样，Lua调用的C函数也可以返回许多结果。

作为一个例子，下面的函数接收可变数量的数字参数并返回它们的平均值和它们的总和：

static int foo (lua_State *L) {
  int n = lua_gettop(L    /* number of arguments */
  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        /* first result */
  lua_pushnumber(L, sum         /* second result */
  return 2;                   /* number of results */
}

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状态下的所有对象（调用相应的垃圾收集元方法，如果有的话）并释放此状态使用的所有动态内存。在多个平台上，您可能不需要调用此函数，因为所有资源在主机程序结束时自然释放。另一方面，创建多个状态的长时间运行的程序（如守护程序或Web服务器）可能需要在不需要时立即关闭状态。

lua_compare-0, +0, e

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

比较两个 Lua 值。如果在索引中的值，则返回1 index1满足op时与索引的值进行比较index2，以下对应的Lua操作符的语义（即，它可以调用元方法）。否则返回0.如果任何索引无效，则返回0。

值op必须是以下常量之一：

• LUA_OPEQ： 比较平等（==）

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为真，则二进制表示可能不包含有关该函数的所有调试信息，以节省空间。

返回的值是上次调用writer时返回的错误代码; 0表示没有错误。

该函数不会从堆栈中弹出Lua函数。

lua_error-1, +0, v

int lua_error (lua_State *L

生成一个 Lua 错误，使用堆栈顶部的值作为错误对象。此功能会跳远，因此不会返回（请参阅luaL_error）。

lua_gc-0, +0, m

int lua_gc (lua_State *L, int what, int data

控制垃圾收集器。

根据参数的值，该功能执行几项任务what：

• LUA_GCSTOP：停止垃圾收集器。

有关这些选项的更多详细信息，请参阅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一样，这个函数可能触发“索引”事件的元方法（见§2.4）。

返回推送值的类型。

lua_getextraspace-0, +0, –

void *lua_getextraspace (lua_State *L

返回指向与给定的Lua状态相关的原始内存区域的指针。应用程序可以将此区域用于任何目的; Lua没有使用它。

每个新线程都使用主线程区域的副本初始化该区域。

默认情况下，该区域的指针大小为void，但您可以使用该区域的不同大小重新编译Lua。（参见LUA_EXTRASPACE在luaconf.h）。

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一样，这个函数可能触发“索引”事件的元方法（见§2.4）。

返回推送值的类型。

lua_getmetatable-0, +(0|1), –

int lua_getmetatable (lua_State *L, int index

如果给定索引处的值具有metatable，则该函数会将metatable推送到堆栈并返回1.否则，该函数将返回0，并且不会在堆栈上执行任何操作。

lua_gettable-1, +1, e

int lua_gettable (lua_State *L, int index

将值推入堆栈t[k]，其中t是给定索引k处的值，并且是堆栈顶部的值。

该函数从堆栈弹出键，将结果值推到原位。和Lua一样，这个函数可能触发“索引”事件的元方法（见§2.4）。

返回推送值的类型。

lua_gettop-0, +0, –

int lua_gettop (lua_State *L

返回堆栈中顶层元素的索引。因为索引从1开始，所以这个结果等于堆栈中元素的数量; 特别是，0表示空栈。

lua_getuservalue-0, +1, –

int lua_getuservalue (lua_State *L, int index

将与给定索引处的完整用户数据关联的Lua值推入堆栈。

返回推送值的类型。

lua_insert-1, +1, –

void lua_insert (lua_State *L, int index

将顶层元素移动到给定的有效索引中，将该索引上方的元素向上移动以打开空间。该函数不能用伪索引调用，因为伪索引不是实际的堆栈位置。

lua_Integer

typedef ... lua_Integer;

Lua中的整数类型。

默认情况下，这个类型是long long（通常是一个64位二补数整数），但可以改为long或int（通常是一个32位二补数整数）。（参见LUA_INT_TYPE在luaconf.h）。

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_isfunction-0, +0, –

int lua_isfunction (lua_State *L, int index

如果给定索引处的值是一个函数（C或Lua），则返回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

如果给定索引处的值为零，则返回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

如果给定索引无效或者此索引处的值为零，则返回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

Returns 1 if the value at the given index is a string or a number (which is always convertible to a string), and 0 otherwise.

lua_istable-0, +0, –

int lua_istable (lua_State *L, int index

Returns 1 if the value at the given index is a table, and 0 otherwise.

lua_isthread-0, +0, –

int lua_isthread (lua_State *L, int index

Returns 1 if the value at the given index is a thread, and 0 otherwise.

lua_isuserdata-0, +0, –

int lua_isuserdata (lua_State *L, int index

Returns 1 if the value at the given index is a userdata (either full or light), and 0 otherwise.

lua_isyieldable-0, +0, –

int lua_isyieldable (lua_State *L

Returns 1 if the given coroutine can yield, and 0 otherwise.

lua_KContext

typedef ... lua_KContext;

The type for continuation-function contexts. It must be a numeric type. This type is defined as intptr_t when intptr_t is available, so that it can store pointers too. Otherwise, it is defined as ptrdiff_t.

lua_KFunction

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

Type for continuation functions (see §4.7).

lua_len-0, +1, e

void lua_len (lua_State *L, int index

Returns the length of the value at the given index. It is equivalent to the '#' operator in Lua (see §3.4.7) and may trigger a metamethod for the "length" event (see §2.4). The result is pushed on the stack.

lua_load-0, +1, –

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

Loads a Lua chunk without running it. If there are no errors, lua_load pushes the compiled chunk as a Lua function on top of the stack. Otherwise, it pushes an error message.

The return values of lua_load are:

• LUA_OK: no errors;

The lua_load function uses a user-supplied reader function to read the chunk (see lua_Reader). The data argument is an opaque value passed to the reader function.

The chunkname argument gives a name to the chunk, which is used for error messages and in debug information (see §4.9).

lua_load automatically detects whether the chunk is text or binary and loads it accordingly (see program luac). The string mode works as in function load, with the addition that a NULL value is equivalent to the string "bt".

lua_load uses the stack internally, so the reader function must always leave the stack unmodified when returning.

If the resulting function has upvalues, its first upvalue is set to the value of the global environment stored at index LUA_RIDX_GLOBALS in the registry (see §4.5). When loading main chunks, this upvalue will be the _ENV variable (see §2.2). Other upvalues are initialized with nil.

lua_newstate-0, +0, –

lua_State *lua_newstate (lua_Alloc f, void *ud

Creates a new thread running in a new, independent state. Returns NULL if it cannot create the thread or the state (due to lack of memory). The argument f is the allocator function; Lua does all memory allocation for this state through this function (see lua_Alloc). The second argument, ud, is an opaque pointer that Lua passes to the allocator in every call.

lua_newtable-0, +1, m

void lua_newtable (lua_State *L

Creates a new empty table and pushes it onto the stack. It is equivalent to lua_createtable(L, 0, 0).

lua_newthread-0, +1, m

lua_State *lua_newthread (lua_State *L

Creates a new thread, pushes it on the stack, and returns a pointer to a lua_State that represents this new thread. The new thread returned by this function shares with the original thread its global environment, but has an independent execution stack.

There is no explicit function to close or to destroy a thread. Threads are subject to garbage collection, like any Lua object.

lua_newuserdata-0, +1, m

void *lua_newuserdata (lua_State *L, size_t size

This function allocates a new block of memory with the given size, pushes onto the stack a new full userdata with the block address, and returns this address. The host program can freely use this memory.

lua_next-1, +(2|0), e

int lua_next (lua_State *L, int index

Pops a key from the stack, and pushes a key–value pair from the table at the given index (the "next" pair after the given key). If there are no more elements in the table, then lua_next returns 0 (and pushes nothing).

A typical traversal looks like this:

/* table is in the stack at index 't' */
lua_pushnil(L  /* first key */
while (lua_next(L, t) != 0) {
  /* uses 'key' (at index -2) and 'value' (at index -1) */
  printf("%s - %s\n",
         lua_typename(L, lua_type(L, -2)),
         lua_typename(L, lua_type(L, -1))
  /* removes 'value'; keeps 'key' for next iteration */
  lua_pop(L, 1
}

While traversing a table, do not call lua_tolstring directly on a key, unless you know that the key is actually a string. Recall that lua_tolstring may change the value at the given index; this confuses the next call to lua_next.

See function next for the caveats of modifying the table during its traversal.

lua_Number

typedef ... lua_Number;

The type of floats in Lua.

By default this type is double, but that can be changed to a single float or a long double. (See LUA_FLOAT_TYPE in luaconf.h.)

lua_numbertointeger

int lua_numbertointeger (lua_Number n, lua_Integer *p

Converts a Lua float to a Lua integer. This macro assumes that n has an integral value. If that value is within the range of Lua integers, it is converted to an integer and assigned to *p. The macro results in a boolean indicating whether the conversion was successful. (Note that this range test can be tricky to do correctly without this macro, due to roundings.)

This macro may evaluate its arguments more than once.

lua_pcall-(nargs + 1), +(nresults|1), –

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

Calls a function in protected mode.

Both nargs and nresults have the same meaning as in lua_call. If there are no errors during the call, lua_pcall behaves exactly like lua_call. However, if there is any error, lua_pcall catches it, pushes a single value on the stack (the error object), and returns an error code. Like lua_call, lua_pcall always removes the function and its arguments from the stack.

If msgh is 0, then the error object returned on the stack is exactly the original error object. Otherwise, msgh is the stack index of a message handler. (This index cannot be a pseudo-index.) In case of runtime errors, this function will be called with the error object and its return value will be the object returned on the stack by lua_pcall.

Typically, the message handler is used to add more debug information to the error object, such as a stack traceback. Such information cannot be gathered after the return of lua_pcall, since by then the stack has unwound.

The lua_pcall function returns one of the following constants (defined in lua.h):

• LUA_OK (0): success.

lua_pcallk-(nargs + 1), +(nresults|1), –

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

This function behaves exactly like lua_pcall, but allows the called function to yield (see §4.7).

lua_pop-n, +0, –

void lua_pop (lua_State *L, int n

Pops n elements from the stack.

lua_pushboolean-0, +1, –

void lua_pushboolean (lua_State *L, int b

Pushes a boolean value with value b onto the stack.

lua_pushcclosure-n, +1, m

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

Pushes a new C closure onto the stack.

When a C function is created, it is possible to associate some values with it, thus creating a C closure (see §4.4 these values are then accessible to the function whenever it is called. To associate values with a C function, first these values must be pushed onto the stack (when there are multiple values, the first value is pushed first). Then lua_pushcclosure is called to create and push the C function onto the stack, with the argument n telling how many values will be associated with the function. lua_pushcclosure also pops these values from the stack.

The maximum value for n is 255.

When n is zero, this function creates a light C function, which is just a pointer to the C function. In that case, it never raises a memory error.

lua_pushcfunction-0, +1, –

void lua_pushcfunction (lua_State *L, lua_CFunction f

Pushes a C function onto the stack. This function receives a pointer to a C function and pushes onto the stack a Lua value of type function that, when called, invokes the corresponding C function.

Any function to be callable by Lua must follow the correct protocol to receive its parameters and return its results (see lua_CFunction).

lua_pushfstring-0, +1, e

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

Pushes onto the stack a formatted string and returns a pointer to this string. It is similar to the ISO C function sprintf, but has some important differences:

• You do not have to allocate space for the result: the result is a Lua string and Lua takes care of memory allocation (and deallocation, through garbage collection).

Unlike other push functions, this function checks for the stack space it needs, including the slot for its result.

lua_pushglobaltable-0, +1, –

void lua_pushglobaltable (lua_State *L

Pushes the global environment onto the stack.

lua_pushinteger-0, +1, –

void lua_pushinteger (lua_State *L, lua_Integer n

Pushes an integer with value n onto the stack.

lua_pushlightuserdata-0, +1, –

void lua_pushlightuserdata (lua_State *L, void *p

将轻量级用户数据推入堆栈。

用户数据表示 Lua 中的C值。一个light userdata代表一个指针，一个void*。它是一个值（像一个数字）：你不创建它，它没有单独的metatable，它不被收集（因为它从来没有被创建）。轻的用户数据等于具有相同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

将s尺寸指向的字符串len推入堆栈。Lua创建（或重新使用）给定字符串的内部副本，因此s可以在函数返回后立即释放或重用内存。该字符串可以包含任何二进制数据，包括嵌入的零。

返回一个指向字符串内部副本的指针。

lua_pushnil-0, +1, –

void lua_pushnil (lua_State *L

将一个零值推入堆栈。

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可以在函数返回后立即释放或重用内存。

返回一个指向字符串内部副本的指针。

如果s是NULL，推零和返回NULL。

lua_pushthread-0, +1, –

int lua_pushthread (lua_State *L

将由代表的线程L推入堆栈。如果此线程是其状态的主线程，则返回1。

lua_pushvalue-0, +1, –

void lua_pushvalue (lua_State *L, int index

将给定索引处元素的副本压入堆栈。

lua_pushvfstring-0, +1, m

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

如果在索引的两个值，则返回1 index1和index2是原始地等于（即，不调用__eq元方法）。否则返回0.如果任何索引无效，则返回0。

lua_rawget-1, +1, –

int lua_rawget (lua_State *L, int index

类似于lua_gettable，但没有原始访问（即没有metamethods）。

lua_rawgeti-0, +1, –

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

将值推入堆栈t[n]，其中t是给定索引处的表。访问是原始的，也就是说，它不会调用__indexmetamethod。

返回推送值的类型。

lua_rawgetp-0, +1, –

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

将值推入堆栈t[k]，其中t是给定索引处的表，并且k是指示p为轻型用户数据的指针。访问是生的; 也就是说，它不会调用__indexmetamethod。

返回推送值的类型。

lua_rawlen-0, +0, –

size_t lua_rawlen (lua_State *L, int index

返回给定索引处的值的原始“长度”：对于字符串，这是字符串长度; 对于表，这是长度运算符（' #'）的结果，没有metamethods; 对于用户数据，这是为用户数据分配的内存块的大小; 对于其他值，它是0。

lua_rawset-2, +0, m

void lua_rawset (lua_State *L, int index

类似lua_settable，但做了原始分配（即没有metamethods）。

lua_rawseti-1, +0, m

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

是否相当于t[i] = v，其中t是表中的给定索引处并且v是在堆栈的顶部的值。

该函数从堆栈中弹出值。该任务是原始的，也就是说，它不会调用__newindexmetamethod。

lua_rawsetp-1, +0, m

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

是否等价于给定索引处的表在t[p] = v哪里t被p编码为轻型用户数据，并且v是堆栈顶部的值。

该函数从堆栈中弹出值。该任务是原始的，也就是说，它不会调用__newindexmetamethod。

lua_Reader

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

读者功能使用lua_load。每次它需要另一块时，lua_load调用读者，传递其data参数。阅读器必须返回一个指向一块内存块的指针并将其设置size为块大小。该块必须存在，直到再次调用阅读器功能。为了表示块的结束，阅读器必须返回NULL或设置size为零。阅读器功能可以返回任何大于零的尺寸的部分。

lua_register-0, +0, e

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

将C函数设置f为全局的新值name。它被定义为一个宏：

#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

将顶层元素移动到给定的有效索引中，而不移动任何元素（因此替换该给定索引处的值），然后弹出顶层元素。

lua_resume-?, +?, –

int lua_resume (lua_State *L, lua_State *from, int nargs

在给定的线程中启动并恢复一个协程L。

要启动一个协程，你可以将线程堆栈的主函数加上任何参数; 然后你打电话lua_resume，nargs作为参数的数量。这个调用在协程暂停或结束执行时返回。当它返回时，堆栈包含传递给的lua_yield所有值，或者正文函数返回的所有值。lua_resume返回LUA_YIELD如果协程产率，LUA_OK如果所述协程完成它的执行没有错误，或在错误的情况下的错误代码（参见lua_pcall）。

如果发生错误，堆栈不会解开，因此您可以使用调试 API 覆盖它。错误对象位于堆栈的顶部。

要恢复一个协程，你可以从最后一个结果中删除任何结果lua_yield，只将其作为结果传入的值放在栈上yield，然后调用lua_resume。

该参数from表示正在恢复的协程L。如果没有这样的协程，这个参数可以NULL。

lua_rotate-0, +0, –

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

在有效索引idx和堆栈顶部之间旋转堆栈元素。这些元素是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_setmetatable-1, +0, –

void lua_setmetatable (lua_State *L, int index

从堆栈中弹出一个表并将其设置为给定索引处的值的新元数据。

lua_settable-2, +0, e

void lua_settable (lua_State *L, int index

是否等同于t[k] = v，这里t是给定索引处的值，v是在堆栈的顶部的值，k略低于前值。

该函数弹出堆栈中的键和值。和Lua一样，这个函数可能触发“newindex”事件的元方法（参见§2.4）。

lua_settop-?, +?, –

void lua_settop (lua_State *L, int index

接受任何索引或0，并将堆栈顶部设置为该索引。如果新的顶部比旧的顶部大，那么新的元素被填充为零。如果index为0，则所有堆栈元素都将被删除。

lua_setuservalue-1, +0, –

void lua_setuservalue (lua_State *L, int index

从堆栈中弹出一个值，并将其设置为与给定索引处的完整用户数据关联的新值。

lua_State

typedef struct lua_State lua_State;

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

一个指向这个结构的指针必须作为第一个参数传递给库中的每个函数，除了lua_newstate从头创建一个Lua状态。

lua_status-0, +0, –

int lua_status (lua_State *L

返回线程的状态L。

The status can be 0 (LUA_OK) for a normal thread, an error code if the thread finished the execution of a lua_resume with an error, or LUA_YIELD if the thread is suspended.

您只能在具有状态的线程中调用函数LUA_OK。您可以恢复具有状态的线程LUA_OK（启动新协程）或LUA_YIELD（恢复协程）。

lua_stringtonumber-0, +1, –

size_t lua_stringtonumber (lua_State *L, const char *s

将以零结尾的字符串s转换为数字，将该数字推入堆栈，并返回字符串的总大小，即其长度加1。根据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_isboolean测试值的类型。）

lua_tocfunction-0, +0, –

lua_CFunction lua_tocfunction (lua_State *L, int index

将给定索引处的值转换为C函数。该值必须是C函数; 否则，返回NULL。

lua_tointeger-0, +0, –

lua_Integer lua_tointeger (lua_State *L, int index

相当于lua_tointegerx用isnum等于NULL。

lua_tointegerx-0, +0, –

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

将给定索引处的Lua值转换为带符号整型lua_Integer。Lua值必须是一个整数，或者是一个可转换为整数的数字或字符串（参见§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

将给定索引处的Lua值转换为C字符串。如果len不是NULL，则设置*len字符串长度。Lua值必须是字符串或数字; 否则，函数返回NULL。如果该值是一个数字，那么lua_tolstring也会将堆栈中的实际值更改为一个字符串。（这种改变在表遍历过程中被应用于键lua_next时lua_tolstring会产生混淆。）

lua_tolstring返回一个指向Lua状态内的字符串的指针。该字符串\0在最后一个字符后面（如C中）始终有一个零（' '），但在其正文中可以包含其他零。

由于 Lua 具有垃圾回收功能，因此不能保证lua_tolstring在将相应的Lua值从堆栈中移除后，返回的指针将会有效。

lua_tonumber-0, +0, –

lua_Number lua_tonumber (lua_State *L, int index

相当于lua_tonumberx用isnum等于NULL。

lua_tonumberx-0, +0, –

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

将给定索引处的Lua值转换为C类型lua_Number（请参阅参考资料lua_Number）。Lua值必须是可转换为数字的数字或字符串（请参阅第3.4.3节）; 否则，lua_tonumberx返回0。

如果isnum不是NULL，则为其指示对象分配一个布尔值，指示操作是否成功。

lua_topointer-0, +0, –

const void *lua_topointer (lua_State *L, int index

将给定索引处的值转换为通用C指针（void*）。该值可以是用户数据，表格，线程或函数; 否则，lua_topointer返回NULL。不同的对象会给出不同的指针。没有办法将指针转换回原始值。

通常这个函数只用于哈希和调试信息。

lua_tostring-0, +0, m

const char *lua_tostring (lua_State *L, int index

相当于lua_tolstring用len等于NULL。

lua_tothread-0, +0, –

lua_State *lua_tothread (lua_State *L, int index

将给定索引处的值转换为Lua线程（表示为lua_State*）。这个值必须是一个线程; 否则，函数返回NULL。

lua_touserdata-0, +0, –

void *lua_touserdata (lua_State *L, int index

如果给定索引处的值是完整的用户数据，则返回其块地址。如果该值是一个light userdata，则返回其指针。否则，退货NULL。

lua_type-0, +0, –

int lua_type (lua_State *L, int index

返回给定有效索引中的值的类型，或者返回LUA_TNONE无效（但可接受）索引中的值的类型。返回的类型lua_type是通过在定义的以下常量编码lua.h：LUA_TNIL（0）， ， ，LUA_TNUMBER，LUA_TBOOLEAN，LUA_TSTRING，，LUA_TTABLE ，和。LUA_TFUNCTIONLUA_TUSERDATALUA_TTHREADLUA_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.4节）。

lua_version-0, +0, –

const lua_Number *lua_version (lua_State *L

返回存储在Lua核中的版本号（一个C静态变量）的地址。当用有效的方式调用时lua_State，返回用于创建该状态的版本的地址。呼叫时NULL，返回运行呼叫的版本的地址。

lua_Writer

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

编写器函数使用的类型lua_dump。每次它产生另一块时，lua_dump调用写入器，传递缓冲区以写入（p），其大小（sz）和data提供给的参数lua_dump。

作者返回一个错误代码：0意味着没有错误; 任何其他值意味着错误，并停止lua_dump再次调用作者。

lua_xmove-?, +?, –

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

交换相同状态的不同线程之间的值。

该函数n从堆栈中弹出值from，并将它们推入堆栈to。

lua_yield-?, +?, e

int lua_yield (lua_State *L, int nresults

这个功能相当于lua_yieldk，但没有延续（见§4.7）。因此，当线程恢复时，它继续调用函数调用的函数lua_yield。

lua_yieldk-?, +?, e

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

产生一个协程（线程）。

当C函数调用时lua_yieldk，正在运行的协程暂停执行，并且lua_resume启动该协程的调用返回。该参数nresults是堆栈中将作为结果传递给的值的数量lua_resume。

当协程再次恢复时，Lua调用给定的继续函数k继续执行产生的C函数（见§4.7）。这个继续函数从前一个函数接收相同的堆栈，并将n结果删除并由传递给它的参数替换lua_resume。而且，继续函数接收ctx传递给的值lua_yieldk。

通常，这个函数不会返回; 当协程最终恢复时，它继续执行延续功能。但是，有一种特殊情况，即在线内或计数挂钩中调用此函数时（请参阅第4.9节）。在这种情况下，lua_yieldk应该在没有延续的情况下（可能以）的形式被调用，lua_yield并且没有结果，并且钩子应该在调用之后立即返回。Lua将屈服，并且当协程再次恢复时，它将继续正常执行触发钩子的（Lua）函数。

如果从具有挂起C调用而没有连续功能的线程调用该函数，或者该函数是从未在简历中运行的线程（例如主线程）调用的，则此函数可能会引发错误。

4.9 – The Debug Interface

Lua 没有内置的调试工具。相反，它通过函数和钩子提供了一个特殊的接口。该接口允许构建不同类型的调试器，分析器和其他需要解释器“内部信息”的工具。

lua_Debug

typedef struct lua_Debug {
  int event;
  const char *name;           /* (n) */
  const char *namewhat;       /* (n) */
  const char *what;           /* (S) */
  const char *source;         /* (S) */
  int currentline;            /* (l) */
  int linedefined;            /* (S) */
  int lastlinedefined;        /* (S) */
  unsigned char nups;         /* (u) number of upvalues */
  unsigned char nparams;      /* (u) number of parameters */
  char isvararg;              /* (u) */
  char istailcall;            /* (t) */
  char short_src[LUA_IDSIZE]; /* (S) */
  /* private part */
  other fields
} lua_Debug;

用于承载有关功能或激活记录的不同信息的结构。lua_getstack只填充这个结构的私有部分，供以后使用。要填充lua_Debug有用信息的其他字段，请致电lua_getinfo。

这些领域lua_Debug具有以下含义：

• source：创建函数的块的名称。如果source以“ @' 开头，则意味着该函数是在文件名称跟在” @“ 之后的文件中定义的。如果source以' =' 开头，则其余内容以依赖于用户的方式描述源。否则，函数被定义在字符串的source字符串中。

lua_gethook-0, +0, –

lua_Hook lua_gethook (lua_State *L

返回当前的挂钩函数。

lua_gethookcount-0, +0, –

int lua_gethookcount (lua_State *L

返回当前挂钩计数。

lua_gethookmask-0, +0, –

int lua_gethookmask (lua_State *L

返回当前的钩子掩码。

lua_getinfo-(0|1), +(0|1|2), e

int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar

获取有关特定函数或函数调用的信息。

要获得关于函数调用的信息，参数ar必须是一个有效的激活记录，该记录由前一次调用lua_getstack或作为参数给出（参见lua_Hook）。

要获得关于某个函数的信息，请将其推入堆栈并what使用字符“ >' 开始字符串。（在这种情况下，lua_getinfo从堆栈顶部弹出该函数。）例如，要知道在哪一行f中定义了函数，可以编写以下代码：

lua_Debug ar;
lua_getglobal(L, "f"  /* get global 'f' */
lua_getinfo(L, ">S", &ar
printf("%d\n", ar.linedefined

字符串中的每个字符都what选择ar要填充的结构的某些字段或要在堆栈中压入的值：

• ' n'：填写字段name并且namewhat;

该函数在出错时返回0（例如，一个无效的选项what）。

lua_getlocal-0, +(0|1), –

const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n

获取有关给定激活记录或给定函数的局部变量的信息。

在第一种情况下，该参数ar必须是一个有效的激活记录，该记录由前一次调用lua_getstack或作为参数给出（参见lua_Hook）。该索引n选择要检查的局部变量; 查看debug.getlocal有关变量索引和名称的详细信息。

lua_getlocal 将变量的值推入堆栈并返回其名称。

在第二种情况下，ar必须是，NULL并且要检查的功能必须位于堆栈的顶部。在这种情况下，只有Lua函数的参数可见（因为没有关于哪些变量处于活动状态的信息）并且没有值被压入堆栈。

NULL当索引大于活动局部变量的数量时，返回（并且不会执行任何操作）。

lua_getstack-0, +0, –

int lua_getstack (lua_State *L, int level, lua_Debug *ar

获取有关解释器运行时堆栈的信息。

该函数填充了一个lua_Debug结构的一部分，并标识了在给定级别执行的函数的激活记录。0级是当前运行的函数，而n + 1级是已调用级别n的函数（tail 函数除外，它不计入堆栈）。当没有错误时，lua_getstack返回1; 当用大于堆栈深度的级别调用时，它返回0。

lua_getupvalue-0, +(0|1), –

const char *lua_getupvalue (lua_State *L, int funcindex, int n

获取有关n索引处闭包的最新价值的信息funcindex。它将upvalue的值推入堆栈并返回其名称。NULL当索引n大于upvalues的数量时，返回（并且不推送）。

对于 C 函数，此函数使用空字符串""作为所有upvalues的名称。（对于Lua函数，upvalues是函数使用的外部局部变量，因此包含在它的闭包中。）

Upvalues 没有特定的顺序，因为它们在整个功能中处于活动状态。它们以任意顺序编号。

lua_Hook

typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar

键入调试挂钩函数。

每当调用一个钩子时，它的ar参数都会将其字段event设置为触发钩子的特定事件。Lua中识别这些事件与以下常量：LUA_HOOKCALL，LUA_HOOKRET，LUA_HOOKTAILCALL，LUA_HOOKLINE，和LUA_HOOKCOUNT。而且，对于线路事件，该字段currentline也被设置。要获取其他字段的值，ar必须调用该钩子lua_getinfo。

对于呼叫事件，event可以是LUA_HOOKCALL正常值，或者LUA_HOOKTAILCALL对于尾部呼叫; 在这种情况下，将不会有相应的回报事件。

当Lua运行一个钩子时，它会禁止其他钩子调用。因此，如果一个钩子回叫Lua执行一个函数或一个块，这个执行就会发生，不会有任何钩子调用。

钩子函数不能延续，也就是说，他们不能打电话lua_yieldk，lua_pcallk或lua_callk与非空k。

钩子函数可以在下列条件下产生：只有计数和行事件可以产生; 到产量，钩函数必须完成其执行主叫lua_yield与nresults等于零（即，没有值）。

lua_sethook-0, +0, –

void lua_sethook (lua_State *L, lua_Hook f, int mask, int count

设置调试挂钩功能。

参数f是钩子函数。mask指定要在其事件的钩将被称为：它是由常量的位OR形成LUA_MASKCALL，LUA_MASKRET，LUA_MASKLINE，和LUA_MASKCOUNT。该count参数仅在掩码包含时才有意义LUA_MASKCOUNT。对于每个事件，挂钩被调用如下所述：

• 调用钩子： 当解释器调用一个函数时被调用。钩子在Lua在函数获取其参数之前输入新函数之后立即调用。

挂钩通过设置mask为零来禁用。

lua_setlocal-(0|1), +0, –

const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n

设置给定激活记录的局部变量的值。它将堆栈顶部的值赋给变量并返回其名称。它也弹出堆栈中的值。

Returns NULL (and pops nothing) when the index is greater than the number of active local variables.

参数ar和n功能一样lua_getlocal。

lua_setupvalue-(0|1), +0, –

const char *lua_setupvalue (lua_State *L, int funcindex, int n

设置封闭的upvalue的值。它将堆栈顶部的值赋给upvalue并返回它的名字。它也弹出堆栈中的值。

NULL当索引n大于upvalues的数量时，返回（并且不会弹出）。

参数funcindex和n功能一样lua_getupvalue。

lua_upvalueid-0, +0, –

void *lua_upvalueid (lua_State *L, int funcindex, int n

n从索引处的闭包返回编号为upvalue的唯一标识符funcindex。

这些唯一标识符允许程序检查不同的关闭是否共享upvalue。共享一个upvalue（也就是说，访问一个相同的外部局部变量）的Lua闭包将为这些upvalue索引返回相同的id。

参数funcindex和n功能一样lua_getupvalue，但n不能大于upvalues的数量。

lua_upvaluejoin-0, +0, –

void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
                                    int funcindex2, int n2

使n1指数中Lua收盘价的第 - 高价值funcindex1指n2的是指数中Lua收盘价的第 - 高价值funcindex2。