called upvalues and are accessible
to the function whenever it is called (see |lua_pushcclosure()|).

Whenever a C function is called, its upvalues are located at specific
pseudo-indices. These pseudo-indices are produced by the macro
`lua_upvalueindex`. The first value associated with a function is at position
`lua_upvalueindex(1)`, and so on. Any access to `lua_upvalueindex(` `n` `)`,
where `n` is greater than the number of upvalues of the current function,
produces an acceptable (but invalid) index.

==============================================================================
3.5  Registry                                           *lua-registry*

Lua provides a registry, a pre-defined table that can be used by any C code to
store whatever Lua value it needs to store. This table is always located at
pseudo-index `LUA_REGISTRYINDEX`. Any C library can store data into this
table, but it should take care to choose keys different from those used by
other libraries, to avoid collisions. Typically, you should use as key a
string containing your library name or a light userdata with the address of a
C object in your code.

The integer keys in the registry are used by the reference mechanism,
implemented by the auxiliary library, and therefore should not be used for
other purposes.

==============================================================================
3.6  Error Handling in C                                *lua-apiError*

Internally, Lua uses the C `longjmp` facility to handle errors. (You can also
choose to use exceptions if you use C++; see file `luaconf.h`.) When Lua faces
any error (such as memory allocation errors, type errors, syntax errors, and
runtime errors) it raises an error; that is, it does a long jump. A protected
environment uses `setjmp` to set a recover point; any error jumps to the most
recent active recover point.

Almost any function in the API may raise an error, for instance due to a
memory allocation error. The following functions run in protected mode (that
is, they create a protected environment to run), so they never raise an error:
`lua_newstate`, `lua_close`, `lua_load`, `lua_pcall`, and `lua_cpcall` (see
|lua_newstate()|, |lua_close()|, |lua_load()|,
|lua_pcall()|, and |lua_cpcall()|).

Inside a C function you can raise an error by calling `lua_error`  (see
|lua_error()|).

==============================================================================
3.7  Functions and Types                                   *lua-apiFunctions*

Here we list all functions and types from the C API in alphabetical order.

lua_Alloc                                                            *lua_Alloc*
>c
    typedef void * (*lua_Alloc) (void *ud,
                                 void *ptr,
                                 size_t osize,
                                 size_t nsize);
<
        The type of the memory-allocation function used by Lua states. The
        allocator function must provide a functionality similar to `realloc`,
        but not exactly the same. Its arguments are `ud`, an opaque pointer
        passed to `lua_newstate` (see |lua_newstate()|); `ptr`, a pointer
        to the block being allocated/reallocated/freed; `osize`, the original
        size of the block; `nsize`, the new size of the block. `ptr` is `NULL`
        if and only if `osize` is zero. When `nsize` is zero, the allocator
        must return `NULL`; if `osize` is not zero, it should free the block
        pointed to by `ptr`. When `nsize` is not zero, the allocator returns
        `NULL` if and only if it cannot fill the request. When `nsize` is not
        zero and `osize` is zero, the allocator should behave like `malloc`.
        When `nsize` and `osize` are not zero, the allocator behaves like
        `realloc`. Lua assumes that the allocator never fails when
        `osize >= nsize`.

        Here is a simple implementation for the allocator function. It is used
        in the auxiliary library by `luaL_newstate` (see