gdb/common/cleanups.c - gdb

Global variables defined

Data types defined

Functions defined

Macros defined

Source code

  1. /* Cleanup routines for GDB, the GNU debugger.

  3.    Copyright (C) 1986-2015 Free Software Foundation, Inc.

  5.    This file is part of GDB.

  7.    This program 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.    This program 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/>.  */

  20. #include "common-defs.h"
  21. #include "cleanups.h"

  23. /* The cleanup list records things that have to be undone
  24.    if an error happens (descriptors to be closed, memory to be freed, etc.)
  25.    Each link in the chain records a function to call and an
  26.    argument to give it.

  28.    Use make_cleanup to add an element to the cleanup chain.
  29.    Use do_cleanups to do all cleanup actions back to a given
  30.    point in the chain.  Use discard_cleanups to remove cleanups
  31.    from the chain back to a given point, not doing them.

  33.    If the argument is pointer to allocated memory, then you need
  34.    to additionally set the 'free_arg' member to a function that will
  35.    free that memory.  This function will be called both when the cleanup
  36.    is executed and when it's discarded.  */

  38. ‌struct cleanup
  39. {
  40.   struct cleanup *next;
  41.   void (*function) (void *);
  42.   void (*free_arg) (void *);
  43.   void *arg;
  44. };

  46. /* Used to mark the end of a cleanup chain.
  47.    The value is chosen so that it:
  48.    - is non-NULL so that make_cleanup never returns NULL,
  49.    - causes a segv if dereferenced
  50.      [though this won't catch errors that a value of, say,
  51.      ((struct cleanup *) -1) will]
  52.    - displays as something useful when printed in gdb.
  53.    This is const for a bit of extra robustness.
  54.    It is initialized to coax gcc into putting it into .rodata.
  55.    All fields are initialized to survive -Wextra.  */
  56. ‌static const struct cleanup sentinel_cleanup = { 0, 0, 0, 0 };

  58. /* Handy macro to use when referring to sentinel_cleanup.  */
  59. ‌#define SENTINEL_CLEANUP ((struct cleanup *) &sentinel_cleanup)

  61. /* Chain of cleanup actions established with make_cleanup,
  62.    to be executed if an error happens.  */
  63. ‌static struct cleanup *cleanup_chain = SENTINEL_CLEANUP;

  65. /* Chain of cleanup actions established with make_final_cleanup,
  66.    to be executed when gdb exits.  */
  67. ‌static struct cleanup *final_cleanup_chain = SENTINEL_CLEANUP;

  69. /* Main worker routine to create a cleanup.
  70.    PMY_CHAIN is a pointer to either cleanup_chain or final_cleanup_chain.
  71.    FUNCTION is the function to call to perform the cleanup.
  72.    ARG is passed to FUNCTION when called.
  73.    FREE_ARG, if non-NULL, is called after the cleanup is performed.

  75.    The result is a pointer to the previous chain pointer
  76.    to be passed later to do_cleanups or discard_cleanups.  */

  78. static struct cleanup *
  79. ‌make_my_cleanup2 (struct cleanup **pmy_chain, make_cleanup_ftype *function,
  80.                   void *arg,  void (*free_arg) (void *))
  81. {
  82.   struct cleanup *new
  83.     = (struct cleanup *) xmalloc (sizeof (struct cleanup));
  84.   struct cleanup *old_chain = *pmy_chain;

  86.   new->next = *pmy_chain;
  87.   new->function = function;
  88.   new->free_arg = free_arg;
  89.   new->arg = arg;
  90.   *pmy_chain = new;

  92.   gdb_assert (old_chain != NULL);
  93.   return old_chain;
  94. }

  96. /* Worker routine to create a cleanup without a destructor.
  97.    PMY_CHAIN is a pointer to either cleanup_chain or final_cleanup_chain.
  98.    FUNCTION is the function to call to perform the cleanup.
  99.    ARG is passed to FUNCTION when called.

  101.    The result is a pointer to the previous chain pointer
  102.    to be passed later to do_cleanups or discard_cleanups.  */

  104. static struct cleanup *
  105. ‌make_my_cleanup (struct cleanup **pmy_chain, make_cleanup_ftype *function,
  106.                  void *arg)
  107. {
  108.   return make_my_cleanup2 (pmy_chain, function, arg, NULL);
  109. }

  111. /* Add a new cleanup to the cleanup_chain,
  112.    and return the previous chain pointer
  113.    to be passed later to do_cleanups or discard_cleanups.
  114.    Args are FUNCTION to clean up with, and ARG to pass to it.  */

  116. struct cleanup *
  117. ‌make_cleanup (make_cleanup_ftype *function, void *arg)
  118. {
  119.   return make_my_cleanup (&cleanup_chain, function, arg);
  120. }

  122. /* Same as make_cleanup except also includes DTOR, a destructor to free ARG.
  123.    DTOR is invoked when the cleanup is performed or when it is discarded.  */

  125. struct cleanup *
  126. ‌make_cleanup_dtor (make_cleanup_ftype *function, void *arg,
  127.                    make_cleanup_dtor_ftype *dtor)
  128. {
  129.   return make_my_cleanup2 (&cleanup_chain,
  130.                            function, arg, dtor);
  131. }

  133. /* Same as make_cleanup except the cleanup is added to final_cleanup_chain.  */

  135. struct cleanup *
  136. ‌make_final_cleanup (make_cleanup_ftype *function, void *arg)
  137. {
  138.   return make_my_cleanup (&final_cleanup_chain, function, arg);
  139. }

  141. /* Worker routine to perform cleanups.
  142.    PMY_CHAIN is a pointer to either cleanup_chain or final_cleanup_chain.
  143.    OLD_CHAIN is the result of a "make" cleanup routine.
  144.    Cleanups are performed until we get back to the old end of the chain.  */

  146. static void
  147. ‌do_my_cleanups (struct cleanup **pmy_chain,
  148.                 struct cleanup *old_chain)
  149. {
  150.   struct cleanup *ptr;

  152.   while ((ptr = *pmy_chain) != old_chain)
  153.     {
  154.       *pmy_chain = ptr->next;        /* Do this first in case of recursion.  */
  155.       (*ptr->function) (ptr->arg);
  156.       if (ptr->free_arg)
  157.         (*ptr->free_arg) (ptr->arg);
  158.       xfree (ptr);
  159.     }
  160. }

  162. /* Return a value that can be passed to do_cleanups, do_final_cleanups to
  163.    indicate perform all cleanups.  */

  165. struct cleanup *
  166. ‌all_cleanups (void)
  167. {
  168.   return SENTINEL_CLEANUP;
  169. }

  171. /* Discard cleanups and do the actions they describe
  172.    until we get back to the point OLD_CHAIN in the cleanup_chain.  */

  174. void
  175. ‌do_cleanups (struct cleanup *old_chain)
  176. {
  177.   do_my_cleanups (&cleanup_chain, old_chain);
  178. }

  180. /* Discard cleanups and do the actions they describe
  181.    until we get back to the point OLD_CHAIN in the final_cleanup_chain.  */

  183. void
  184. ‌do_final_cleanups (struct cleanup *old_chain)
  185. {
  186.   do_my_cleanups (&final_cleanup_chain, old_chain);
  187. }

  189. /* Main worker routine to discard cleanups.
  190.    PMY_CHAIN is a pointer to either cleanup_chain or final_cleanup_chain.
  191.    OLD_CHAIN is the result of a "make" cleanup routine.
  192.    Cleanups are discarded until we get back to the old end of the chain.  */

  194. static void
  195. ‌discard_my_cleanups (struct cleanup **pmy_chain,
  196.                      struct cleanup *old_chain)
  197. {
  198.   struct cleanup *ptr;

  200.   while ((ptr = *pmy_chain) != old_chain)
  201.     {
  202.       *pmy_chain = ptr->next;
  203.       if (ptr->free_arg)
  204.         (*ptr->free_arg) (ptr->arg);
  205.       xfree (ptr);
  206.     }
  207. }

  209. /* Discard cleanups, not doing the actions they describe,
  210.    until we get back to the point OLD_CHAIN in the cleanup chain.  */

  212. void
  213. ‌discard_cleanups (struct cleanup *old_chain)
  214. {
  215.   discard_my_cleanups (&cleanup_chain, old_chain);
  216. }

  218. /* Discard final cleanups, not doing the actions they describe,
  219.    until we get back to the point OLD_CHAIN in the final cleanup chain.  */

  221. void
  222. ‌discard_final_cleanups (struct cleanup *old_chain)
  223. {
  224.   discard_my_cleanups (&final_cleanup_chain, old_chain);
  225. }

  227. /* Main worker routine to save cleanups.
  228.    PMY_CHAIN is a pointer to either cleanup_chain or final_cleanup_chain.
  229.    The chain is emptied and the result is a pointer to the old chain.  */

  231. static struct cleanup *
  232. ‌save_my_cleanups (struct cleanup **pmy_chain)
  233. {
  234.   struct cleanup *old_chain = *pmy_chain;

  236.   *pmy_chain = SENTINEL_CLEANUP;
  237.   return old_chain;
  238. }

  240. /* Set the cleanup_chain to 0, and return the old cleanup_chain.  */

  242. struct cleanup *
  243. ‌save_cleanups (void)
  244. {
  245.   return save_my_cleanups (&cleanup_chain);
  246. }

  248. /* Set the final_cleanup_chain to 0, and return the old
  249.    final_cleanup_chain.  */

  251. struct cleanup *
  252. ‌save_final_cleanups (void)
  253. {
  254.   return save_my_cleanups (&final_cleanup_chain);
  255. }

  257. /* Main worker routine to save cleanups.
  258.    PMY_CHAIN is a pointer to either cleanup_chain or final_cleanup_chain.
  259.    The chain is restored from CHAIN.  */

  261. static void
  262. ‌restore_my_cleanups (struct cleanup **pmy_chain, struct cleanup *chain)
  263. {
  264.   if (*pmy_chain != SENTINEL_CLEANUP)
  265.     internal_warning (__FILE__, __LINE__,
  266.                       _("restore_my_cleanups has found a stale cleanup"));

  268.   *pmy_chain = chain;
  269. }

  271. /* Restore the cleanup chain from a previously saved chain.  */

  273. void
  274. ‌restore_cleanups (struct cleanup *chain)
  275. {
  276.   restore_my_cleanups (&cleanup_chain, chain);
  277. }

  279. /* Restore the final cleanup chain from a previously saved chain.  */

  281. void
  282. ‌restore_final_cleanups (struct cleanup *chain)
  283. {
  284.   restore_my_cleanups (&final_cleanup_chain, chain);
  285. }

  287. /* Provide a known function that does nothing, to use as a base for
  288.    a possibly long chain of cleanups.  This is useful where we
  289.    use the cleanup chain for handling normal cleanups as well as dealing
  290.    with cleanups that need to be done as a result of a call to error().
  291.    In such cases, we may not be certain where the first cleanup is, unless
  292.    we have a do-nothing one to always use as the base.  */

  294. void
  295. ‌null_cleanup (void *arg)
  296. {
  297. }