E.8.3 Conversion Between Lisp and Module Values ¶

With very few exceptions, most modules need to exchange data with Lisp programs that call them: accept arguments to module functions and return values from module functions. For this purpose, the module API provides the emacs_value type, which represents Emacs Lisp objects communicated via the API; it is the functional equivalent of the Lisp_Object type used in Emacs C primitives (see Writing Emacs Primitives). This section describes the parts of the module API that allow to create emacs_value objects corresponding to basic Lisp data types, and how to access from C data in emacs_value objects that correspond to Lisp objects.

All of the functions described below are actually function pointers provided via the pointer to the environment which every module function accepts. Therefore, module code should call these functions through the environment pointer, like this:

emacs_env *env;  /* the environment pointer */
env->some_function (arguments...);

The emacs_env pointer will usually come from the first argument to the module function, or from the call to get_environment if you need the environment in the module initialization function.

Most of the functions described below became available in Emacs 25, the first Emacs release that supported dynamic modules. For the few functions that became available in later Emacs releases, we mention the first Emacs version that supported them.

The following API functions extract values of various C data types from emacs_value objects. They all raise the wrong-type-argument error condition (see Type Predicates) if the argument emacs_value object is not of the type expected by the function. See Nonlocal Exits in Modules, for details of how signaling errors works in Emacs modules, and how to catch error conditions inside the module before they are reported to Emacs. The API function type_of (see type_of) can be used to obtain the type of a emacs_value object.

Function: intmax_t extract_integer (emacs_env *env, emacs_value arg) ¶

This function returns the value of a Lisp integer specified by arg. The C data type of the return value, intmax_t, is the widest integral data type supported by the C compiler, typically long long.

Function: double extract_float (emacs_env *env, emacs_value arg) ¶

This function returns the value of a Lisp float specified by arg, as a C double value.

Function: bool copy_string_contents (emacs_env *env, emacs_value arg, char *buf, ptrdiff_t *len) ¶

This function stores the UTF-8 encoded text of a Lisp string specified by arg in the array of char pointed by buf, which should have enough space to hold at least *len bytes, including the terminating null byte. The argument len must not be a NULL pointer, and, when the function is called, it should point to a value that specifies the size of buf in bytes.

If the buffer size specified by *len is large enough to hold the string’s text, the function stores in *len the actual number of bytes copied to buf, including the terminating null byte, and returns true. If the buffer is too small, the function raises the args-out-of-range error condition, stores the required number of bytes in *len, and returns false. See Nonlocal Exits in Modules, for how to handle pending error conditions.

The argument buf can be a NULL pointer, in which case the function stores in *len the number of bytes required for storing the contents of arg, and returns true. This is how you can determine the size of buf needed to store a particular string: first call copy_string_contents with NULL as buf, then allocate enough memory to hold the number of bytes stored by the function in *len, and call the function again with non-NULL buf to actually perform the text copying.

Function: emacs_value vec_get (emacs_env *env, emacs_value vector, ptrdiff_t index) ¶

This function returns the element of vector at index. The index of the first vector element is zero. The function raises the args-out-of-range error condition if the value of index is invalid. To extract C data from the value the function returns, use the other extraction functions described here, as appropriate for the Lisp data type stored in that element of the vector.

Function: ptrdiff_t vec_size (emacs_env *env, emacs_value vector) ¶

This function returns the number of elements in vector.

Function: void vec_set (emacs_env *env, emacs_value vector, ptrdiff_t index, emacs_value value) ¶

This function stores value in the element of vector whose index is index. It raises the args-out-of-range error condition if the value of index is invalid.

The following API functions create emacs_value objects from basic C data types. They all return the created emacs_value object.

Function: emacs_value make_integer (emacs_env *env, intmax_t n) ¶

This function takes an integer argument n and returns the corresponding emacs_value object. It raises the overflow-error error condition if the value of n cannot be represented as an Emacs integer, i.e. is not inside the limits set by most-negative-fixnum and most-positive-fixnum (see Integer Basics).

Function: emacs_value make_float (emacs_env *env, double d) ¶

This function takes a double argument d and returns the corresponding Emacs floating-point value.

Function: emacs_value make_string (emacs_env *env, const char *str, ptrdiff_t strlen) ¶

This function creates an Emacs string from C text string pointed by str whose length in bytes, not including the terminating null byte, is strlen. The original string in str can be either an ASCII string or a UTF-8 encoded non-ASCII string; it can include embedded null bytes, and doesn’t have to end in a terminating null byte at str[strlen]. The function raises the overflow-error error condition if strlen is negative or exceeds the maximum length of an Emacs string.

The API does not provide functions to manipulate Lisp data structures, for example, create lists with cons and list (see Building Cons Cells and Lists), extract list members with car and cdr (see Accessing Elements of Lists), create vectors with vector (see Functions for Vectors), etc. For these, use intern and funcall, described in the next subsection, to call the corresponding Lisp functions.

Normally, emacs_value objects have a rather short lifetime: it ends when the emacs_env pointer used for their creation goes out of scope. Occasionally, you may need to create global references: emacs_value objects that live as long as you wish. Use the following two functions to manage such objects.

Function: emacs_value make_global_ref (emacs_env *env, emacs_value value) ¶

This function returns a global reference for value.

Function: void free_global_ref (emacs_env *env, emacs_value global_value) ¶

This function frees the global_value previously created by make_global_ref. The global_value is no longer valid after the call. Your module code should pair each call to make_global_ref with the corresponding free_global_ref.

An alternative to keeping around C data structures that need to be passed to module functions later is to create user pointer objects. A user pointer, or user-ptr, object is a Lisp object that encapsulates a C pointer and can have an associated finalizer function, which is called when the object is garbage-collected (see Garbage Collection). The module API provides functions to create and access user-ptr objects. These functions raise the wrong-type-argument error condition if they are called on emacs_value that doesn’t represent a user-ptr object.

Function: emacs_value make_user_ptr (emacs_env *env, emacs_finalizer fin, void *ptr) ¶

This function creates and returns a user-ptr object which wraps the C pointer ptr. The finalizer function fin can be a NULL pointer (meaning no finalizer), or it can be a function of the following signature:

typedef void (*emacs_finalizer) (void *ptr);

If fin is not a NULL pointer, it will be called with the ptr as the argument when the user-ptr object is garbage-collected. Don’t run any expensive code in a finalizer, because GC must finish quickly to keep Emacs responsive.

Function: void *get_user_ptr (emacs_env *env, emacs_value val) ¶

This function extracts the C pointer from the Lisp object represented by val.

Function: void set_user_ptr (emacs_env *env, emacs_value value, void *ptr) ¶

This function sets the C pointer embedded in the user-ptr object represented by value to ptr.

Function: emacs_finalizer get_user_finalizer (emacs_env *env, emacs_value val) ¶

This function returns the finalizer of the user-ptr object represented by val, or NULL if it doesn’t have a finalizer.

Function: void set_user_finalizer (emacs_env *env, emacs_value val, emacs_finalizer fin) ¶

This function changes the finalizer of the user-ptr object represented by val to be fin. If fin is a NULL pointer, the user-ptr object will have no finalizer.