3.7 Funktionen und Typen Korrektur einreichen Original anzeigen

Aus zeitlichen Gründen ist die Übersetzung dieser Seite bisher leider nicht vollständig.

Hier listen wir alle Funktionen und Typen der C-API in alphabetischer Reihenfolge auf. Jede Funktion hat einen Indikator folgender Art:

Das erste Feld, o, gibt an, wie viele Elemente die Funktion vom Stapelspeicher entfernt. Das zweite Feld, p, gibt an, wie viele Elemente die Funktion auf dem Stapelspeicher ablegt. (Jede Funktion legt ihre Ergebnisse nach dem Entfernen der Argumente ab.) Ein Feld der Form x|y bedeutet, dass die Funktion – je nach Situation – x oder y Elemente ablegen (oder entfernen) kann; ein Fragezeichen '?' bedeutet, dass wir nur durch die Argumente nicht ermitteln können, wie viele Elemente die Funktion entfernt/ablegt (z. B. weil sie vom Inhalt des Stapelspeichers abhängen). Das dritte Feld, x, gibt an, ob die Funktion ggf. Fehler wirft: '-' bedeutet, dass die Funktion niemals Fehler wirft; 'm' bedeutet, dass die Funktion nur bei zu wenig Speicher einen Fehler wirft; 'e' bedeutet, dass die Funktion anderweitige Fehler werfen kann; 'v' bedeutet, dass die Funktion absichtlich einen Fehler wirft.

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

lua_atpanic
lua_CFunction lua_atpanic(lua_State *L, lua_CFunction panicf);

Setzt eine neue Panik-Funktion und liefert die alte zurück.

Falls ein Fehler außerhalb einer geschützten Umgebung auftritt, ruft Lua eine Panik-Funktion auf und anschließend exit(EXIT_FAILURE), um die Host-Anwendung zu verlassen. Ihre Panik-Funktion kann diese Beendigung verhindern, indem sie niemals einen Wert liefert (z. B. über einen long jump).

Die Panik-Funktion kann über den Stack auf die Nachricht des Fehlers zugreifen.

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

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

lua_checkstack
int lua_checkstack(lua_State *L, int extra);

Stellt sicher, dass es mindestens extra freie Plätze auf dem Stapelspeicher gibt. Liefert false, wenn der Stapelspeicher nicht auf diese Größe wachsen kann. Diese Funktion verkleinert den Stapelspeicher niemals; wenn der Stapelspeicher bereits größer als die neue Größe ist, wird dieser unverändert belassen.

lua_close
void lua_close(lua_State *L);

Zerstört alle gegebenen Objekte des Lua-Status (durch Aufruf der entsprechenden Metamethoden der automatischen Speicherbereinigung, sofern verfügbar) und gibt allen von diesem Status belegten dynamischen Speicher frei. Auf den meisten Plattformen müssen Sie diese Funktion wahrscheinlich nicht aufrufen, weil alle Resourcen nach dem Ende des Host-Programms freigegeben werden. Andererseits können langlaufende Programme wie Daemons oder Webserver es erforderlich machen, nicht mehr benötigte Stati freizugeben sobald diese nicht mehr benötigt werden, um zu vermeiden, dass der Speicherverbrauch dieser Programme zu stark anwächst.

lua_concat
void lua_concat(lua_State *L, int n);

Konkateniert die n oberen Werte auf dem Stapelspeicher, entfernt diese und belässt das Ergebnis oben auf dem Stapelspeicher. Wenn n 1 ist, ist das Ergebnis der einfache Wert auf dem Stapelspeicher (d. h. die Funktion macht nichts); falls n 0 ist, ist das Ergebnis die leere Zeichenkette. Die Konkatenierung wird unser Berücksichtigung der gewöhnlichen Semantik von Lua durchgeführt (s. § 2.5.4).

lua_cpcall
int lua_cpcall(lua_State *L, lua_CFunction func, void *ud);

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

Erzeugt eine neue leere Tabelle und legt sie auf dem Stapelspeicher ab. Der Tabelle wird Speicher für narr Feld-Elemente und nrec Nicht-Feld-Elemente reserviert. Diese Reservierung ist nützlich, wenn Sie genau wissen, wie viele Elemente die Tabelle haben wird. Andernfalls können Sie die Funktion lua_newtable verwenden.

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

Liefert einen binären Dump einer Funktion. Diese Funktion erhält eine Lua-Funktion auf dem Stack und liefert binäre Daten, die wenn sie erneut geladen werden, in einer äquivalenten Funktion wie der alten resultieren. Da diese Funktion Teile der Binärdaten erzeugt, ruft lua_dump die Funktion writer (s. lua_Writer) mit den zu schreibenden Daten auf.

