1 /* GNU m4 -- A simple macro processor
2 Copyright (C) 1989, 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2002, 2003,
3 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
5 This file is part of GNU M4.
7 GNU M4 is free software: you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation, either version 3 of the License, or
10 (at your option) any later version.
12 GNU M4 is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>.
23 #include "configmake.h"
24 #include "m4private.h"
25 #include "xvasprintf.h"
27 /* Define this to see runtime debug info. Implied by DEBUG. */
28 /*#define DEBUG_MODULES */
31 * This file implements dynamic modules in GNU M4. A module is a
32 * compiled shared object, that can be loaded into GNU M4 at run
33 * time. Information about creating modules is in ../modules/README.
35 * This implementation uses libltdl, which is in turn can open modules
36 * using either dlopen(3) (exists on GNU/Linux, OSF, Solaris, SunOS and
37 * others), shl_load(3) (exists on HPUX), LoadLibrary(3) (exists on
38 * Windows, cygwin, OS/2), load_add_on(3) (exists on BeOS), NSAddImage
39 * (exists on MacOS) and can also fall back to dld_link(3) from GNU
40 * libdld or lt_dlpreload from libtool if shared libraries are not
41 * available on the host machine.
43 * An M4 module will usually define an external symbol called
44 * `m4_builtin_table'. This symbol points to a table of `m4_builtin'.
45 * The table is saved as libltdl caller data and each definition therein
46 * is added to the symbol table.
48 * To load a module, call m4_module_load(), which uses the libltdl
49 * API to find the module in the module search path. The search
50 * path is initialized from the environment variable M4MODPATH, followed
51 * by the configuration time default where the modules shipped with M4
52 * itself are installed. Libltdl reads the libtool .la file to
53 * get the real library name (which can be system dependent), returning
54 * NULL on failure or else a libtool module handle for the newly mapped
55 * vm segment containing the module code. If the module is not already
56 * loaded, m4_module_load() retrieves its value for the symbol
57 * `m4_builtin_table', which is installed using set_module_builtin_table().
59 * In addition to builtin functions, you can also define static macro
60 * expansions in the `m4_macro_table' symbol. If you define this symbol
61 * in your modules, it should be an array of `m4_macro's, mapping macro
62 * names to the expansion text. Any macros defined in `m4_macro_table'
63 * are installed into the M4 symbol table with set_module_macro_table().
65 * Each time a module is loaded, the module function prototyped as
66 * "M4INIT_HANDLER (<module name>)" is called, if defined. Any value
67 * stored in OBS by this function becomes the expansion of the macro
68 * which called it. Before M4 exits, all modules are unloaded and the
69 * function prototyped as "M4FINISH_HANDLER (<module name>)" is called,
70 * if defined. It is safe to load the same module several times: the
71 * init and finish functions will also be called multiple times in this
74 * To unload a module, use m4_module_unload(). which uses
75 * m4__symtab_remove_module_references() to remove the builtins defined by
76 * the unloaded module from the symbol table. If the module has been
77 * loaded several times with calls to m4_module_load, then the module will
78 * not be unloaded until the same number of calls to m4_module_unload()
79 * have been made (nor will the symbol table be purged).
82 #define MODULE_SELF_NAME "!myself!"
84 static const char* module_dlerror (void);
85 static int module_remove (m4
*context
, m4_module
*module
,
88 static void install_builtin_table (m4
*, m4_module
*);
89 static void install_macro_table (m4
*, m4_module
*);
91 static int m4__module_interface (lt_dlhandle handle
,
92 const char *id_string
);
94 static lt_dlinterface_id iface_id
= NULL
;
97 m4_get_module_name (const m4_module
*module
)
99 const lt_dlinfo
*info
;
101 assert (module
&& module
->handle
);
103 info
= lt_dlgetinfo (module
->handle
);
105 return info
? info
->name
: NULL
;
109 m4_module_import (m4
*context
, const char *module_name
,
110 const char *symbol_name
, m4_obstack
*obs
)
112 m4_module
* module
= m4__module_find (module_name
);
113 void * symbol_address
= NULL
;
115 /* Try to load the module if it is not yet available (errors are
116 diagnosed by m4_module_load). */
117 /* FIXME - should this use m4__module_open instead, to avoid
118 polluting the symbol table when importing a function? */
120 module
= m4_module_load (context
, module_name
, obs
);
124 symbol_address
= lt_dlsym (module
->handle
, symbol_name
);
127 m4_error (context
, 0, 0, NULL
,
128 _("cannot load symbol `%s' from module `%s'"),
129 symbol_name
, module_name
);
132 return symbol_address
;
136 install_builtin_table (m4
*context
, m4_module
*module
)
138 const m4_builtin
*bp
;
143 bp
= (m4_builtin
*) lt_dlsym (module
->handle
, BUILTIN_SYMBOL
);
146 for (; bp
->name
!= NULL
; bp
++)
148 m4_symbol_value
*value
= m4_symbol_value_create ();
151 /* Sanity check that builtins meet the required interface. */
152 assert (bp
->min_args
<= bp
->max_args
);
153 assert (bp
->min_args
> 0
154 || (bp
->flags
& (M4_BUILTIN_BLIND
155 | M4_BUILTIN_SIDE_EFFECT
)) == 0);
156 assert ((bp
->flags
& ~M4_BUILTIN_FLAGS_MASK
) == 0);
158 m4_set_symbol_value_builtin (value
, bp
);
159 VALUE_MODULE (value
) = module
;
160 VALUE_FLAGS (value
) = bp
->flags
;
161 VALUE_MIN_ARGS (value
) = bp
->min_args
;
162 VALUE_MAX_ARGS (value
) = bp
->max_args
;
164 if (m4_get_prefix_builtins_opt (context
))
165 name
= xasprintf ("m4_%s", bp
->name
);
169 m4_symbol_pushdef (M4SYMTAB
, name
, value
);
171 if (m4_get_prefix_builtins_opt (context
))
172 free ((char *) name
);
175 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
176 _("module %s: builtins loaded"),
177 m4_get_module_name (module
));
182 install_macro_table (m4
*context
, m4_module
*module
)
189 mp
= (const m4_macro
*) lt_dlsym (module
->handle
, MACRO_SYMBOL
);
193 for (; mp
->name
!= NULL
; mp
++)
195 m4_symbol_value
*value
= m4_symbol_value_create ();
197 m4_set_symbol_value_text (value
, xstrdup (mp
->value
));
198 VALUE_MODULE (value
) = module
;
200 m4_symbol_pushdef (M4SYMTAB
, mp
->name
, value
);
203 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
204 _("module %s: macros loaded"),
205 m4_get_module_name (module
));
210 m4_module_load (m4
*context
, const char *name
, m4_obstack
*obs
)
212 m4_module
*module
= m4__module_open (context
, name
, obs
);
214 if (module
&& module
->refcount
== 1)
216 install_builtin_table (context
, module
);
217 install_macro_table (context
, module
);
223 /* Make the module MODULE resident. Return NULL on success, or a
224 pre-translated error string on failure. */
226 m4_module_makeresident (m4_module
*module
)
229 return lt_dlmakeresident (module
->handle
) ? module_dlerror () : NULL
;
232 /* Unload a module. */
234 m4_module_unload (m4
*context
, const char *name
, m4_obstack
*obs
)
236 m4_module
* module
= NULL
;
242 module
= m4__module_find (name
);
246 const char *error_msg
= _("module not loaded");
248 lt_dlseterror (lt_dladderror (error_msg
));
252 errors
= module_remove (context
, module
, obs
);
256 m4_error (context
, EXIT_FAILURE
, 0, NULL
,
257 _("cannot unload module `%s': %s"),
258 name
? name
: MODULE_SELF_NAME
, module_dlerror ());
265 m4__module_interface (lt_dlhandle handle
, const char *id_string
)
267 /* Shortcut. If we've already associated our wrapper with this
268 handle, then we've validated the handle in the past, and don't
269 need to waste any time on additional lt_dlsym calls. */
270 m4_module
*module
= (m4_module
*) lt_dlcaller_get_data (iface_id
, handle
);
274 /* A valid m4 module must provide at least one of these symbols. */
275 return !(lt_dlsym (handle
, INIT_SYMBOL
)
276 || lt_dlsym (handle
, FINISH_SYMBOL
)
277 || lt_dlsym (handle
, BUILTIN_SYMBOL
)
278 || lt_dlsym (handle
, MACRO_SYMBOL
));
282 /* Return successive loaded modules that pass the interface test registered
283 with the interface id. */
285 m4__module_next (m4_module
*module
)
287 lt_dlhandle handle
= module
? module
->handle
: NULL
;
290 /* Resident modules still show up in the lt_dlhandle_iterate loop
291 after they have been unloaded from m4. */
294 handle
= lt_dlhandle_iterate (iface_id
, handle
);
297 module
= (m4_module
*) lt_dlcaller_get_data (iface_id
, handle
);
300 assert (module
->handle
== handle
);
304 /* Return the first loaded module that passes the registered interface test
305 and is called NAME. */
307 m4__module_find (const char *name
)
313 handle
= lt_dlhandle_fetch (iface_id
, name
);
316 module
= (m4_module
*) lt_dlcaller_get_data (iface_id
, handle
);
318 assert (module
->handle
== handle
);
323 /* Initialization. Currently the module search path in path.c is
324 initialized from M4MODPATH. Only absolute path names are accepted to
325 prevent the path search of the dlopen library from finding wrong
328 m4__module_init (m4
*context
)
332 /* Do this only once! If we already have an iface_id, then the
333 module system has already been initialized. */
336 m4_error (context
, 0, 0, NULL
,
337 _("multiple module loader initializations"));
341 errors
= lt_dlinit ();
343 /* Register with libltdl for a key to store client data against
344 ltdl module handles. */
347 iface_id
= lt_dlinterface_register ("m4 libm4", m4__module_interface
);
351 const char *error_msg
= _("libltdl client registration failed");
353 lt_dlseterror (lt_dladderror (error_msg
));
355 /* No need to check error statuses from the calls above -- If
356 either fails for some reason, a diagnostic will be set for
357 lt_dlerror() anyway. */
363 errors
= lt_dlsetsearchpath (PKGLIBEXECDIR
);
365 /* If the user set M4MODPATH, then use that as the start of the module
369 char *path
= getenv (USER_MODULE_PATH_ENV
);
372 errors
= lt_dlinsertsearchdir (lt_dlgetsearchpath (), path
);
375 /* Couldn't initialize the module system; diagnose and exit. */
377 m4_error (context
, EXIT_FAILURE
, 0, NULL
,
378 _("failed to initialize module loader: %s"), module_dlerror ());
381 fputs ("Module loader initialized.\n", stderr
);
382 #endif /* DEBUG_MODULES */
386 /* Load a module. NAME can be a absolute file name or, if relative,
387 it is searched for in the module path. The module is unloaded in
390 m4__module_open (m4
*context
, const char *name
, m4_obstack
*obs
)
392 lt_dlhandle handle
= lt_dlopenext (name
);
393 m4_module
* module
= NULL
;
394 m4_module_init_func
* init_func
= NULL
;
397 assert (iface_id
); /* need to have called m4__module_init */
401 const lt_dlinfo
*info
= lt_dlgetinfo (handle
);
403 /* If we have a handle, there must be handle info. */
407 if (info
->ref_count
> 1)
409 xfprintf (stderr
, "module %s: now has %d libtool references.",
410 name
, info
->ref_count
);
412 #endif /* DEBUG_MODULES */
414 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
415 _("module %s: opening file `%s'"),
416 name
? name
: MODULE_SELF_NAME
, info
->filename
);
418 /* Provide the m4_module corresponding to the lt_dlhandle, if
420 module
= (m4_module
*) lt_dlcaller_get_data (iface_id
, handle
);
426 module
= (m4_module
*) xzalloc (sizeof *module
);
427 module
->handle
= handle
;
429 /* clear out any stale errors, since we have to use
430 lt_dlerror to distinguish between success and
433 old
= lt_dlcaller_set_data (iface_id
, handle
, module
);
437 m4_error (context
, EXIT_FAILURE
, 0, NULL
,
438 _("unable to load module `%s': %s"), name
, err
);
441 /* Find and run any initializing function in the opened module,
442 each time the module is opened. */
444 init_func
= (m4_module_init_func
*) lt_dlsym (handle
, INIT_SYMBOL
);
447 init_func (context
, module
, obs
);
449 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
450 _("module %s: init hook called"), name
);
452 else if (!lt_dlsym (handle
, FINISH_SYMBOL
)
453 && !lt_dlsym (handle
, BUILTIN_SYMBOL
)
454 && !lt_dlsym (handle
, MACRO_SYMBOL
))
456 m4_error (context
, EXIT_FAILURE
, 0, NULL
,
457 _("module `%s' has no entry points"), name
);
460 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
461 _("module %s: opened"), name
);
465 /* Couldn't open the module; diagnose and exit. */
466 m4_error (context
, EXIT_FAILURE
, 0, NULL
,
467 _("cannot open module `%s': %s"), name
, module_dlerror ());
474 m4__module_exit (m4
*context
)
476 m4_module
* module
= m4__module_next (NULL
);
479 while (module
&& !errors
)
481 m4_module
* pending
= module
;
483 /* If we are about to unload the final reference, move on to the
484 next module before we unload the current one. */
485 if (pending
->refcount
<= 1)
486 module
= m4__module_next (module
);
488 errors
= module_remove (context
, pending
, NULL
);
491 assert (iface_id
); /* need to have called m4__module_init */
492 lt_dlinterface_free (iface_id
);
496 errors
= lt_dlexit ();
500 m4_error (context
, EXIT_FAILURE
, 0, NULL
,
501 _("cannot unload all modules: %s"), module_dlerror ());
507 /* FIXME - libtool doesn't expose lt_dlerror strings for translation. */
509 module_dlerror (void)
511 const char *dlerror
= lt_dlerror ();
514 dlerror
= _("unknown error");
519 /* Close one reference to the module MODULE, and output to OBS any
520 information from the finish hook of the module. If no references
521 to MODULE remain, also remove all symbols and other memory
522 associated with the module. */
524 module_remove (m4
*context
, m4_module
*module
, m4_obstack
*obs
)
526 const lt_dlinfo
* info
;
530 bool last_reference
= false;
531 bool resident
= false;
532 m4_module_finish_func
* finish_func
;
534 assert (module
&& module
->handle
);
536 /* Be careful when closing myself. */
537 handle
= module
->handle
;
538 name
= m4_get_module_name (module
);
539 name
= xstrdup (name
? name
: MODULE_SELF_NAME
);
541 info
= lt_dlgetinfo (handle
);
542 resident
= info
->is_resident
;
544 /* Only do the actual close when the number of calls to close this
545 module is equal to the number of times it was opened. */
547 if (info
->ref_count
> 1)
549 xfprintf (stderr
, "module %s: now has %d libtool references.",
550 name
, info
->ref_count
- 1);
552 #endif /* DEBUG_MODULES */
554 if (module
->refcount
-- == 1)
556 /* Remove the table references only when ref_count is *exactly*
557 equal to 1. If module_close is called again on a
558 resident module after the references have already been
559 removed, we needn't try to remove them again! */
560 m4__symtab_remove_module_references (M4SYMTAB
, module
);
562 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
563 _("module %s: symbols unloaded"), name
);
564 last_reference
= true;
567 finish_func
= (m4_module_finish_func
*) lt_dlsym (handle
, FINISH_SYMBOL
);
570 finish_func (context
, module
, obs
);
572 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
573 _("module %s: finish hook called"), name
);
576 if (last_reference
&& resident
)
578 /* Special case when closing last reference to resident module -
579 we need to remove the association of the m4_module wrapper
580 with the dlhandle, because we are about to free the wrapper,
581 but the module will still show up in lt_dlhandle_iterate.
582 Still call lt_dlclose to reduce the ref count, but ignore the
583 failure about not closing a resident module. */
584 void *old
= lt_dlcaller_set_data (iface_id
, handle
, NULL
);
586 m4_error (context
, EXIT_FAILURE
, 0, NULL
,
587 _("unable to close module `%s': %s"), name
,
589 assert (old
== module
);
591 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
592 _("module %s: resident module not closed"), name
);
596 errors
= lt_dlclose (handle
);
597 /* Ignore the error expected if the module was resident. */
602 m4_debug_message (context
, M4_DEBUG_TRACE_MODULE
,
603 _("module %s: closed"), name
);
608 m4_error (context
, EXIT_FAILURE
, 0, NULL
,
609 _("cannot close module `%s': %s"), name
, module_dlerror ());
619 /* Below here are the accessor functions behind fast macros. Declare
620 them last, so the rest of the file can use the macros. */
622 /* Return the current refcount, or times that module MODULE has been
624 #undef m4_module_refcount
626 m4_module_refcount (const m4_module
*module
)
628 const lt_dlinfo
*info
;
630 info
= lt_dlgetinfo (module
->handle
);
632 assert (module
->refcount
<= info
->ref_count
);
633 return module
->refcount
;