?
This document uses PHP Chinese website manual Release
本節(jié)描述 Lua 的 C API，即主機程序可用于與 Lua 通信的一組 C 函數。所有的 API 函數以及相關的類型和常量都在頭文件中聲明lua.h。
即使我們使用術語“功能”，API中的任何工具都可以作為宏提供。除非另有說明，否則所有這些宏都只使用它們的每個參數一次（除了第一個參數，它總是一個Lua狀態(tài)），所以不會產生任何隱藏的副作用。
和大多數C庫一樣，Lua API函數也不檢查參數的有效性或一致性。但是，您可以通過使用LUA_USE_APICHECK定義的宏編譯Lua來更改此行為。
Lua庫是完全可重入的：它沒有全局變量。它將所需的所有信息保存在一個稱為Lua狀態(tài)的動態(tài)結構中。
每個Lua狀態(tài)都有一個或多個線程，這些線程對應于獨立的合作執(zhí)行線。類型lua_State（盡管它的名稱）是指一個線程。（間接地，通過線程，它也指與線程關聯(lián)的Lua狀態(tài)。）
一個指向線程的指針必須作為第一個參數傳遞給庫中的每個函數，除了lua_newstate從頭創(chuàng)建一個Lua狀態(tài)并返回一個指向新狀態(tài)主線程的指針。
4.1 – The Stack
Lua使用虛擬堆棧向C傳遞值和從C傳遞值。此堆棧中的每個元素表示一個Lua值（零，數字，字符串等）。API中的函數可以通過它們接收的Lua狀態(tài)參數訪問此堆棧。
每當Lua調用C時，被調用的函數都會得到一個新的堆棧，它獨立于先前的堆棧和仍然處于活動狀態(tài)的C函數堆棧。此堆棧最初包含C函數的任何參數，并且它是C函數可以存儲臨時Lua值的位置，并且必須將其結果返回給調用方（請參閱參考資料lua_CFunction）。
為方便起見，API中的大多數查詢操作都不遵循嚴格的堆棧規(guī)則。相反，他們可以使用索引引用堆棧中的任何元素：正數索引表示絕對堆棧位置（從1開始）; 負索引表示相對于堆棧頂部的偏移量。更具體地說，如果堆棧有n個元素，則索引1表示第一個元素（即，先推入堆棧的元素），而索引n表示最后一個元素; 索引-1也表示最后一個元素（即頂部的元素）和索引-n表示第一個元素。
4.2 – Stack Size
當您與 Lua API 交互時，您有責任確保一致性。特別是，你負責控制堆棧溢出。您可以使用該函數lua_checkstack確保堆棧有足夠的空間來推送新元素。
每當 Lua 調用 C 時，它都會確保堆棧至少有LUA_MINSTACK額外的插槽空間。LUA_MINSTACK被定義為20，所以通常你不必擔心堆棧空間，除非你的代碼有循環(huán)將元素推入堆棧。
當你調用沒有固定數量結果的Lua函數時（參見lua_call參考資料），Lua確保堆棧為所有結果提供了足夠的空間，但它不能確保有任何額外的空間。所以，在這樣的通話之后，在推動任何東西之前，你應該使用lua_checkstack。
4.3 – Valid and Acceptable Indices
接收堆棧索引的API中的任何函數只能使用有效的索引或可接受的索引。
有效的索引是指存儲可修改的Lua值的位置的索引。它包含1和堆棧頂部（1 ≤ abs(index) ≤ top）之間的堆棧索引以及偽代碼，它們代表C代碼可訪問但不在堆棧中的某些位置。偽索引用于訪問注冊表（請參閱第4.5節(jié)）和C函數的高價值（請參閱第4.4節(jié)）。
函數不需要特定的可變位置，但只有一個值（例如查詢函數），可以用可接受的索引來調用。一個可接受的索引可以是任何有效的索引，但它也可以是在為該堆棧分配的空間內的堆棧頂部之后的任何正數索引，即，索引直至堆棧大小。（請注意，0永遠不是可接受的索引。）除非另有說明，API中的函數可以使用可接受的索引。
查詢堆棧時，可接受的索引用于避免對堆棧頂部進行額外的測試。例如，一個C函數可以查詢它的第三個參數，而不需要先檢查是否有第三個參數，也就是說，不需要檢查3是否是一個有效的索引。
對于可以用可接受索引調用的函數，任何無效索引都被視為包含虛擬類型的值LUA_TNONE，其行為類似于零值。
4.4 – C Closures
當創(chuàng)建一個C函數時，可以將一些值與它關聯(lián)，從而創(chuàng)建一個C閉包（參見lua_pushcclosure）; 這些值被稱為upvalues，并且只要被調用就可以被該函數訪問。
無論何時調用C函數，它的upvalues都位于特定的偽索引處。這些偽指數是由宏產生的lua_upvalueindex。與函數關聯(lián)的第一個upvalue位于索引處lua_upvalueindex(1)，依此類推。任何訪問，其中n大于當前函數的upvalues數（但不大于256，這是一個加上閉包中upvalues的最大數），產生一個可接受但無效的索引。lua_upvalueindex(n)
4.5 – Registry
Lua提供了一個注冊表，這是一個預定義的表，任何C代碼都可以使用它來存儲它需要存儲的任何Lua值。注冊表表格始終位于偽索引處LUA_REGISTRYINDEX。任何C庫都可以將數據存儲到此表中，但必須注意選擇與其他庫所使用的不同的密鑰，以避免沖突。通常，您應該使用包含您的庫名稱的字符串或代碼中具有C對象地址的輕型用戶數據或由您的代碼創(chuàng)建的任何Lua對象作為關鍵字。與變量名一樣，以下劃線開頭的字符串鍵后跟大寫字母保留給Lua。
注冊表中的整數鍵由引用機制（請參閱luaL_ref）和一些預定義的值使用。因此，整數鍵不能用于其他目的。
當你創(chuàng)建一個新的Lua狀態(tài)時，它的注冊表帶有一些預定義的值。這些預定義值使用定義為常量的整數鍵索引lua.h。定義了以下常量：
LUA_RIDX_MAINTHREAD： 在這個索引處，注冊表具有狀態(tài)的主線程。（主線程是與狀態(tài)一起創(chuàng)建的主線程。）LUA_RIDX_GLOBALS： 在這個索引處，注冊管理機構擁有全球環(huán)境。
4.6 – Error Handling in C
在內部，Lua 使用C longjmp工具來處理錯誤。（如果將它編譯為C ++，Lua將使用異常; LUAI_THROW有關詳細信息，請在源代碼中進行搜索。）當Lua面臨任何錯誤（例如內存分配錯誤或類型錯誤）時，會引發(fā)錯誤; 也就是說，它跳遠了。一個受保護的環(huán)境使用setjmp設置一個恢復點; 任何錯誤都會跳轉到最近的活動恢復點。
在 C 函數內部，您可以通過調用來引發(fā)錯誤lua_error。
API中的大多數函數都可能引發(fā)錯誤，例如由于內存分配錯誤。每個函數的文檔都指出它是否會引發(fā)錯誤。
如果在任何受保護的環(huán)境之外發(fā)生錯誤，Lua會調用panic函數（請參閱lua_atpanic）然后調用abort，從而退出主機應用程序。你的恐慌功能可以通過永不返回來避免這種退出（例如，在Lua之外跳轉到自己的恢復點）。
正如其名稱所暗示的，恐慌功能是一種最后的手段。程序應該避免它。一般來說，當Lua調用一個Lua狀態(tài)的C函數時，它可以在Lua狀態(tài)下做任何事情，因為它應該已經被保護了。但是，當C代碼運行在其他Lua狀態(tài)（例如，函數的Lua參數，存儲在注冊表中的Lua狀態(tài)或結果lua_newthread）時，它應該只在不會引發(fā)錯誤的API調用中使用它們。
恐慌函數就像是一個消息處理程序一樣運行（請參閱第2.3節(jié)）; 特別是，錯誤對象位于堆棧的頂部。但是，堆棧空間不能保證。要推動堆棧中的任何內容，恐慌功能必須首先檢查可用空間（請參閱第4.2節(jié)）。
4.7 – Handling Yields in C
在內部，Lua 使用C longjmp工具來產生協(xié)程。因此，如果一個C函數foo調用一個API函數并且這個API函數產生（通過調用另一個產生的函數直接或間接產生），Lua不能再返回foo，因為longjmp它從C棧中移除了它的框架。
為了避免這樣的問題，提出的Lua每當它試圖跨越API調用來產生，除了三個功能錯誤：lua_yieldk，lua_callk，和lua_pcallk。所有這些函數都會收到一個繼續(xù)函數（作為一個名為參數k）以在yield之后繼續(xù)執(zhí)行。
我們需要設置一些術語來解釋延續(xù)。我們有一個從 Lua 調用的 C 函數，我們將其稱為原始函數。這個原始函數然后調用 C API 中的三個函數之一，我們將調用被調用函數，然后產生當前線程。（這可能發(fā)生在被調用函數時lua_yieldk，或者當被調用函數是lua_callk或者lua_pcallk并且由它們調用的函數產生時）。
假設正在運行的線程在執(zhí)行被調用函數時產生。線程恢復后，它最終將完成運行被調用函數。但是，被調用函數無法返回到原始函數，因為C堆棧中的框架被yield損壞了。相反，Lua調用一個繼續(xù)函數，它被作為被調用函數的參數給出。顧名思義，繼續(xù)功能應該繼續(xù)原有功能的任務。
作為說明，請考慮以下功能：
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?，F在，我們必須告訴Lua，k如果被執(zhí)行的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);}請注意對延續(xù)的外部顯式調用：只有在需要時，Lua才會調用延續(xù)，也就是說，如果發(fā)生錯誤或者在yield之后恢復。如果被調用的函數正常返回而沒有屈服，lua_pcallk（和lua_callk）也將正常返回。（當然，不是在這種情況下調用延續(xù)，而是直接在原始函數內執(zhí)行等效工作。）
除了Lua狀態(tài)之外，continuation函數還有兩個其他參數：調用的最終狀態(tài)和ctx最初傳遞給的上下文值（）lua_pcallk。（Lua沒有使用這個上下文值，它只是將原始函數中的值傳遞給繼續(xù)函數）。因為lua_pcallk，狀態(tài)與返回的值相同lua_pcallk，只不過它是LUA_YIELD在yield之后執(zhí)行的（而不是的LUA_OK）。對于lua_yieldk和lua_callk，LUA_YIELD當Lua稱為延續(xù)時，狀態(tài)總是如此。（對于這兩個函數，如果發(fā)生錯誤，Lua將不會調用延續(xù)，因為它們不會處理錯誤。）類似地，使用時lua_callk，您應該LUA_OK以狀態(tài)的形式調用延續(xù)函數。（對于lua_yieldk，直接調用繼續(xù)函數沒有太大意義，因為lua_yieldk通常不會返回。）
Lua 將延續(xù)功能看作是原始功能。continuation函數從原始函數接收相同的Lua堆棧，處于與被調用函數返回時相同的狀態(tài)。（例如，lua_callk函數及其參數從堆棧中移除并由調用的結果替換后）。它也具有相同的upvalues。無論它返回的是由Lua處理，就好像它是原始函數的返回一樣。
4.8 – Functions and Types-o, +p, x
這里我們按字母順序列出C API中的所有函數和類型。每個功能都有一個像這樣的指示器：
第一個字段o是函數從堆棧中彈出多少個元素。第二個字段p是函數將多少元素壓入堆棧。（任何函數在彈出其參數后總是推送其結果。）表單中的字段x|y表示該函數可以推送（或彈出）x或y元素，具體取決于具體情況; 一個詢問標記“ ?'意味著我們無法通過僅查看其參數（例如，它們可能取決于棧上的內容）來知道該函數彈出/推動多少個元素。第三個字段x告訴函數是否會引發(fā)錯誤：' -'表示函數不會引發(fā)任何錯誤; ' m'表示該函數可能引發(fā)運行元方法的內存__gc不足錯誤和錯誤; “e'表示該函數可能引發(fā)任何錯誤（它可以直接或通過元方法運行任意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 狀態(tài)使用的內存分配函數的類型。分配器函數必須提供類似的功能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是創(chuàng)建該類型的新對象。何時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);
對堆棧頂部的兩個值（或一個，如果是否定）執(zhí)行算術運算或按位運算，頂部的值為第二個操作數，彈出這些值并推送操作結果。該函數遵循相應的Lua運算符的語義（也就是說，它可能調用metamethods）。
值op必須是以下常量之一：
LUA_OPADD： 執(zhí)行addition（+）LUA_OPSUB： 執(zhí)行減法（-）LUA_OPMUL： 執(zhí)行乘法（*）LUA_OPDIV： 執(zhí)行浮動除法（/）LUA_OPIDIV： 執(zhí)行地板劃分（//）LUA_OPMOD： 執(zhí)行modulo（%）LUA_OPPOW： 執(zhí)行冪（^）LUA_OPUNM： 執(zhí)行數學否定（一元-）LUA_OPBNOT： 按位執(zhí)行NOT（~）LUA_OPBAND： 執(zhí)行按位AND（&）LUA_OPBOR： 執(zhí)行按位OR（|）LUA_OPBXOR： 執(zhí)行按位異或（~）LUA_OPSHL： 執(zhí)行左移（<<）LUA_OPSHR： 執(zhí)行右移（>>）
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);
調用一個函數。
要調用函數，您必須使用以下協(xié)議：首先，要調用的函數被壓入堆棧; 然后，函數的參數按直接順序推入; 也就是說，第一個參數是先推。最后你打電話lua_call; nargs是您推入堆棧的參數的數量。函數被調用時，所有參數和函數值都從堆棧彈出。當函數返回時，函數結果被壓入堆棧。結果的數量調整為nresults，除非nresults是LUA_MULTRET。在這種情況下，該功能的所有結果都會被推送; Lua注意返回值適合堆棧空間，但它不能確保堆棧中有任何額外的空間。函數結果按直接順序壓入堆棧（第一個結果先被壓入），這樣在調用后最后的結果位于堆棧的頂部。
被調用函數中的任何錯誤都向上傳播（使用a longjmp）。
以下示例顯示主機程序如何執(zhí)行與此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函數必須使用以下協(xié)議，該協(xié)議定義了傳遞參數和結果的方式：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狀態(tài)下的所有對象（調用相應的垃圾收集元方法，如果有的話）并釋放此狀態(tài)使用的所有動態(tài)內存。在多個平臺上，您可能不需要調用此函數，因為所有資源在主機程序結束時自然釋放。另一方面，創(chuàng)建多個狀態(tài)的長時間運行的程序（如守護程序或Web服務器）可能需要在不需要時立即關閉狀態(tài)。
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_OPLT： 比較小于（<）LUA_OPLE： 比較少或相等（<=）
lua_concat-n, +1, e
void lua_concat (lua_State *L, int n);
連接n堆棧頂部的值，彈出它們，并將結果保留在頂部。如果n是1，結果是堆棧中的單個值（即該函數不執(zhí)行任何操作）; 如果n是0，結果是空字符串。按照Lua的通常語義執(zhí)行連接（請參閱第3.4.6節(jié)）。
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);
創(chuàng)建一個新的空表并將其壓入堆棧。參數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為真，則二進制表示可能不包含有關該函數的所有調試信息，以節(jié)省空間。
返回的值是上次調用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);
控制垃圾收集器。
根據參數的值，該功能執(zhí)行幾項任務what：
LUA_GCSTOP：停止垃圾收集器。LUA_GCRESTART：重新啟動垃圾收集器。LUA_GCCOLLECT：執(zhí)行完整的垃圾收集循環(huán)。LUA_GCCOUNT：返回Lua使用的當前內存量（以KB為單位）。LUA_GCCOUNTB：將由Lua使用的當前內存字節(jié)數除以1024的余數。LUA_GCSTEP：執(zhí)行垃圾收集的增量步驟。LUA_GCSETPAUSE：設置data為收集器暫停的新值（請參閱§2.5）并返回暫停的前一個值。LUA_GCSETSTEPMUL：設置data為收集器步驟乘數的新值（見§2.5）并返回步驟乘數的前一個值。LUA_GCISRUNNING：返回一個布爾值，告訴收集器是否正在運行（即不停止）。
有關這些選項的更多詳細信息，請參閱collectgarbage。
lua_getallocf-0, +0, –
lua_Alloc lua_getallocf (lua_State *L, void **ud);
返回給定狀態(tài)的內存分配函數。如果ud不是NULL，Lua將存儲在*ud設置了內存分配器函數時給出的不透明指針上。
lua_getfield-0, +1, e
int lua_getfield (lua_State *L, int index, const char *k);
將值推到堆棧上t[k]，其中t是給定索引處的值。和Lua一樣，這個函數可能觸發(fā)“索引”事件的元方法（見§2.4）。
返回推送值的類型。
lua_getextraspace-0, +0, –
void *lua_getextraspace (lua_State *L);
返回指向與給定的Lua狀態(tài)相關的原始內存區(qū)域的指針。應用程序可以將此區(qū)域用于任何目的; Lua沒有使用它。
每個新線程都使用主線程區(qū)域的副本初始化該區(qū)域。
默認情況下，該區(qū)域的指針大小為void，但您可以使用該區(qū)域的不同大小重新編譯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一樣，這個函數可能觸發(fā)“索引”事件的元方法（見§2.4）。
返回推送值的類型。
lua_getmetatable-0, +(0|1), –
int lua_getmetatable (lua_State *L, int index);
如果給定索引處的值具有metatable，則該函數會將metatable推送到堆棧并返回1.否則，該函數將返回0，并且不會在堆棧上執(zhí)行任何操作。
lua_gettable-1, +1, e
int lua_gettable (lua_State *L, int index);
將值推入堆棧t[k]，其中t是給定索引k處的值，并且是堆棧頂部的值。
該函數從堆棧彈出鍵，將結果值推到原位。和Lua一樣，這個函數可能觸發(fā)“索引”事件的元方法（見§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);
將與給定索引處的完整用戶數據關聯(lián)的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;LUA_ERRSYNTAX: syntax error during precompilation;LUA_ERRMEM: memory allocation (out-of-memory) error;LUA_ERRGCMM: error while running a__gcmetamethod. (This error has no relation with the chunk being loaded. It is generated by the garbage collector.)
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_ERRRUN: a runtime error.LUA_ERRMEM: memory allocation error. For such errors, Lua does not call the message handler.LUA_ERRERR: error while running the message handler.LUA_ERRGCMM: error while running a__gcmetamethod. For such errors, Lua does not call the message handler (as this kind of error typically has no relation with the function being called).
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).
The conversion specifiers are quite restricted. There are no flags, widths, or precisions. The conversion specifiers can only be '
%%' (inserts the character '%'), '%s' (inserts a zero-terminated string, with no size restrictions), '%f' (inserts alua_Number), '%I' (inserts alua_Integer), '%p' (inserts a pointer as a hexadecimal numeral), '%d' (inserts anint), '%c' (inserts anintas a one-byte character), and '%U' (inserts along intas a UTF-8 byte sequence).
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*。它是一個值（像一個數字）：你不創(chuàng)建它，它沒有單獨的metatable，它不被收集（因為它從來沒有被創(chuàng)建）。輕的用戶數據等于具有相同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創(chuàng)建（或重新使用）給定字符串的內部副本，因此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創(chuàng)建（或重新使用）給定字符串的內部副本，因此s可以在函數返回后立即釋放或重用內存。
返回一個指向字符串內部副本的指針。
如果s是NULL，推零和返回NULL。
lua_pushthread-0, +1, –
int lua_pushthread (lua_State *L);
將由代表的線程L推入堆棧。如果此線程是其狀態(tài)的主線程，則返回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);
在給定的線程中啟動并恢復一個協(xié)程L。
要啟動一個協(xié)程，你可以將線程堆棧的主函數加上任何參數; 然后你打電話lua_resume，nargs作為參數的數量。這個調用在協(xié)程暫?；蚪Y束執(zhí)行時返回。當它返回時，堆棧包含傳遞給的lua_yield所有值，或者正文函數返回的所有值。lua_resume返回LUA_YIELD如果協(xié)程產率，LUA_OK如果所述協(xié)程完成它的執(zhí)行沒有錯誤，或在錯誤的情況下的錯誤代碼（參見lua_pcall）。
如果發(fā)生錯誤，堆棧不會解開，因此您可以使用調試 API 覆蓋它。錯誤對象位于堆棧的頂部。
要恢復一個協(xié)程，你可以從最后一個結果中刪除任何結果lua_yield，只將其作為結果傳入的值放在棧上yield，然后調用lua_resume。
該參數from表示正在恢復的協(xié)程L。如果沒有這樣的協(xié)程，這個參數可以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用用戶數據改變給定狀態(tài)的分配器功能ud。
lua_setfield-1, +0, e
void lua_setfield (lua_State *L, int index, const char *k);
是否為等效的t[k] = v，在那里t是給定索引處的值并且v是在堆棧的頂部的值。
該函數從堆棧中彈出值。和Lua一樣，這個函數可能觸發(fā)“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一樣，這個函數可能觸發(fā)“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一樣，這個函數可能觸發(fā)“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);
從堆棧中彈出一個值，并將其設置為與給定索引處的完整用戶數據關聯(lián)的新值。
lua_State
typedef struct lua_State lua_State;
一個不透明的結構，指向一個線程并間接（通過線程）到一個 Lua 解釋器的整個狀態(tài)。Lua庫是完全可重入的：它沒有全局變量。所有關于國家的信息都可以通過這個結構來訪問。
一個指向這個結構的指針必須作為第一個參數傳遞給庫中的每個函數，除了lua_newstate從頭創(chuàng)建一個Lua狀態(tài)。
lua_status-0, +0, –
int lua_status (lua_State *L);
返回線程的狀態(tài)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.
您只能在具有狀態(tài)的線程中調用函數LUA_OK。您可以恢復具有狀態(tài)的線程LUA_OK（啟動新協(xié)程）或LUA_YIELD（恢復協(xié)程）。
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狀態(tài)內的字符串的指針。該字符串\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節(jié)）; 否則，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節(jié)）。
lua_version-0, +0, –
const lua_Number *lua_version (lua_State *L);
返回存儲在Lua核中的版本號（一個C靜態(tài)變量）的地址。當用有效的方式調用時lua_State，返回用于創(chuàng)建該狀態(tài)的版本的地址。呼叫時NULL，返回運行呼叫的版本的地址。
lua_Writer
typedef int (*lua_Writer) (lua_State *L, const void* p, size_t sz, void* ud);
編寫器函數使用的類型lua_dump。每次它產生另一塊時，lua_dump調用寫入器，傳遞緩沖區(qū)以寫入（p），其大?。?code>sz）和data提供給的參數lua_dump。
作者返回一個錯誤代碼：0意味著沒有錯誤; 任何其他值意味著錯誤，并停止lua_dump再次調用作者。
lua_xmove-?, +?, –
void lua_xmove (lua_State *from, lua_State *to, int n);
交換相同狀態(tài)的不同線程之間的值。
該函數n從堆棧中彈出值from，并將它們推入堆棧to。
lua_yield-?, +?, e
int lua_yield (lua_State *L, int nresults);
這個功能相當于lua_yieldk，但沒有延續(xù)（見§4.7）。因此，當線程恢復時，它繼續(xù)調用函數調用的函數lua_yield。
lua_yieldk-?, +?, e
int lua_yieldk (lua_State *L, int nresults, lua_KContext ctx, lua_KFunction k);
產生一個協(xié)程（線程）。
當C函數調用時lua_yieldk，正在運行的協(xié)程暫停執(zhí)行，并且lua_resume啟動該協(xié)程的調用返回。該參數nresults是堆棧中將作為結果傳遞給的值的數量lua_resume。
當協(xié)程再次恢復時，Lua調用給定的繼續(xù)函數k繼續(xù)執(zhí)行產生的C函數（見§4.7）。這個繼續(xù)函數從前一個函數接收相同的堆棧，并將n結果刪除并由傳遞給它的參數替換lua_resume。而且，繼續(xù)函數接收ctx傳遞給的值lua_yieldk。
通常，這個函數不會返回; 當協(xié)程最終恢復時，它繼續(xù)執(zhí)行延續(xù)功能。但是，有一種特殊情況，即在線內或計數掛鉤中調用此函數時（請參閱第4.9節(jié)）。在這種情況下，lua_yieldk應該在沒有延續(xù)的情況下（可能以）的形式被調用，lua_yield并且沒有結果，并且鉤子應該在調用之后立即返回。Lua將屈服，并且當協(xié)程再次恢復時，它將繼續(xù)正常執(zhí)行觸發(fā)鉤子的（Lua）函數。
如果從具有掛起C調用而沒有連續(xù)功能的線程調用該函數，或者該函數是從未在簡歷中運行的線程（例如主線程）調用的，則此函數可能會引發(fā)錯誤。
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：創(chuàng)建函數的塊的名稱。如果source以“@' 開頭，則意味著該函數是在文件名稱跟在”@“ 之后的文件中定義的。如果source以'=' 開頭，則其余內容以依賴于用戶的方式描述源。否則，函數被定義在字符串的source字符串中。short_src：source用于錯誤消息的“可打印”版本。linedefined：函數定義開始的行號。lastlinedefined：函數定義結束的行號。what："Lua"函數是Lua函數的字符串，"C"如果是C函數，"main"則它是塊的主要部分。currentline：給定函數正在執(zhí)行的當前行。當沒有行信息可用時，currentline設置為-1。name：給定函數的合理名稱。因為Lua中的函數是一流的值，所以它們沒有固定的名稱：一些函數可以是多個全局變量的值，而另一些函數可以僅存儲在表字段中。該lua_getinfo函數檢查如何調用該函數以找到合適的名稱。如果找不到名稱，則name設置為NULL。namewhat：解釋這個name領域。的值namewhat可以是"global"，"local"，"method"，"field"，"upvalue"，或""（空字符串），根據功能如何被調用。（當沒有其他選項似乎適用時，Lua使用空字符串。）istailcall：如果通過尾部調用調用此函數調用，則為true。在這種情況下，此級別的調用者不在堆棧中。nups：函數的upvalues數量。nparams：函數的固定參數數量（C函數始終為0）。isvararg：如果函數是可變參數函數，則為true（對于C函數總是如此）。
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;'
S“：填補了領域source，short_src，linedefined，lastlinedefined，和what;'
l'：填寫字段currentline;'
t'：填寫字段istailcall;'
u“：填補了領域nups，nparams以及isvararg;'
f'：將在給定級別運行的函數壓入堆棧;'
L'：將一個表格索引到函數上有效的行號上。（一個有效的行是一個包含相關代碼的行，也就是說，可以放置一個斷點的行，無效的行包含空行和注釋）。如果此選項與選項“f' 一起給出，其表是在功能后推動。
該函數在出錯時返回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函數的參數可見（因為沒有關于哪些變量處于活動狀態(tài)的信息）并且沒有值被壓入堆棧。
NULL當索引大于活動局部變量的數量時，返回（并且不會執(zhí)行任何操作）。
lua_getstack-0, +0, –
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
獲取有關解釋器運行時堆棧的信息。
該函數填充了一個lua_Debug結構的一部分，并標識了在給定級別執(zhí)行的函數的激活記錄。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 沒有特定的順序，因為它們在整個功能中處于活動狀態(tài)。它們以任意順序編號。
lua_Hook
typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
鍵入調試掛鉤函數。
每當調用一個鉤子時，它的ar參數都會將其字段event設置為觸發(fā)鉤子的特定事件。Lua中識別這些事件與以下常量：LUA_HOOKCALL，LUA_HOOKRET，LUA_HOOKTAILCALL，LUA_HOOKLINE，和LUA_HOOKCOUNT。而且，對于線路事件，該字段currentline也被設置。要獲取其他字段的值，ar必須調用該鉤子lua_getinfo。
對于呼叫事件，event可以是LUA_HOOKCALL正常值，或者LUA_HOOKTAILCALL對于尾部呼叫; 在這種情況下，將不會有相應的回報事件。
當Lua運行一個鉤子時，它會禁止其他鉤子調用。因此，如果一個鉤子回叫Lua執(zhí)行一個函數或一個塊，這個執(zhí)行就會發(fā)生，不會有任何鉤子調用。
鉤子函數不能延續(xù)，也就是說，他們不能打電話lua_yieldk，lua_pcallk或lua_callk與非空k。
鉤子函數可以在下列條件下產生：只有計數和行事件可以產生; 到產量，鉤函數必須完成其執(zhí)行主叫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在函數獲取其參數之前輸入新函數之后立即調用。
返回鉤子： 當解釋器從函數返回時被調用。掛鉤在Lua離開函數之前被調用。沒有標準的方法來訪問函數返回的值。
線鉤子： 當解釋器即將開始執(zhí)行新的代碼行時，或者在代碼中跳回時（甚至是同一行），將調用它。（這個事件只發(fā)生在Lua執(zhí)行Lua函數時。）
計數掛鉤： 在解釋器執(zhí)行每條
count指令后調用。（這個事件只發(fā)生在Lua執(zhí)行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。