Der zurückgelieferte Wert entspricht dem Fehler des letzten Aufrufes an writer; 0 bedeutet keine Fehler.

Diese Funktion entfernt die Lua-Funktion nicht vom Stack.

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

Liefert 1, wenn die zwei Werte an den gültigen Indizes index1 und index2 nach der Semantik des Lua-Operators == gleich sind (d. h. es werden ggf. Metamethoden aufgerufen). Andernfalls wird 0 geliefert. Die Funktion liefert ebenso 0, wenn einer der Indizes nicht gültig ist.

lua_error
int lua_error(lua_State *L);

Erzeugt einen Lua-Fehler. Die Fehlermeldung (welche ein Lua-Wert beliebigen Typs sein kann) muss sich oben auf dem Stapelspeicher befinden. Diese Funktion führt einen "long jump" durch und liefert somit kein Ergebnis (s. luaL_error).

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

Steuert die automatische Speicherbereinigung.

Diese Funktion führt verschiedene Aufgaben aus, entsprechend des Wertes des Parameters what:

  • LUA_GCSTOP: Hält die automatische Speicherbereinigung an.
  • LUA_GCRESTART: Startet die automatische Speicherbereinigung neu.
  • LUA_GCCOLLECT: Führt einen vollständigen Lauf der automatischen Speicherbereinigung durch.
  • LUA_GCCOUNT: Liefert die gegenwärtig von Lua genutzte Menge an Speicher (in KiB).
  • LUA_GCCOUNTB: Liefert den Rest der Division des aktuellen Speicherverbrauchs durch 1024.
  • LUA_GCSTEP: Führt einen inkrementellen Schritt der automatischen Speicherbereinigung aus. Die "Schrittweite" wird in nicht spezifizierter Weise durch data bestimmt (größere Werte bedeuten mehr Schritte). Falls Sie die Schrittweite beeinflussen möchten, müssen Sie den Wert von data experimentell bestimmen. Die Funktion liefert 1, wenn der Schritt einen Lauf beendet hat.
  • LUA_GCSETPAUSE: Setzt data als neuen Wert für die Pause der automatischen Speicherbereinigung (s. §2.10). Die Funktion liefert den vorherigen Wert der Pause.
  • LUA_GCSETSTEPMUL: Setzt data als neuen Wert des Schrittmultiplikators (s. §2.10). Die Funktion liefert den vorherigen Wert des Schrittmultiplikators.
lua_getallocf
lua_Alloc lua_getallocf (lua_State *L, void **ud);

Liefert die Speicherallokationsfuntion des gegebenen Status. Wenn ud nicht NULL ist, speichert Lua den an lua_newstate übergebenen Zeiger unter *ud.

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

Legt die Umgebungstabelle des Wertes am gegebenen Index auf dem Stapelspeicher ab.

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

Legt den Wert t[k] auf dem Stapelspeicher ab, wobei t der Wert am gegebenen gültigen Index ist. Wie in Lua kann diese Funktion eine Metamethode für das "index"-Ereignis auslösen (s. § 2.8).

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

Legt den Wert des globalen name auf dem Stapelspeicher ab. Die Funktion ist als Makro definiert:

#define lua_getglobal(L,s) lua_getfield(L,LUA_GLOBALSINDEX,s)
lua_getmetatable
int lua_getmetatable(lua_State *L, int index);

Legt die Metatabelle des Wertes am gegebenen gültigen Index auf dem Stapelspeicher ab. Falls der Index ungültig ist oder der Wert keine Metatabelle besitzt, liefert die Funktion 0 und legt nichts auf dem Stapelspeicher ab.

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

Legt auf dem Stack den Wert t[k] ab, wobei t der Wert am gegebenen gültigen Index ist und k den Wert auf dem Stack darstellt.

Diese Funktion entfernt den Schlüssel vom Stack. Wie in Lua kann diese Funktion eine Meta-Methode für das "index"-Ereignis aufrufen.

lua_gettop
int lua_gettop(lua_State *L);

Liefert den Index des obersten Elements auf dem Stapelspeicher. Auf Grund der Tatsache, dass Indizes bei 1 beginnen, ist dieses Ergebnis gleich zur Anzahl der Elemente im Stapelspeicher (und somit entspricht 0 einem leeren Stapelspeicher).

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

Moves the top element into the given valid index, shifting up the elements above this index to open space. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.

lua_Integer
typedef ptrdiff_t lua_Integer;

