Next: Module Misc, Previous: Module Functions, Up: Writing Dynamic Modules
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 Module Nonlocal, 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.
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, typicallylong long
.
This function returns the value of a Lisp float specified by arg, as a C
double
value.
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 aNULL
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 returnstrue
. If the buffer is too small, the function raises theargs-out-of-range
error condition, stores the required number of bytes in*
len, and returnsfalse
. See Module Nonlocal, 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 returnstrue
. This is how you can determine the size of buf needed to store a particular string: first callcopy_string_contents
withNULL
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.
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.
This function returns the number of elements in vector.
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.
This function takes an integer argument n and returns the corresponding
emacs_value
object. It raises theoverflow-error
error condition if the value of n cannot be represented as an Emacs integer, i.e. is not inside the limits set bymost-negative-fixnum
andmost-positive-fixnum
(see Integer Basics).
This function takes a
double
argument d and returns the corresponding Emacs floating-point value.
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 theoverflow-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 Lists), extract list members with car
and
cdr
(see List Elements), create vectors with vector
(see Vector Functions), 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.
This function returns a global reference for 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 tomake_global_ref
with the correspondingfree_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.
This function creates and returns a
user-ptr
object which wraps the C pointer ptr. The finalizer function fin can be aNULL
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 theuser-ptr
object is garbage-collected. Don't run any expensive code in a finalizer, because GC must finish quickly to keep Emacs responsive.
This function extracts the C pointer from the Lisp object represented by val.
This function sets the C pointer embedded in the
user-ptr
object represented by value to ptr.