When calling the __len metamethod on userdata, Lua passes two arguments to C, nil and userdata. What is the nil for?

Question

Here's a small C test program to demonstrate what I'm seeing. It registers a new object type with Lua and executes a Lua script. When the script calls the __len metamethod, I would expect only one argument to be passed on the stack - the objects userdata. Instead it passes the userdata and a mysterious nil.

len.c:

#include <stdio.h>
#include <lua5.1/lua.h>
#include <lua5.1/lauxlib.h>
#include <lua5.1/lualib.h>

#define OBJECT_LEN 123456

/* Dummy object */
typedef struct {
    int length;
} object;

/* Create the new object and set the length to OBJECT_LEN */
static int object_new( lua_State *L ) {
    object *new = lua_newuserdata( L, sizeof( object ) );
    new->length = OBJECT_LEN;
    luaL_getmetatable( L, "metatable" );
    lua_setmetatable( L, 1 );
    return 1;
}

/* Get the objects length. */
static int object_len( lua_State *L ) {
    /* Print the Lua stack - always 2 args, userdata and nil */
    static const char *const lua_types[] = {
        "nil", "boolean", "light userdata", "number", "string",
        "table", "function", "userdata", "thread",
    };
    int arg_count = lua_gettop( L );
    int i;
    for ( i = arg_count; i > 0; -- i ) {
        int type = lua_type( L, i );
        printf( "%d:%s\n", i, lua_types[ type ] );
    }

    /* Push the objects length onto the Lua stack */
    object *obj = luaL_checkudata( L, 1, "metatable" );
    lua_pop( L, 2 ); /* pop the mystery 'nil' and userdata */
    lua_pushinteger( L, obj->length );

    return 1;
}    

static const luaL_reg object_constructor[] = {
    { "new", object_new },
    { NULL, NULL }
};

static const luaL_reg object_methods[] = {
    { "__len", object_len },
    { NULL, NULL }
};

int main( int argc, char **argv ) {
    lua_State *L = lua_open();
    luaL_openlibs( L );

    /* Create the 'object' type */
    luaL_newmetatable( L, "metatable" );
    lua_pushvalue( L, -1 );
    lua_setfield( L, -2, "__index" );
    luaL_register( L, NULL, object_methods );
    luaL_register( L, "object", object_constructor );
    lua_pop( L, 2 );

    /* Run the lua script */
    int result = luaL_dofile( L, "meta.lua" );
    if ( result != 0 ) {
        fprintf( stderr, "error:%s\n", lua_tostring( L, 1 ) );
    }

    lua_close( L );

    return 0;
}

meta.lua: Create an object, print it's length.

obj = object.new()
print( "obj length:", #obj )

Compile and execute:

$ gcc -Wall len.c -o len -llua5.1 && ./len
2:nil
1:userdata
obj length:     123456

What's the nil on the stack for?

Answer 1

It is an "unimportant implementation detail."

See this lua-l message thread