1/* emacs-module.h - GNU Emacs module API. 2 3Copyright (C) 2015-2021 Free Software Foundation, Inc. 4 5This file is part of GNU Emacs. 6 7GNU Emacs is free software: you can redistribute it and/or modify 8it under the terms of the GNU General Public License as published by 9the Free Software Foundation, either version 3 of the License, or (at 10your option) any later version. 11 12GNU Emacs is distributed in the hope that it will be useful, 13but WITHOUT ANY WARRANTY; without even the implied warranty of 14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 15GNU General Public License for more details. 16 17You should have received a copy of the GNU General Public License 18along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */ 19 20/* 21This file defines the Emacs module API. Please see the chapter 22`Dynamic Modules' in the GNU Emacs Lisp Reference Manual for 23information how to write modules and use this header file. 24*/ 25 26#ifndef EMACS_MODULE_H 27#define EMACS_MODULE_H 28 29#include <stddef.h> 30#include <stdint.h> 31#include <time.h> 32 33#ifndef __cplusplus 34#include <stdbool.h> 35#endif 36 37#define EMACS_MAJOR_VERSION @emacs_major_version@ 38 39#if defined __cplusplus && __cplusplus >= 201103L 40# define EMACS_NOEXCEPT noexcept 41#else 42# define EMACS_NOEXCEPT 43#endif 44 45#ifdef __has_attribute 46#if __has_attribute(__nonnull__) 47# define EMACS_ATTRIBUTE_NONNULL(...) __attribute__((__nonnull__(__VA_ARGS__))) 48#endif 49#endif 50#ifndef EMACS_ATTRIBUTE_NONNULL 51# define EMACS_ATTRIBUTE_NONNULL(...) 52#endif 53 54#ifdef __cplusplus 55extern "C" { 56#endif 57 58/* Current environment. */ 59typedef struct emacs_env_27 emacs_env; 60 61/* Opaque pointer representing an Emacs Lisp value. 62 BEWARE: Do not assume NULL is a valid value! */ 63typedef struct emacs_value_tag *emacs_value; 64 65enum { emacs_variadic_function = -2 }; 66 67/* Struct passed to a module init function (emacs_module_init). */ 68struct emacs_runtime 69{ 70 /* Structure size (for version checking). */ 71 ptrdiff_t size; 72 73 /* Private data; users should not touch this. */ 74 struct emacs_runtime_private *private_members; 75 76 /* Return an environment pointer. */ 77 emacs_env *(*get_environment) (struct emacs_runtime *ert) 78 EMACS_ATTRIBUTE_NONNULL(1); 79}; 80 81 82/* Possible Emacs function call outcomes. */ 83enum emacs_funcall_exit 84{ 85 /* Function has returned normally. */ 86 emacs_funcall_exit_return = 0, 87 88 /* Function has signaled an error using `signal'. */ 89 emacs_funcall_exit_signal = 1, 90 91 /* Function has exit using `throw'. */ 92 emacs_funcall_exit_throw = 2 93}; 94 95/* Possible return values for emacs_env.process_input. */ 96enum emacs_process_input_result 97{ 98 /* Module code may continue */ 99 emacs_process_input_continue = 0, 100 101 /* Module code should return control to Emacs as soon as possible. */ 102 emacs_process_input_quit = 1 103}; 104 105/* Define emacs_limb_t so that it is likely to match GMP's mp_limb_t. 106 This micro-optimization can help modules that use mpz_export and 107 mpz_import, which operate more efficiently on mp_limb_t. It's OK 108 (if perhaps a bit slower) if the two types do not match, and 109 modules shouldn't rely on the two types matching. */ 110typedef size_t emacs_limb_t; 111#define EMACS_LIMB_MAX SIZE_MAX 112 113struct emacs_env_25 114{ 115@module_env_snippet_25@ 116}; 117 118struct emacs_env_26 119{ 120@module_env_snippet_25@ 121 122@module_env_snippet_26@ 123}; 124 125struct emacs_env_27 126{ 127@module_env_snippet_25@ 128 129@module_env_snippet_26@ 130 131@module_env_snippet_27@ 132}; 133 134/* Every module should define a function as follows. */ 135extern int emacs_module_init (struct emacs_runtime *ert) 136 EMACS_NOEXCEPT 137 EMACS_ATTRIBUTE_NONNULL(1); 138 139#ifdef __cplusplus 140} 141#endif 142 143#endif /* EMACS_MODULE_H */ 144