gdb/cleanups.h

   1 /* Cleanups.
   2    Copyright (C) 1986, 1988-2005, 2007-2012 Free Software Foundation, Inc.
   3
   4    This file is part of GDB.
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef CLEANUPS_H
  20 #define CLEANUPS_H
  21
  22 /* The cleanup list records things that have to be undone
  23    if an error happens (descriptors to be closed, memory to be freed, etc.)
  24    Each link in the chain records a function to call and an
  25    argument to give it.
  26
  27    Use make_cleanup to add an element to the cleanup chain.
  28    Use do_cleanups to do all cleanup actions back to a given
  29    point in the chain.  Use discard_cleanups to remove cleanups
  30    from the chain back to a given point, not doing them.
  31
  32    If the argument is pointer to allocated memory, then you need
  33    to additionally set the 'free_arg' member to a function that will
  34    free that memory.  This function will be called both when the cleanup
  35    is executed and when it's discarded.  */
  36
  37 struct cleanup
  38   {
  39     struct cleanup *next;
  40     void (*function) (void *);
  41     void (*free_arg) (void *);
  42     void *arg;
  43   };
  44
  45 /* NOTE: cagney/2000-03-04: This typedef is strictly for the
  46    make_cleanup function declarations below.  Do not use this typedef
  47    as a cast when passing functions into the make_cleanup() code.
  48    Instead either use a bounce function or add a wrapper function.
  49    Calling a f(char*) function with f(void*) is non-portable.  */
  50 typedef void (make_cleanup_ftype) (void *);
  51
  52 /* WARNING: The result of the "make cleanup" routines is not the intuitive
  53    choice of being a handle on the just-created cleanup.  Instead it is an
  54    opaque handle of the cleanup mechanism and represents all cleanups created
  55    from that point onwards.  */
  56
  57 extern struct cleanup *make_cleanup (make_cleanup_ftype *, void *);
  58
  59 extern struct cleanup *make_cleanup_dtor (make_cleanup_ftype *, void *,
  60                                           void (*dtor) (void *));
  61
  62 extern struct cleanup *make_final_cleanup (make_cleanup_ftype *, void *);
  63
  64 extern struct cleanup *make_my_cleanup (struct cleanup **,
  65                                         make_cleanup_ftype *, void *);
  66 extern struct cleanup *make_my_cleanup2 (struct cleanup **,
  67                                          make_cleanup_ftype *, void *,
  68                                          void (*free_arg) (void *));
  69
  70 /* A special value to pass to do_cleanups and do_final_cleanups
  71    to tell them to do all cleanups.  */
  72 #define ALL_CLEANUPS    ((struct cleanup *)0)
  73
  74 extern void do_cleanups (struct cleanup *);
  75 extern void do_final_cleanups (struct cleanup *);
  76
  77 extern void discard_cleanups (struct cleanup *);
  78 extern void discard_final_cleanups (struct cleanup *);
  79 extern void discard_my_cleanups (struct cleanup **, struct cleanup *);
  80
  81 extern struct cleanup *save_cleanups (void);
  82 extern struct cleanup *save_final_cleanups (void);
  83 extern struct cleanup *save_my_cleanups (struct cleanup **);
  84
  85 extern void restore_cleanups (struct cleanup *);
  86 extern void restore_final_cleanups (struct cleanup *);
  87 extern void restore_my_cleanups (struct cleanup **, struct cleanup *);
  88
  89 /* A no-op cleanup.
  90    This is useful when you want to establish a known reference point
  91    to pass to do_cleanups.  */
  92 extern void null_cleanup (void *);
  93
  94 #endif /* CLEANUPS_H */