4.1 – Stack and Function Information

The main function to get information about the interpreter runtime stack is

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

This function fills parts of a lua_Debug structure with an identification of the activation record of the function executing at a given level. Level 0 is the current running function, whereas level n+1 is the function that has called level n. When there are no errors, lua_getstack returns 1; when called with a level greater than the stack depth, it returns 0.

The structure lua_Debug is used to carry different pieces of information about an active function:

      typedef struct lua_Debug {
        int event;
        const char *name;      /* (n) */
        const char *namewhat;  /* (n) `global', `local', `field', `method' */
        const char *what;      /* (S) `Lua' function, `C' function, Lua `main' */
        const char *source;    /* (S) */
        int currentline;       /* (l) */
        int nups;              /* (u) number of upvalues */
        int linedefined;       /* (S) */
        char short_src[LUA_IDSIZE]; /* (S) */
 
        /* private part */
        ...
      } lua_Debug;

lua_getstack fills only the private part of this structure, for later use. To fill the other fields of lua_Debug with useful information, call

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

This function returns 0 on error (for instance, an invalid option in what). Each character in the string what selects some fields of the structure ar to be filled, as indicated by the letter in parentheses in the definition of lua_Debug above: `S´ fills in the fields source, linedefined, and what; `l´ fills in the field currentline, etc. Moreover, `f´ pushes onto the stack the function that is running at the given level.

To get information about a function that is not active (that is, not in the stack), you push it onto the stack and start the what string with the character `>´. For instance, to know in which line a function f was defined, you can write

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

The fields of lua_Debug have the following meaning:

• source If the function was defined in a string, then source is that string. If the function was defined in a file, then source starts with a `@´ followed by the file name.

• short_src A “printable” version of source, to be used in error messages.

• linedefined the line number where the definition of the function starts.

• what the string "Lua" if this is a Lua function, "C" if this is a C function, "main" if this is the main part of a chunk, and "tail" if this was a function that did a tail call. In the latter case, Lua has no other information about this function.

• currentline the current line where the given function is executing. When no line information is available, currentline is set to -1.

• name a reasonable name for the given function. Because functions in Lua are first class values, they do not have a fixed name: Some functions may be the value of multiple global variables, while others may be stored only in a table field. The lua_getinfo function checks how the function was called or whether it is the value of a global variable to find a suitable name. If it cannot find a name, then name is set to NULL.

• namewhat Explains the name field. The value of namewhat can be "global", "local", "method", "field", or "" (the empty string), according to how the function was called. (Lua uses the empty string when no other option seems to apply.)

• nups The number of upvalues of the function.