Der Typ, welcher von der Lua-API zur Repräsentation eines ganzzahligen Wertes dient.

Standardmäßig handelt es sich um einen ptrdiff_t, welcher für gewöhnlich der größte vorzeichenbehaftete Ganzzahl-Typ ist, welcher von dem Rechner verarbeitet wird.

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

Returns 1 if the value at the given acceptable index has type boolean, and 0 otherwise.

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

Returns 1 if the value at the given acceptable index is a C function, and 0 otherwise.

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

Returns 1 if the value at the given acceptable index is a function (either C or Lua), and 0 otherwise.

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

Returns 1 if the value at the given acceptable index is a light userdata, and 0 otherwise.

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

Liefert 1, wenn der Wert am gegebenen Index nil ist und ansonsten 0.

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

Returns 1 if the given acceptable index is not valid (that is, it refers to an element outside the current stack), and 0 otherwise.

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

Returns 1 if the given acceptable index is not valid (that is, it refers to an element outside the current stack) or if the value at this index is nil, and 0 otherwise.

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

Liefert 1, wenn der Wert am gegebenen Index eine Zahl oder zu einer solchen konvertierbaren Zeichenkette ist und ansonsten 0

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

Liefert 1, wenn der Wert am gegebenen Index eine Zeichenkette oder Zahl (welche immer zu einer Zeichenkette konvertierbar ist) ist und ansonsten 0.

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

Liefert 1, wenn der Wert am gegebenen Index eine Tabelle ist und ansonsten 0.

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

Liefert 1, wenn der Wert am gegebenen Index ein Thread ist und ansonsten 0.

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

Liefert 1, wenn der Wert am gegebenen Index Benutzerdaten sind und ansonsten 0.

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

Returns 1 if the value at acceptable index index1 is smaller than the value at acceptable index index2, following the semantics of the Lua < operator (that is, may call metamethods). Otherwise returns 0. Also returns 0 if any of the indices is non valid.

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

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

Creates a new, independent state. Returns NULL if cannot create 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. The second argument, ud, is an opaque pointer that Lua simply passes to the allocator in every call.

lua_newtable
void lua_newtable(lua_State *L);

Erzeugt eine neue leere Tabelle und legt sie auf dem Stapelspeicher ab. Dies ist äquivalent zu lua_createtable(L,0,0).

lua_newthread
lua_State *lua_newthread (lua_State *L);

Erstellt einen neuen Thread, legt ihn auf dem Stack ab und liefert einen Zeiger auf einen lua_State, der diesen Thread repräsentiert. Der neue von dieser Funktion gelieferte Zustand teilt alle globalen Objekte mit dem ursprünglichen Zustand (so beispielsweise Tabellen), hat jedoch einen unabhängigen Ausführungsstapel.

Es existiert keine Funktion, um Threads explizit zu beenden oder zu zerstören. Threads werden wie jedes andere Lua-Objekt von der automatischen Speicherbereinigung behandelt.

lua_newuserdata
void *lua_newuserdata (lua_State *L, size_t size);

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

lua_Number
typedef double lua_Number;

lua_objlen
size_t lua_objlen (lua_State *L, int index);

Returns the "length" of the value at the given acceptable index: for strings, this is the string length; for tables, this is the result of the length operator ('#'); for userdata, this is the size of the block of memory allocated for the userdata; for other values, it is 0.

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

lua_pop
void lua_pop(lua_State *L, int n);

Entfernt n Elemente aus dem Stapelspeicher.

lua_pushboolean
void lua_pushboolean(lua_State *L, int b);

Legt einen Wahrheitswert b auf dem Stapelspeicher ab.

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

lua_pushcfunction
void lua_pushcfunction(lua_State *L, lua_CFunction f);

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

lua_pushinteger
void lua_pushinteger(lua_State *L, lua_Integer n);

Legt eine Zahl mit dem Wert n auf dem Stapelspeicher ab.

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

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

Dieses Makro ist äquivalent zu lua_pushlstring, kann jedoch nur benutzt werden, wenn s eine literale Zeichenkette ist. In diesen Fällen wird automatisch die Länge der Zeichenkette zur Verfügung gestellt.

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

Pushes the string pointed to by s with size len onto the stack. Lua makes (or reuses) an internal copy of the given string, so the memory at s can be freed or reused immediately after the function returns. The string can contain embedded zeros.

lua_pushnil
void lua_pushnil(lua_State *L);

Legt einen Nullwert auf dem Stapelspeicher ab.

lua_pushnumber
void lua_pushnumber(lua_State *L, lua_Number n);

