分类：
2013-01-24 09:36:50
原文地址：参考手册 - 3.7 - 函数与类型[L-Z] 作者：hshq_cn
[-0, +0, e]
int lua_lessthan (lua_State *L, int index1, int index2);
如果认可的索引index1处的小于值认可的索引index2处的值则返回1，该操作遵循Lua的<操作符的语义（即可能调用元方法）。否则返回0。如果任何索引不合法也返回0。
[-0, +1, -]
int lua_load (lua_State *L,
lua_Reader reader,
void *data,
const char *chunkname);
加载Lua代码单元。如果没有错误，将编译的单元作为Lua函数压栈。否则，将一条错误消息压栈。的返回值是：
本函数只是载入单元；并不执行它。
自动地检测单元是文本还是二进制，进而加载它（见程序luac）。
函数使用用户提供的reader函数读取单元（见）。data参数是传入读取器函数的不透明值。
chunkname参数给单元提供名字，用于错误消息和调试信息（见）。
[-0, +0, -]
lua_State *lua_newstate (lua_Alloc f, void *ud);
创建新的、独立的状态机。如果不能创建状态机则返回NULL（由于内存不足）。参数f是分配器函数；Lua通过该函数为状态机执行全部的内存分配操作。第二参数ud是个不透明的指针，在每次调用中Lua将其传入分配器。
[-0, +1, m]
void lua_newtable (lua_State *L);
创建新的空表并将其压栈。它等价于lua_createtable(L, 0, 0)。
[-0, +1, m]
lua_State *lua_newthread (lua_State *L);
创建新线程，将其压栈，并返回指向的指针，它表示该新线程。本函数返回的新状态机与初始状态机共享所有全局对象（例如表），但具有独立的执行栈。
没有关闭或销毁线程的显式函数。像任何Lua对象一样，线程受垃圾收集的支配。
[-0, +1, m]
void *lua_newuserdata (lua_State *L, size_t size);
本函数分配新的给定尺寸的内存块，以块地址的方式将完整的用户数据压栈，并返回该地址。
Lua中的用户数据表示C值。完整的用户数据表示一块内存。它是个对象（如同表）：你必须创建它，它可以有自己的元表，而且当被收集时能被检测到。完整的用户数据只等于自己（依照原始的相等比较）。
当Lua用gc元方法收集完整的用户数据时，Lua调用该元方法并把用户数据标记为完成的。当该用户数据再次被收集时，Lua释放其对应的内存。
[-1, +(2|0), e]
int lua_next (lua_State *L, int index);
从栈中弹出一个键，并从给定的索引处的表中弹出一个键-值对（给定键的“下一”对）。如果表中没有更多的元素，则返回0（且不会压栈任何东西）。
典型的遍历看起来像这样：
/* 表在栈中的索引‘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);
}
当遍历表时，不要直接对键调用，除非你知道键确实是字符串。回忆一下，会改变给定所引处的值；这会干扰下一次调用。
typedef double lua_Number;
Lua中的数字类型。缺省是双精度浮点数，但是能在luaconf.h中改变。
通过配置文件能改变Lua去操作其他的类型用作数字（例如单精度浮点数或长整型）。
[-0, +0, -]
size_t lua_objlen (lua_State *L, int index);
返回给定的认可的索引处的值的“长度”：对于字符串，这是其长度；对于表，这是取长操作符（‘#’）的结果；对于用户数据，这是为其分配的内存块的尺寸；对于其他类型是0。
[-(nargs + 1), +(nresults|1), -]
int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
在保护模式中调用函数。
nargs和nresults同中的有相同的含义。如果调用期间没有错误，的行为完全类似。然而，如果存在任何错误，捕捉它，将单个值压栈（错误消息），并返回错误代码。同一样，总是从栈中移除函数及其参数。
如果errfunc是0，则在栈上返回的错误消息就是原始的错误消息。否则,errfunc就是错误处理器函数（error handler function）的栈索引。（当前实现中，该索引不能是伪索引。）在发生运行时错误时，该函数将用错误消息调用，而且其返回值将变成栈上被返回的消息。
典型地，错误处理器函数用于向错误消息中增加更多调试信息，例如栈回溯。这种信息不能在返回后搜集，因为那时候栈释放。
成功时函数返回0，或者页面的错误代码之一（在lua.h中定义）：
[-n, +0, -]
void lua_pop (lua_State *L, int n);
从栈中弹出n个元素。
[-0, +1, -]
void lua_pushboolean (lua_State *L, int b);
把值b作为布尔值压栈。
[-n, +1, m]
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
把新的C闭包压栈。
当C函数被创建时，它可以把一些值与自己关联，这样就创建了C闭包（见）；接下来无论何时它被调用，这些值对该函数都是可访问的。要将值与C函数关联，首先这些值应当被压栈（当有多个值时第一个值首先压栈）。然后用参数n调用来创建C函数并将其压栈，n表明应当把多少值关联到该函数。也会将这些值从栈中弹出。
[-0, +1, m]
void lua_pushcfunction (lua_State *L, lua_CFunction f);
将C函数压栈。本函数接收一个指向C函数的指针并把一个function类型的Lua值压栈，当这种类型的函数被调用时，会调用相应的C函数。
任何要在Lua中注册的函数必须遵循正确的协议，以接收其参数并返回其结果（见）。
lua_pushcfunction被定义为宏：
#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
[-0, +1, m]
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
将格式化的字符串压栈并返回指向它的指针。它与C函数sprintf类似，但也有一些重要的区别：
%%' （在字符串中插入一个'%'），'%s' （插入一个以0结尾的字符串，没有尺寸限制），'%f' （插入一个），'%p' （插入一个指针作为十六进制数），'%d' （插入一个int），以及'%c' （插入一个int作为字符）。
[-0, +1, -]
void lua_pushinteger (lua_State *L, lua_Integer n);
将一个值为n的数字压栈。
[-0, +1, -]
void lua_pushlightuserdata (lua_State *L, void *p);
将轻型用户数据压栈。
在Lua中用户数据表示C值。轻型用户数据表示一个指针。它是个值（就像数字）：你不用创建它，它没有单独的元表，而且它不会被回收（如同从不被创建）。带有相同的C地址的轻型用户数据相等。
[-0, +1, m]
void lua_pushliteral (lua_State *L, const char *s);
本宏等价于，但是只能当s是字面字符串时使用。在这些情况下，它自动地提供字符串长度。
[-0, +1, m]
void lua_pushlstring (lua_State *L, const char *s, size_t len);
将s指向的尺寸为len的字符串压栈。Lua制造（或重用）给定字符串的内部拷贝，所以函数返回后s的内存立刻可被释放或重用。字符串可含有内嵌的0。
[-0, +1, -]
void lua_pushnil (lua_State *L);
将nil值压栈。
[-0, +1, -]
void lua_pushnumber (lua_State *L, lua_Number n);
将值为n的数字压栈。
[-0, +1, m]
void lua_pushstring (lua_State *L, const char *s);
将s指向的以0结尾的字符串压栈。Lua制造（或重用）给定字符串的内部拷贝，所以函数返回后s的内存立刻可被释放或重用。字符串不可含有内嵌的0；假定它在首个0处结束。
[-0, +1, -]
int lua_pushthread (lua_State *L);
将L表示的线程压栈。如果该线程是其状态机的主线程则返回1。
[-0, +1, -]
void lua_pushvalue (lua_State *L, int index);
将给定的有效索引处的元素的拷贝压栈。
[-0, +1, m]
const char *lua_pushvfstring (lua_State *L,
const char *fmt,
va_list argp);
等价于，除了它接收一个va_list而不是可变数量的参数。
[-0, +0, -]
int lua_rawequal (lua_State *L, int index1, int index2);
如果认可的索引index1和index2处的两个值原生相等（即不调用元方法）则返回1。否则返回0。如果任何索引不合法也返回0。
[-1, +1, -]
void lua_rawget (lua_State *L, int index);
类似，但是执行一次原生访问（也就是不用元方法）。
[-0, +1, -]
void lua_rawgeti (lua_State *L, int index, int n);
降值t[n]压栈，其中t是给定的有效索引处的值。访问是原生的；即不会调用元方法。
[-2, +0, m]
void lua_rawset (lua_State *L, int index);
类似，但是执行一次原生赋值（也就是不用元方法）。
[-1, +0, m]
void lua_rawseti (lua_State *L, int index, int n);
执行t[n] = v的等价操作，其中t是给定的有效索引处的值，v是栈顶的值。
本函数将值出栈。赋值是原生的；即不调用元方法。
typedef const char * (*lua_Reader) (lua_State *L,
void *data,
size_t *size);
被使用的读取器函数。每次需要单元的另一段时，沿着它的data参数调用读取器。读取器必须返回一个的内存块的指针，其中含有单元的新代码段，并且设置size为块尺寸。块必须一直存在直到再次调用读取器函数。读取器必须返回NULL来指示单元结束。读取器函数可能返回大于0的任何尺寸的代码段。
[-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))
[-1, +0, -]
void lua_remove (lua_State *L, int index);
移除给定的有效索引处的元素，并将该索引上面的元素下移来填充空隙。不能用伪索引调用，因为伪索引不是真实的栈位置。
[-1, +0, -]
void lua_replace (lua_State *L, int index);
将栈顶元素移动到给定的索引中（并弹出它），不会移动任何元素（因此替换给定位置的值）。
[-?, +?, -]
int lua_resume (lua_State *L, int narg);
启动和恢复给定线程中的一个协程。
要启动一个协程，首先创建线程（见）；接着将主函数以及任何参数压到它的栈中；然后用narg指定参数个数来调用。当协程挂起或运行完成时该调用返回。当它返回时，栈中含有传入的所有值，或主体函数返回的所有值。如果协程yield则返回，如果运行无误结束则返回0，或者在发生错误时返回错误代码（见）。发生错误时，栈未被释放，所以可对它使用调试API。错误消息位于栈顶。要重新启动协程，你只需把要从yield传出的结果放到栈上，然后调用。
[-0, +0, -]
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
把给定状态机的分配器函数换成带用户数据ud的f。
[-1, +0, -]
int lua_setfenv (lua_State *L, int index);
从栈中弹出一个表并把它设为给定索引处的值的新环境。如果给定索引处的值既不是函数又不是线程也不是用户数据，返回0。否则返回1。
[-1, +0, e]
void lua_setfield (lua_State *L, int index, const char *k);
执行t[k] = v的等价操作，其中t是给定的有效索引处的值，v是栈顶的值。
本函数从栈中弹出值。同Lua中一样，本函数可能触发“newindex”事件的元方法（见）。
[-1, +0, e]
void lua_setglobal (lua_State *L, const char *name);
从栈中弹出一个值并将其设为全局变量name的新值。它被定义为宏：
#define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
[-1, +0, -]
int lua_setmetatable (lua_State *L, int index);
从栈中弹出一个表并将其设为给定的认可的索引处的值得新元表。
[-2, +0, e]
void lua_settable (lua_State *L, int index);
执行t[k] = v的等价操作，其中t是给定的有效索引处的值，v是栈顶的值，k正好是栈顶下面的值。
本函数将键和值都弹出栈。同Lua中一样，本函数可能触发“newindex”事件的元方法（见）。
[-?, +?, -]
void lua_settop (lua_State *L, int index);
接受任何认可的索引或0，并将栈顶设为该值。如果新栈顶比旧的大，则新元素用nil填充。如果index 是0，则移除所有栈元素。
typedef struct lua_State lua_State;
保持一个Lua解释器的完整状态机的不透明结构。Lua库是完全可重入的：没有全局变量。关于状态机的所有信息保持在该结构中。
一个指向该状态机的指针必须作为第一参数传入库中的所有函数，除了，它从头创建Lua状态机。
[-0, +0, -]
int lua_status (lua_State *L);
返回线程L的状态。
对于正常的线程状态可为0，如果线程发生错误而结束则为错误代码，或者如果线程挂起则为。
[-0, +0, -]
int lua_toboolean (lua_State *L, int index);
把给定的认可的索引处的Lua值转换为C布尔值（0或1）。同Lua中的所有测试一样，对于任何不同于false和nil的Lua值，返回1；否则返回0。当用不合法的索引调用时也返回0。（如果你要只接受真正的布尔值，使用测试值的类型。）
[-0, +0, -]
lua_CFunction lua_tocfunction (lua_State *L, int index);
把给定的认可的索引处的值转换为C函数。那个值必须是个C函数，否则返回NULL。
[-0, +0, -]
lua_Integer lua_tointeger (lua_State *L, int index);
把给定的认可的索引处的Lua值转换为带符号整数类型。该Lua值必须是数字或可转换为数字的字符串（见）；否则返回0。
如果该数字不是整数，它会被以某种未指定的方式被截断。
[-0, +0, m]
const char *lua_tolstring (lua_State *L, int index, size_t *len);
把给定的认可的索引处的Lua值转换为C字符串。如果len不是NULL，也会用字符串长度设置*len。该Lua值必须是字符串或数字；否则，本函数返回NULL。如果该值是数字，则也会改变栈中的实际值为字符串。（当在表遍历期间被用于键时，这个改变会干扰。）
返回个指向Lua状态机内部的字符串的完全调整的指针。这个字符串总是在其最后字符后有个0（‘\0’）（同C中一样），但是其体内可含有其他的0。因为Lua具有垃圾收集，所以无法担保返回的指针在相应的值从栈中移除后仍然有效。
[-0, +0, -]
lua_Number lua_tonumber (lua_State *L, int index);
把给定的认可的索引处的Lua值转换为C类型（见）。该Lua值必须是数字或可转为数字的字符串（见）；否则返回0。
[-0, +0, -]
const void *lua_topointer (lua_State *L, int index);
把给定的认可的索引处的值转换为普通的C指针（void*）。该值可为用户数据、表、线程或函数；否则返回NULL。不同的对象将给出不同的指针。没有方法可以把指针转回其原始值。
典型地，本函数只用于调试信息。
[-0, +0, m]
const char *lua_tostring (lua_State *L, int index);
等价于len等于NULL时的。
[-0, +0, -]
lua_State *lua_tothread (lua_State *L, int index);
把给定的认可的索引处的值转换为Lua线程（用lua_State*表示）。该值必须为线程；否则，本函数返回NULL。
[-0, +0, -]
void *lua_touserdata (lua_State *L, int index);
如果给定的认可的索引处的值是完整的用户数据，则返回其块地址。如果是轻型用户数据，返回其指针。否则返回NULL。
[-0, +0, -]
int lua_type (lua_State *L, int index);
返回给定的认可的索引处的值的类型，或者对不合法的索引返回LUA_TNONE（即指向“空”栈位置的索引）。返回的类型在lua.h中定义，被编码为下面的常量：
LUA_TNIL、LUA_TNUMBER、LUA_TBOOLEAN、LUA_TSTRING、LUA_TTABLE、LUA_TFUNCTION、LUA_TUSERDATA、LUA_TTHREAD和LUA_TLIGHTUSERDATA。
[-0, +0, -]
const char *lua_typename (lua_State *L, int tp);
返回由值tp编码的类型名，tp必须是的返回值的其中一个。
typedef int (*lua_Writer) (lua_State *L,
const void* p,
size_t sz,
void* ud);
由使用的记录器函数的类型。沿着要被写入的缓冲区（p）调用本函数，同时传入缓冲区尺寸（sz）和提供给的data参数。每次调用会产生单元的另一段代码。
记录器返回错误代码：0表示没错误；任何其他值表示错误并阻止再次调用记录器。
[-?, +?, -]
void lua_xmove (lua_State *from, lua_State *to, int n);
在同一个全局状态机的不同线程间交换值。
本函数从栈from中弹出n个值并把它们压入栈to中。
[-?, +?, -]
int lua_yield (lua_State *L, int nresults);
中断一个协程。
本函数只应当作为C函数的返回表达式调用，如下：
return lua_yield (L, nresults);
当C函数以那种方式调用时，当前运行的协程挂起，并且启动该协程的调用返回。参数nresults是作为结果传给的来自栈中的值的数量。