doc/html/realloc.htm

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
   2
   3 <html>
   4 <head>
   5     <title>Using Wrapper Functions</title>
   6 </head>
   7
   8 <body>
   9     <div class="Section1">
  10         <h1>Using Wrapper Functions</h1>
  11
  12         <p>The propose of this document is to provide an example of
  13         how to use wrapper functions to create programs that are
  14         more robust and that Splint can check more
  15         effectively.&nbsp; The C standard library function realloc
  16         has complex semantics and is easy to use incorrectly.&nbsp;
  17         Still, it is a popular function, and we are frequently
  18         asked how to use Splint to check code that uses
  19         realloc.&nbsp; We hope to answer these questions in this
  20         section.&nbsp; Additionally, we hope this example will
  21         provide insight into other ways to work around some of the
  22         limitations of Splint&rsquo;s checking, and serve as a
  23         template for users wishing to create their own wrapper
  24         functions.</p>
  25
  26         <p>Splint cannot currently describe general functions where
  27         some of the attributes are dependent on one or more of the
  28         possible return values.&nbsp; Often, functions are defined
  29         to modify their outputs, and perhaps allocate storage, but
  30         can also return an error indication, in which case none of
  31         the modifications or allocations will take place.</p>
  32
  33         <p>One very common example of this is the C standard
  34         library function realloc( void *pointer, size_t
  35         size).&nbsp; When realloc succeeds, the pointer passed to
  36         it is no longer valid.&nbsp; The returned pointer points to
  37         available storage with the specified size, and the values
  38         are copied from the leading portion of the original storage
  39         indicated by the pointer passed to the function.&nbsp; When
  40         realloc returns a NULL pointer, and more than zero bytes
  41         were supposed to be allocated, no new storage has been
  42         allocated.&nbsp; The original pointer passed in is not
  43         deallocated and its contents are still accessible.&nbsp;
  44         (Under ANSI C '89 and later, malloc and realloc may return
  45         NULL if asked for zero bytes.&nbsp; In this case, realloc
  46         would release the old storage.)</p>
  47
  48         <p>If you use realloc, -usereleased can be used to suppress
  49         warnings.&nbsp; However, this may result in legitimate
  50         warnings for other errors being suppressed as well.&nbsp;
  51         If you don't mind crafting your code to work around
  52         Splint's quirks, you can isolate this difficult-to-describe
  53         behavior to a single function that's easy to verify by
  54         inspection, and use that function elsewhere.&nbsp; For
  55         example:</p>
  56
  57         &nbsp;&nbsp;&nbsp; /*@-usereleased@*/<br>
  58
  59         &nbsp;&nbsp;&nbsp; static /*@null@*/ void *<br>
  60
  61         &nbsp;&nbsp;&nbsp; grow_or_free (/*@only@*/ void *ptr,
  62         size_t newsize)<br>
  63
  64         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  65         /*@*/<br>
  66
  67         &nbsp;&nbsp;&nbsp; {<br>
  68
  69         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; void
  70         *newptr;<br>
  71
  72         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; newptr =
  73         realloc (ptr, newsize);<br>
  74
  75         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if (newptr ==
  76         NULL &amp;&amp; newsize != 0) {<br>
  77
  78
  79         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  80         /* Splint would complain,<br>
  81
  82
  83         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  84         but this is correct.&nbsp; */<br>
  85
  86
  87         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  88         free (ptr);<br>
  89
  90
  91         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  92         return NULL;<br>
  93
  94         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }<br>
  95
  96         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return
  97         newptr;<br>
  98
  99         &nbsp;&nbsp;&nbsp; }<br>
 100
 101         &nbsp;&nbsp;&nbsp; /*@=usereleased@*/<br>
 102
 103         <p>It would also be possible to use a function that always
 104         returns a valid pointer, and separately indicates whether
 105         it managed to change the size to that desired by the
 106         caller.</p>
 107     </div>
 108 </body>
 109 </html>