source/include/emacs-module.h

0001 /* emacs-module.h - GNU Emacs module API.
0002
0003 Copyright (C) 2015-2022 Free Software Foundation, Inc.
0004
0005 This file is part of GNU Emacs.
0006
0007 GNU Emacs is free software: you can redistribute it and/or modify
0008 it under the terms of the GNU General Public License as published by
0009 the Free Software Foundation, either version 3 of the License, or (at
0010 your option) any later version.
0011
0012 GNU Emacs is distributed in the hope that it will be useful,
0013 but WITHOUT ANY WARRANTY; without even the implied warranty of
0014 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0015 GNU General Public License for more details.
0016
0017 You should have received a copy of the GNU General Public License
0018 along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.  */
0019
0020 /*
0021 This file defines the Emacs module API.  Please see the chapter
0022 `Dynamic Modules' in the GNU Emacs Lisp Reference Manual for
0023 information how to write modules and use this header file.
0024 */
0025
0026 #ifndef EMACS_MODULE_H
0027 #define EMACS_MODULE_H
0028
0029 #include <stddef.h>
0030 #include <stdint.h>
0031 #include <time.h>
0032
0033 #ifndef __cplusplus
0034 #include <stdbool.h>
0035 #endif
0036
0037 #define EMACS_MAJOR_VERSION 28
0038
0039 #if defined __cplusplus && __cplusplus >= 201103L
0040 # define EMACS_NOEXCEPT noexcept
0041 #else
0042 # define EMACS_NOEXCEPT
0043 #endif
0044
0045 #if defined __cplusplus && __cplusplus >= 201703L
0046 # define EMACS_NOEXCEPT_TYPEDEF noexcept
0047 #else
0048 # define EMACS_NOEXCEPT_TYPEDEF
0049 #endif
0050
0051 #if 3 < __GNUC__ + (3 <= __GNUC_MINOR__)
0052 # define EMACS_ATTRIBUTE_NONNULL(...) \
0053    __attribute__ ((__nonnull__ (__VA_ARGS__)))
0054 #elif (defined __has_attribute \
0055        && (!defined __clang_minor__ \
0056        || 3 < __clang_major__ + (5 <= __clang_minor__)))
0057 # if __has_attribute (__nonnull__)
0058 #  define EMACS_ATTRIBUTE_NONNULL(...) \
0059     __attribute__ ((__nonnull__ (__VA_ARGS__)))
0060 # endif
0061 #endif
0062 #ifndef EMACS_ATTRIBUTE_NONNULL
0063 # define EMACS_ATTRIBUTE_NONNULL(...)
0064 #endif
0065
0066 #ifdef __cplusplus
0067 extern "C" {
0068 #endif
0069
0070 /* Current environment.  */
0071 typedef struct emacs_env_28 emacs_env;
0072
0073 /* Opaque pointer representing an Emacs Lisp value.
0074    BEWARE: Do not assume NULL is a valid value!  */
0075 typedef struct emacs_value_tag *emacs_value;
0076
0077 enum { emacs_variadic_function = -2 };
0078
0079 /* Struct passed to a module init function (emacs_module_init).  */
0080 struct emacs_runtime
0081 {
0082   /* Structure size (for version checking).  */
0083   ptrdiff_t size;
0084
0085   /* Private data; users should not touch this.  */
0086   struct emacs_runtime_private *private_members;
0087
0088   /* Return an environment pointer.  */
0089   emacs_env *(*get_environment) (struct emacs_runtime *runtime)
0090     EMACS_ATTRIBUTE_NONNULL (1);
0091 };
0092
0093 /* Type aliases for function pointer types used in the module API.
0094    Note that we don't use these aliases directly in the API to be able
0095    to mark the function arguments as 'noexcept' before C++20.
0096    However, users can use them if they want.  */
0097
0098 /* Function prototype for the module Lisp functions.  These must not
0099    throw C++ exceptions.  */
0100 typedef emacs_value (*emacs_function) (emacs_env *env, ptrdiff_t nargs,
0101                                        emacs_value *args,
0102                                        void *data)
0103   EMACS_NOEXCEPT_TYPEDEF EMACS_ATTRIBUTE_NONNULL (1);
0104
0105 /* Function prototype for module user-pointer and function finalizers.
0106    These must not throw C++ exceptions.  */
0107 typedef void (*emacs_finalizer) (void *data) EMACS_NOEXCEPT_TYPEDEF;
0108
0109 /* Possible Emacs function call outcomes.  */
0110 enum emacs_funcall_exit
0111 {
0112   /* Function has returned normally.  */
0113   emacs_funcall_exit_return = 0,
0114
0115   /* Function has signaled an error using `signal'.  */
0116   emacs_funcall_exit_signal = 1,
0117
0118   /* Function has exit using `throw'.  */
0119   emacs_funcall_exit_throw = 2
0120 };
0121
0122 /* Possible return values for emacs_env.process_input.  */
0123 enum emacs_process_input_result
0124 {
0125   /* Module code may continue  */
0126   emacs_process_input_continue = 0,
0127
0128   /* Module code should return control to Emacs as soon as possible.  */
0129   emacs_process_input_quit = 1
0130 };
0131
0132 /* Define emacs_limb_t so that it is likely to match GMP's mp_limb_t.
0133    This micro-optimization can help modules that use mpz_export and
0134    mpz_import, which operate more efficiently on mp_limb_t.  It's OK
0135    (if perhaps a bit slower) if the two types do not match, and
0136    modules shouldn't rely on the two types matching.  */
0137 typedef size_t emacs_limb_t;
0138 #define EMACS_LIMB_MAX SIZE_MAX
0139
0140 struct emacs_env_25
0141 {
0142   /* Structure size (for version checking).  */
0143   ptrdiff_t size;
0144
0145   /* Private data; users should not touch this.  */
0146   struct emacs_env_private *private_members;
0147
0148   /* Memory management.  */
0149
0150   emacs_value (*make_global_ref) (emacs_env *env, emacs_value value)
0151     EMACS_ATTRIBUTE_NONNULL(1);
0152
0153   void (*free_global_ref) (emacs_env *env, emacs_value global_value)
0154     EMACS_ATTRIBUTE_NONNULL(1);
0155
0156   /* Non-local exit handling.  */
0157
0158   enum emacs_funcall_exit (*non_local_exit_check) (emacs_env *env)
0159     EMACS_ATTRIBUTE_NONNULL(1);
0160
0161   void (*non_local_exit_clear) (emacs_env *env)
0162     EMACS_ATTRIBUTE_NONNULL(1);
0163
0164   enum emacs_funcall_exit (*non_local_exit_get)
0165     (emacs_env *env, emacs_value *symbol, emacs_value *data)
0166     EMACS_ATTRIBUTE_NONNULL(1, 2, 3);
0167
0168   void (*non_local_exit_signal) (emacs_env *env,
0169                  emacs_value symbol, emacs_value data)
0170     EMACS_ATTRIBUTE_NONNULL(1);
0171
0172   void (*non_local_exit_throw) (emacs_env *env,
0173                 emacs_value tag, emacs_value value)
0174     EMACS_ATTRIBUTE_NONNULL(1);
0175
0176   /* Function registration.  */
0177
0178   emacs_value (*make_function) (emacs_env *env,
0179                 ptrdiff_t min_arity,
0180                 ptrdiff_t max_arity,
0181                 emacs_value (*func) (emacs_env *env,
0182                                                      ptrdiff_t nargs,
0183                                                      emacs_value* args,
0184                                                      void *data)
0185                   EMACS_NOEXCEPT
0186                                   EMACS_ATTRIBUTE_NONNULL(1),
0187                 const char *docstring,
0188                 void *data)
0189     EMACS_ATTRIBUTE_NONNULL(1, 4);
0190
0191   emacs_value (*funcall) (emacs_env *env,
0192                           emacs_value func,
0193                           ptrdiff_t nargs,
0194                           emacs_value* args)
0195     EMACS_ATTRIBUTE_NONNULL(1);
0196
0197   emacs_value (*intern) (emacs_env *env, const char *name)
0198     EMACS_ATTRIBUTE_NONNULL(1, 2);
0199
0200   /* Type conversion.  */
0201
0202   emacs_value (*type_of) (emacs_env *env, emacs_value arg)
0203     EMACS_ATTRIBUTE_NONNULL(1);
0204
0205   bool (*is_not_nil) (emacs_env *env, emacs_value arg)
0206     EMACS_ATTRIBUTE_NONNULL(1);
0207
0208   bool (*eq) (emacs_env *env, emacs_value a, emacs_value b)
0209     EMACS_ATTRIBUTE_NONNULL(1);
0210
0211   intmax_t (*extract_integer) (emacs_env *env, emacs_value arg)
0212     EMACS_ATTRIBUTE_NONNULL(1);
0213
0214   emacs_value (*make_integer) (emacs_env *env, intmax_t n)
0215     EMACS_ATTRIBUTE_NONNULL(1);
0216
0217   double (*extract_float) (emacs_env *env, emacs_value arg)
0218     EMACS_ATTRIBUTE_NONNULL(1);
0219
0220   emacs_value (*make_float) (emacs_env *env, double d)
0221     EMACS_ATTRIBUTE_NONNULL(1);
0222
0223   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
0224      null-terminated string.
0225
0226      SIZE must point to the total size of the buffer.  If BUFFER is
0227      NULL or if SIZE is not big enough, write the required buffer size
0228      to SIZE and return true.
0229
0230      Note that SIZE must include the last null byte (e.g. "abc" needs
0231      a buffer of size 4).
0232
0233      Return true if the string was successfully copied.  */
0234
0235   bool (*copy_string_contents) (emacs_env *env,
0236                                 emacs_value value,
0237                                 char *buf,
0238                                 ptrdiff_t *len)
0239     EMACS_ATTRIBUTE_NONNULL(1, 4);
0240
0241   /* Create a Lisp string from a utf8 encoded string.  */
0242   emacs_value (*make_string) (emacs_env *env,
0243                   const char *str, ptrdiff_t len)
0244     EMACS_ATTRIBUTE_NONNULL(1, 2);
0245
0246   /* Embedded pointer type.  */
0247   emacs_value (*make_user_ptr) (emacs_env *env,
0248                 void (*fin) (void *) EMACS_NOEXCEPT,
0249                 void *ptr)
0250     EMACS_ATTRIBUTE_NONNULL(1);
0251
0252   void *(*get_user_ptr) (emacs_env *env, emacs_value arg)
0253     EMACS_ATTRIBUTE_NONNULL(1);
0254   void (*set_user_ptr) (emacs_env *env, emacs_value arg, void *ptr)
0255     EMACS_ATTRIBUTE_NONNULL(1);
0256
0257   void (*(*get_user_finalizer) (emacs_env *env, emacs_value uptr))
0258     (void *) EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1);
0259   void (*set_user_finalizer) (emacs_env *env, emacs_value arg,
0260                   void (*fin) (void *) EMACS_NOEXCEPT)
0261     EMACS_ATTRIBUTE_NONNULL(1);
0262
0263   /* Vector functions.  */
0264   emacs_value (*vec_get) (emacs_env *env, emacs_value vector, ptrdiff_t index)
0265     EMACS_ATTRIBUTE_NONNULL(1);
0266
0267   void (*vec_set) (emacs_env *env, emacs_value vector, ptrdiff_t index,
0268            emacs_value value)
0269     EMACS_ATTRIBUTE_NONNULL(1);
0270
0271   ptrdiff_t (*vec_size) (emacs_env *env, emacs_value vector)
0272     EMACS_ATTRIBUTE_NONNULL(1);
0273 };
0274
0275 struct emacs_env_26
0276 {
0277   /* Structure size (for version checking).  */
0278   ptrdiff_t size;
0279
0280   /* Private data; users should not touch this.  */
0281   struct emacs_env_private *private_members;
0282
0283   /* Memory management.  */
0284
0285   emacs_value (*make_global_ref) (emacs_env *env, emacs_value value)
0286     EMACS_ATTRIBUTE_NONNULL(1);
0287
0288   void (*free_global_ref) (emacs_env *env, emacs_value global_value)
0289     EMACS_ATTRIBUTE_NONNULL(1);
0290
0291   /* Non-local exit handling.  */
0292
0293   enum emacs_funcall_exit (*non_local_exit_check) (emacs_env *env)
0294     EMACS_ATTRIBUTE_NONNULL(1);
0295
0296   void (*non_local_exit_clear) (emacs_env *env)
0297     EMACS_ATTRIBUTE_NONNULL(1);
0298
0299   enum emacs_funcall_exit (*non_local_exit_get)
0300     (emacs_env *env, emacs_value *symbol, emacs_value *data)
0301     EMACS_ATTRIBUTE_NONNULL(1, 2, 3);
0302
0303   void (*non_local_exit_signal) (emacs_env *env,
0304                  emacs_value symbol, emacs_value data)
0305     EMACS_ATTRIBUTE_NONNULL(1);
0306
0307   void (*non_local_exit_throw) (emacs_env *env,
0308                 emacs_value tag, emacs_value value)
0309     EMACS_ATTRIBUTE_NONNULL(1);
0310
0311   /* Function registration.  */
0312
0313   emacs_value (*make_function) (emacs_env *env,
0314                 ptrdiff_t min_arity,
0315                 ptrdiff_t max_arity,
0316                 emacs_value (*func) (emacs_env *env,
0317                                                      ptrdiff_t nargs,
0318                                                      emacs_value* args,
0319                                                      void *data)
0320                   EMACS_NOEXCEPT
0321                                   EMACS_ATTRIBUTE_NONNULL(1),
0322                 const char *docstring,
0323                 void *data)
0324     EMACS_ATTRIBUTE_NONNULL(1, 4);
0325
0326   emacs_value (*funcall) (emacs_env *env,
0327                           emacs_value func,
0328                           ptrdiff_t nargs,
0329                           emacs_value* args)
0330     EMACS_ATTRIBUTE_NONNULL(1);
0331
0332   emacs_value (*intern) (emacs_env *env, const char *name)
0333     EMACS_ATTRIBUTE_NONNULL(1, 2);
0334
0335   /* Type conversion.  */
0336
0337   emacs_value (*type_of) (emacs_env *env, emacs_value arg)
0338     EMACS_ATTRIBUTE_NONNULL(1);
0339
0340   bool (*is_not_nil) (emacs_env *env, emacs_value arg)
0341     EMACS_ATTRIBUTE_NONNULL(1);
0342
0343   bool (*eq) (emacs_env *env, emacs_value a, emacs_value b)
0344     EMACS_ATTRIBUTE_NONNULL(1);
0345
0346   intmax_t (*extract_integer) (emacs_env *env, emacs_value arg)
0347     EMACS_ATTRIBUTE_NONNULL(1);
0348
0349   emacs_value (*make_integer) (emacs_env *env, intmax_t n)
0350     EMACS_ATTRIBUTE_NONNULL(1);
0351
0352   double (*extract_float) (emacs_env *env, emacs_value arg)
0353     EMACS_ATTRIBUTE_NONNULL(1);
0354
0355   emacs_value (*make_float) (emacs_env *env, double d)
0356     EMACS_ATTRIBUTE_NONNULL(1);
0357
0358   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
0359      null-terminated string.
0360
0361      SIZE must point to the total size of the buffer.  If BUFFER is
0362      NULL or if SIZE is not big enough, write the required buffer size
0363      to SIZE and return true.
0364
0365      Note that SIZE must include the last null byte (e.g. "abc" needs
0366      a buffer of size 4).
0367
0368      Return true if the string was successfully copied.  */
0369
0370   bool (*copy_string_contents) (emacs_env *env,
0371                                 emacs_value value,
0372                                 char *buf,
0373                                 ptrdiff_t *len)
0374     EMACS_ATTRIBUTE_NONNULL(1, 4);
0375
0376   /* Create a Lisp string from a utf8 encoded string.  */
0377   emacs_value (*make_string) (emacs_env *env,
0378                   const char *str, ptrdiff_t len)
0379     EMACS_ATTRIBUTE_NONNULL(1, 2);
0380
0381   /* Embedded pointer type.  */
0382   emacs_value (*make_user_ptr) (emacs_env *env,
0383                 void (*fin) (void *) EMACS_NOEXCEPT,
0384                 void *ptr)
0385     EMACS_ATTRIBUTE_NONNULL(1);
0386
0387   void *(*get_user_ptr) (emacs_env *env, emacs_value arg)
0388     EMACS_ATTRIBUTE_NONNULL(1);
0389   void (*set_user_ptr) (emacs_env *env, emacs_value arg, void *ptr)
0390     EMACS_ATTRIBUTE_NONNULL(1);
0391
0392   void (*(*get_user_finalizer) (emacs_env *env, emacs_value uptr))
0393     (void *) EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1);
0394   void (*set_user_finalizer) (emacs_env *env, emacs_value arg,
0395                   void (*fin) (void *) EMACS_NOEXCEPT)
0396     EMACS_ATTRIBUTE_NONNULL(1);
0397
0398   /* Vector functions.  */
0399   emacs_value (*vec_get) (emacs_env *env, emacs_value vector, ptrdiff_t index)
0400     EMACS_ATTRIBUTE_NONNULL(1);
0401
0402   void (*vec_set) (emacs_env *env, emacs_value vector, ptrdiff_t index,
0403            emacs_value value)
0404     EMACS_ATTRIBUTE_NONNULL(1);
0405
0406   ptrdiff_t (*vec_size) (emacs_env *env, emacs_value vector)
0407     EMACS_ATTRIBUTE_NONNULL(1);
0408
0409   /* Returns whether a quit is pending.  */
0410   bool (*should_quit) (emacs_env *env)
0411     EMACS_ATTRIBUTE_NONNULL(1);
0412 };
0413
0414 struct emacs_env_27
0415 {
0416   /* Structure size (for version checking).  */
0417   ptrdiff_t size;
0418
0419   /* Private data; users should not touch this.  */
0420   struct emacs_env_private *private_members;
0421
0422   /* Memory management.  */
0423
0424   emacs_value (*make_global_ref) (emacs_env *env, emacs_value value)
0425     EMACS_ATTRIBUTE_NONNULL(1);
0426
0427   void (*free_global_ref) (emacs_env *env, emacs_value global_value)
0428     EMACS_ATTRIBUTE_NONNULL(1);
0429
0430   /* Non-local exit handling.  */
0431
0432   enum emacs_funcall_exit (*non_local_exit_check) (emacs_env *env)
0433     EMACS_ATTRIBUTE_NONNULL(1);
0434
0435   void (*non_local_exit_clear) (emacs_env *env)
0436     EMACS_ATTRIBUTE_NONNULL(1);
0437
0438   enum emacs_funcall_exit (*non_local_exit_get)
0439     (emacs_env *env, emacs_value *symbol, emacs_value *data)
0440     EMACS_ATTRIBUTE_NONNULL(1, 2, 3);
0441
0442   void (*non_local_exit_signal) (emacs_env *env,
0443                  emacs_value symbol, emacs_value data)
0444     EMACS_ATTRIBUTE_NONNULL(1);
0445
0446   void (*non_local_exit_throw) (emacs_env *env,
0447                 emacs_value tag, emacs_value value)
0448     EMACS_ATTRIBUTE_NONNULL(1);
0449
0450   /* Function registration.  */
0451
0452   emacs_value (*make_function) (emacs_env *env,
0453                 ptrdiff_t min_arity,
0454                 ptrdiff_t max_arity,
0455                 emacs_value (*func) (emacs_env *env,
0456                                                      ptrdiff_t nargs,
0457                                                      emacs_value* args,
0458                                                      void *data)
0459                   EMACS_NOEXCEPT
0460                                   EMACS_ATTRIBUTE_NONNULL(1),
0461                 const char *docstring,
0462                 void *data)
0463     EMACS_ATTRIBUTE_NONNULL(1, 4);
0464
0465   emacs_value (*funcall) (emacs_env *env,
0466                           emacs_value func,
0467                           ptrdiff_t nargs,
0468                           emacs_value* args)
0469     EMACS_ATTRIBUTE_NONNULL(1);
0470
0471   emacs_value (*intern) (emacs_env *env, const char *name)
0472     EMACS_ATTRIBUTE_NONNULL(1, 2);
0473
0474   /* Type conversion.  */
0475
0476   emacs_value (*type_of) (emacs_env *env, emacs_value arg)
0477     EMACS_ATTRIBUTE_NONNULL(1);
0478
0479   bool (*is_not_nil) (emacs_env *env, emacs_value arg)
0480     EMACS_ATTRIBUTE_NONNULL(1);
0481
0482   bool (*eq) (emacs_env *env, emacs_value a, emacs_value b)
0483     EMACS_ATTRIBUTE_NONNULL(1);
0484
0485   intmax_t (*extract_integer) (emacs_env *env, emacs_value arg)
0486     EMACS_ATTRIBUTE_NONNULL(1);
0487
0488   emacs_value (*make_integer) (emacs_env *env, intmax_t n)
0489     EMACS_ATTRIBUTE_NONNULL(1);
0490
0491   double (*extract_float) (emacs_env *env, emacs_value arg)
0492     EMACS_ATTRIBUTE_NONNULL(1);
0493
0494   emacs_value (*make_float) (emacs_env *env, double d)
0495     EMACS_ATTRIBUTE_NONNULL(1);
0496
0497   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
0498      null-terminated string.
0499
0500      SIZE must point to the total size of the buffer.  If BUFFER is
0501      NULL or if SIZE is not big enough, write the required buffer size
0502      to SIZE and return true.
0503
0504      Note that SIZE must include the last null byte (e.g. "abc" needs
0505      a buffer of size 4).
0506
0507      Return true if the string was successfully copied.  */
0508
0509   bool (*copy_string_contents) (emacs_env *env,
0510                                 emacs_value value,
0511                                 char *buf,
0512                                 ptrdiff_t *len)
0513     EMACS_ATTRIBUTE_NONNULL(1, 4);
0514
0515   /* Create a Lisp string from a utf8 encoded string.  */
0516   emacs_value (*make_string) (emacs_env *env,
0517                   const char *str, ptrdiff_t len)
0518     EMACS_ATTRIBUTE_NONNULL(1, 2);
0519
0520   /* Embedded pointer type.  */
0521   emacs_value (*make_user_ptr) (emacs_env *env,
0522                 void (*fin) (void *) EMACS_NOEXCEPT,
0523                 void *ptr)
0524     EMACS_ATTRIBUTE_NONNULL(1);
0525
0526   void *(*get_user_ptr) (emacs_env *env, emacs_value arg)
0527     EMACS_ATTRIBUTE_NONNULL(1);
0528   void (*set_user_ptr) (emacs_env *env, emacs_value arg, void *ptr)
0529     EMACS_ATTRIBUTE_NONNULL(1);
0530
0531   void (*(*get_user_finalizer) (emacs_env *env, emacs_value uptr))
0532     (void *) EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1);
0533   void (*set_user_finalizer) (emacs_env *env, emacs_value arg,
0534                   void (*fin) (void *) EMACS_NOEXCEPT)
0535     EMACS_ATTRIBUTE_NONNULL(1);
0536
0537   /* Vector functions.  */
0538   emacs_value (*vec_get) (emacs_env *env, emacs_value vector, ptrdiff_t index)
0539     EMACS_ATTRIBUTE_NONNULL(1);
0540
0541   void (*vec_set) (emacs_env *env, emacs_value vector, ptrdiff_t index,
0542            emacs_value value)
0543     EMACS_ATTRIBUTE_NONNULL(1);
0544
0545   ptrdiff_t (*vec_size) (emacs_env *env, emacs_value vector)
0546     EMACS_ATTRIBUTE_NONNULL(1);
0547
0548   /* Returns whether a quit is pending.  */
0549   bool (*should_quit) (emacs_env *env)
0550     EMACS_ATTRIBUTE_NONNULL(1);
0551
0552   /* Processes pending input events and returns whether the module
0553      function should quit.  */
0554   enum emacs_process_input_result (*process_input) (emacs_env *env)
0555     EMACS_ATTRIBUTE_NONNULL (1);
0556
0557   struct timespec (*extract_time) (emacs_env *env, emacs_value arg)
0558     EMACS_ATTRIBUTE_NONNULL (1);
0559
0560   emacs_value (*make_time) (emacs_env *env, struct timespec time)
0561     EMACS_ATTRIBUTE_NONNULL (1);
0562
0563   bool (*extract_big_integer) (emacs_env *env, emacs_value arg, int *sign,
0564                                ptrdiff_t *count, emacs_limb_t *magnitude)
0565     EMACS_ATTRIBUTE_NONNULL (1);
0566
0567   emacs_value (*make_big_integer) (emacs_env *env, int sign, ptrdiff_t count,
0568                                    const emacs_limb_t *magnitude)
0569     EMACS_ATTRIBUTE_NONNULL (1);
0570 };
0571
0572 struct emacs_env_28
0573 {
0574   /* Structure size (for version checking).  */
0575   ptrdiff_t size;
0576
0577   /* Private data; users should not touch this.  */
0578   struct emacs_env_private *private_members;
0579
0580   /* Memory management.  */
0581
0582   emacs_value (*make_global_ref) (emacs_env *env, emacs_value value)
0583     EMACS_ATTRIBUTE_NONNULL(1);
0584
0585   void (*free_global_ref) (emacs_env *env, emacs_value global_value)
0586     EMACS_ATTRIBUTE_NONNULL(1);
0587
0588   /* Non-local exit handling.  */
0589
0590   enum emacs_funcall_exit (*non_local_exit_check) (emacs_env *env)
0591     EMACS_ATTRIBUTE_NONNULL(1);
0592
0593   void (*non_local_exit_clear) (emacs_env *env)
0594     EMACS_ATTRIBUTE_NONNULL(1);
0595
0596   enum emacs_funcall_exit (*non_local_exit_get)
0597     (emacs_env *env, emacs_value *symbol, emacs_value *data)
0598     EMACS_ATTRIBUTE_NONNULL(1, 2, 3);
0599
0600   void (*non_local_exit_signal) (emacs_env *env,
0601                  emacs_value symbol, emacs_value data)
0602     EMACS_ATTRIBUTE_NONNULL(1);
0603
0604   void (*non_local_exit_throw) (emacs_env *env,
0605                 emacs_value tag, emacs_value value)
0606     EMACS_ATTRIBUTE_NONNULL(1);
0607
0608   /* Function registration.  */
0609
0610   emacs_value (*make_function) (emacs_env *env,
0611                 ptrdiff_t min_arity,
0612                 ptrdiff_t max_arity,
0613                 emacs_value (*func) (emacs_env *env,
0614                                                      ptrdiff_t nargs,
0615                                                      emacs_value* args,
0616                                                      void *data)
0617                   EMACS_NOEXCEPT
0618                                   EMACS_ATTRIBUTE_NONNULL(1),
0619                 const char *docstring,
0620                 void *data)
0621     EMACS_ATTRIBUTE_NONNULL(1, 4);
0622
0623   emacs_value (*funcall) (emacs_env *env,
0624                           emacs_value func,
0625                           ptrdiff_t nargs,
0626                           emacs_value* args)
0627     EMACS_ATTRIBUTE_NONNULL(1);
0628
0629   emacs_value (*intern) (emacs_env *env, const char *name)
0630     EMACS_ATTRIBUTE_NONNULL(1, 2);
0631
0632   /* Type conversion.  */
0633
0634   emacs_value (*type_of) (emacs_env *env, emacs_value arg)
0635     EMACS_ATTRIBUTE_NONNULL(1);
0636
0637   bool (*is_not_nil) (emacs_env *env, emacs_value arg)
0638     EMACS_ATTRIBUTE_NONNULL(1);
0639
0640   bool (*eq) (emacs_env *env, emacs_value a, emacs_value b)
0641     EMACS_ATTRIBUTE_NONNULL(1);
0642
0643   intmax_t (*extract_integer) (emacs_env *env, emacs_value arg)
0644     EMACS_ATTRIBUTE_NONNULL(1);
0645
0646   emacs_value (*make_integer) (emacs_env *env, intmax_t n)
0647     EMACS_ATTRIBUTE_NONNULL(1);
0648
0649   double (*extract_float) (emacs_env *env, emacs_value arg)
0650     EMACS_ATTRIBUTE_NONNULL(1);
0651
0652   emacs_value (*make_float) (emacs_env *env, double d)
0653     EMACS_ATTRIBUTE_NONNULL(1);
0654
0655   /* Copy the content of the Lisp string VALUE to BUFFER as an utf8
0656      null-terminated string.
0657
0658      SIZE must point to the total size of the buffer.  If BUFFER is
0659      NULL or if SIZE is not big enough, write the required buffer size
0660      to SIZE and return true.
0661
0662      Note that SIZE must include the last null byte (e.g. "abc" needs
0663      a buffer of size 4).
0664
0665      Return true if the string was successfully copied.  */
0666
0667   bool (*copy_string_contents) (emacs_env *env,
0668                                 emacs_value value,
0669                                 char *buf,
0670                                 ptrdiff_t *len)
0671     EMACS_ATTRIBUTE_NONNULL(1, 4);
0672
0673   /* Create a Lisp string from a utf8 encoded string.  */
0674   emacs_value (*make_string) (emacs_env *env,
0675                   const char *str, ptrdiff_t len)
0676     EMACS_ATTRIBUTE_NONNULL(1, 2);
0677
0678   /* Embedded pointer type.  */
0679   emacs_value (*make_user_ptr) (emacs_env *env,
0680                 void (*fin) (void *) EMACS_NOEXCEPT,
0681                 void *ptr)
0682     EMACS_ATTRIBUTE_NONNULL(1);
0683
0684   void *(*get_user_ptr) (emacs_env *env, emacs_value arg)
0685     EMACS_ATTRIBUTE_NONNULL(1);
0686   void (*set_user_ptr) (emacs_env *env, emacs_value arg, void *ptr)
0687     EMACS_ATTRIBUTE_NONNULL(1);
0688
0689   void (*(*get_user_finalizer) (emacs_env *env, emacs_value uptr))
0690     (void *) EMACS_NOEXCEPT EMACS_ATTRIBUTE_NONNULL(1);
0691   void (*set_user_finalizer) (emacs_env *env, emacs_value arg,
0692                   void (*fin) (void *) EMACS_NOEXCEPT)
0693     EMACS_ATTRIBUTE_NONNULL(1);
0694
0695   /* Vector functions.  */
0696   emacs_value (*vec_get) (emacs_env *env, emacs_value vector, ptrdiff_t index)
0697     EMACS_ATTRIBUTE_NONNULL(1);
0698
0699   void (*vec_set) (emacs_env *env, emacs_value vector, ptrdiff_t index,
0700            emacs_value value)
0701     EMACS_ATTRIBUTE_NONNULL(1);
0702
0703   ptrdiff_t (*vec_size) (emacs_env *env, emacs_value vector)
0704     EMACS_ATTRIBUTE_NONNULL(1);
0705
0706   /* Returns whether a quit is pending.  */
0707   bool (*should_quit) (emacs_env *env)
0708     EMACS_ATTRIBUTE_NONNULL(1);
0709
0710   /* Processes pending input events and returns whether the module
0711      function should quit.  */
0712   enum emacs_process_input_result (*process_input) (emacs_env *env)
0713     EMACS_ATTRIBUTE_NONNULL (1);
0714
0715   struct timespec (*extract_time) (emacs_env *env, emacs_value arg)
0716     EMACS_ATTRIBUTE_NONNULL (1);
0717
0718   emacs_value (*make_time) (emacs_env *env, struct timespec time)
0719     EMACS_ATTRIBUTE_NONNULL (1);
0720
0721   bool (*extract_big_integer) (emacs_env *env, emacs_value arg, int *sign,
0722                                ptrdiff_t *count, emacs_limb_t *magnitude)
0723     EMACS_ATTRIBUTE_NONNULL (1);
0724
0725   emacs_value (*make_big_integer) (emacs_env *env, int sign, ptrdiff_t count,
0726                                    const emacs_limb_t *magnitude)
0727     EMACS_ATTRIBUTE_NONNULL (1);
0728
0729   void (*(*EMACS_ATTRIBUTE_NONNULL (1)
0730             get_function_finalizer) (emacs_env *env,
0731                                      emacs_value arg)) (void *) EMACS_NOEXCEPT;
0732
0733   void (*set_function_finalizer) (emacs_env *env, emacs_value arg,
0734                                   void (*fin) (void *) EMACS_NOEXCEPT)
0735     EMACS_ATTRIBUTE_NONNULL (1);
0736
0737   int (*open_channel) (emacs_env *env, emacs_value pipe_process)
0738     EMACS_ATTRIBUTE_NONNULL (1);
0739
0740   void (*make_interactive) (emacs_env *env, emacs_value function,
0741                             emacs_value spec)
0742     EMACS_ATTRIBUTE_NONNULL (1);
0743
0744   /* Create a unibyte Lisp string from a string.  */
0745   emacs_value (*make_unibyte_string) (emacs_env *env,
0746                       const char *str, ptrdiff_t len)
0747     EMACS_ATTRIBUTE_NONNULL(1, 2);
0748 };
0749
0750 /* Every module should define a function as follows.  */
0751 extern int emacs_module_init (struct emacs_runtime *runtime)
0752   EMACS_NOEXCEPT
0753   EMACS_ATTRIBUTE_NONNULL (1);
0754
0755 #ifdef __cplusplus
0756 }
0757 #endif
0758
0759 #endif /* EMACS_MODULE_H */