NAME

lua_Alloc — the type of the memory-allocation function used by Lua states

SYNOPSIS

#include <lua.h>

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

DESCRIPTION

The type of the memory-allocation function used by Lua states. The allocator function must provide a functionality similar to realloc(3), but not exactly the same. Its arguments are ud, an opaque pointer passed to lua_newstate(3); 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 not zero and osize is zero, the allocator should behave like malloc(3). When nsize and osize are not zero, the allocator behaves like realloc(3). 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(3).

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);
}

This code assumes that free(NULL) has no effect and that realloc(NULL, size) is equivalent to malloc(size). ANSI C ensures both behaviors.

RETURN VALUES

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.

SEE ALSO

lua_newstate(3), luaL_newstate(3)

Roberto Ierusalimschy, Luiz Henrique de Figueiredo, and Waldemar Celes, Lua 5.1 Reference Manual.

HISTORY

The lua_Alloc() manual page is based on Lua Reference Manual 5.1 and was created by Sergey Bronnikov.