Legt eine Zahl mit dem Wert n auf dem Stapelspeicher ab.

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

Pushes the zero-terminated string pointed to by s onto the stack. Lua makes (or reuses) an internal copy of the given string, so the memory at s can be freed or reused immediately after the function returns. The string cannot contain embedded zeros; it is assumed to end at the first zero.

lua_pushthread
int lua_pushthread(lua_State *L);

Pushes the thread represented by L onto the stack. Returns 1 if this thread is the main thread of its state.

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

Legt eine Kopie des Elements am gegebenen Index auf dem Stapelspeicher ab.

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

Equivalent to lua_pushfstring, except that it receives a va_list instead of a variable number of arguments.

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

Returns 1 if the two values in acceptable indices index1 and index2 are primitively equal (that is, without calling metamethods). Otherwise returns 0. Also returns 0 if any of the indices are non valid.

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

Ähnlich wie lua_gettable, führt jedoch einen rohen Zugriff aus (ohne Metamethoden).

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

Pushes onto the stack the value t[n], where t is the value at the given valid index. The access is raw; that is, it does not invoke metamethods.

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

Ähnlichen wie lua_settable, führt jedoch einen rohen Zugriff aus (ohne Metamethoden).

lua_rawseti
void lua_rawseti(lua_State *L, int index, int n);

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

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

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

Removes the element at the given valid index, shifting down the elements above this index to fill the gap. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.

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

Moves the top element into the given position (and pops it), without shifting any element (therefore replacing the value at the given position).

lua_resume
int lua_resume(lua_State *L, int narg);

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

Changes the allocator function of a given state to f with user data ud.

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

Pops a table from the stack and sets it as the new environment for the value at the given index. If the value at the given index is neither a function nor a thread nor a userdata, lua_setfenv returns 0. Otherwise it returns 1.

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

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

Entfernt einen Wert vom Stapelspeicher und setzt ihn als neuen Wert des globalen name. Die Funktion ist als Makro definiert:

#define lua_setglobal(L,s) lua_setfield(L,LUA_GLOBALSINDEX,s)
lua_setmetatable
int lua_setmetatable(lua_State *L, int index);

Entfernt eine Tabelle vom Stapelspeicher und setzt sie als neue Metatabelle für den Wert am gegebenen Index.

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

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

Accepts any acceptable index, or 0, and sets the stack top to this index. If the new top is larger than the old one, then the new elements are filled with nil. If index is 0, then all stack elements are removed.

lua_State
typedef struct lua_State lua_State;

lua_status
int lua_status(lua_State *L);

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

Converts the Lua value at the given acceptable index to a C boolean value (0 or 1). Like all tests in Lua, lua_toboolean returns 1 for any Lua value different from false and nil; otherwise it returns 0. It also returns 0 when called with a non-valid index. (If you want to accept only actual boolean values, use lua_isboolean to test the value's type.)

lua_tocfunction
lua_CFunction lua_tocfunction (lua_State *L, int inde

Konvertiert einen Wert am gegebenen Index in eine C-Funktion. Dieser Wert muss eine C-Funktion sein; andernfalls wird NULL geliefert.

lua_tointeger
lua_Integer lua_tointeger (lua_State *L, int index);

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

lua_tonumber
lua_Number lua_tonumber (lua_State *L, int index);

Konvertiert den Lua-Wert am gegebenen gültigen Index zu einem C-Typen lua_Number (s. lua_Number). Der Lua-Wert muss eine Zahl oder eine zu einer solchen konvertierbaren Zeichenkette sein (s. § 2.2.1); andernfalls liefert lua_tonumber 0.

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

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

Äquivalent zu lua_tolstring mit len gleich NULL.

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

Konvertiert den Wert am gegebenen gültigen Index zu einem Lua-Thread (als lua_State* repräsentiert). Dieser Wert muss ein Thread sein; andernfalls liefert die Funktion NULL.

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

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

Liefert den Typ des Wertes am gegebenen Index, oder LUA_TNONE für einen ungültigen Index (d. h. ein Index zu einer "leeren" Position auf dem Stapelspeicher). Die von lua_type gelieferten Typen werden durch folgende in der Datei lua.h definierten Konstanten kodiert: LUA_TNIL, LUA_TNUMBER, LUA_TBOOLEAN, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, LUA_TUSERDATA, LUA_TTHREAD und LUA_TLIGHTUSERDATA.

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

Liefert den Bezeichner des vom Wert tp genutzten Typs, welcher einem der von lua_type gelieferten entsprechen muss.

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

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

lua_yield
int lua_yield(lua_State *L, int nresults);