--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">\r
+\r
+<html>\r
+<head>\r
+ <title>Using Wrapper Functions</title>\r
+</head>\r
+\r
+<body>\r
+ <div class="Section1">\r
+ <h1>Using Wrapper Functions</h1>\r
+\r
+ <p>The propose of this document is to provide an example of\r
+ how to use wrapper functions to create programs that are\r
+ more robust and that Splint can check more\r
+ effectively. The C standard library function realloc\r
+ has complex semantics and is easy to use incorrectly. \r
+ Still, it is a popular function, and we are frequently\r
+ asked how to use Splint to check code that uses\r
+ realloc. We hope to answer these questions in this\r
+ section. Additionally, we hope this example will\r
+ provide insight into other ways to work around some of the\r
+ limitations of Splint’s checking, and serve as a\r
+ template for users wishing to create their own wrapper\r
+ functions.</p>\r
+\r
+ <p>Splint cannot currently describe general functions where\r
+ some of the attributes are dependent on one or more of the\r
+ possible return values. Often, functions are defined\r
+ to modify their outputs, and perhaps allocate storage, but\r
+ can also return an error indication, in which case none of\r
+ the modifications or allocations will take place.</p>\r
+\r
+ <p>One very common example of this is the C standard\r
+ library function realloc( void *pointer, size_t\r
+ size). When realloc succeeds, the pointer passed to\r
+ it is no longer valid. The returned pointer points to\r
+ available storage with the specified size, and the values\r
+ are copied from the leading portion of the original storage\r
+ indicated by the pointer passed to the function. When\r
+ realloc returns a NULL pointer, and more than zero bytes\r
+ were supposed to be allocated, no new storage has been\r
+ allocated. The original pointer passed in is not\r
+ deallocated and its contents are still accessible. \r
+ (Under ANSI C '89 and later, malloc and realloc may return\r
+ NULL if asked for zero bytes. In this case, realloc\r
+ would release the old storage.)</p>\r
+\r
+ <p>If you use realloc, -usereleased can be used to suppress\r
+ warnings. However, this may result in legitimate\r
+ warnings for other errors being suppressed as well. \r
+ If you don't mind crafting your code to work around\r
+ Splint's quirks, you can isolate this difficult-to-describe\r
+ behavior to a single function that's easy to verify by\r
+ inspection, and use that function elsewhere. For\r
+ example:</p>\r
+\r
+ /*@-usereleased@*/<br>\r
+\r
+ static /*@null@*/ void *<br>\r
+\r
+ grow_or_free (/*@only@*/ void *ptr,\r
+ size_t newsize)<br>\r
+\r
+ \r
+ /*@*/<br>\r
+\r
+ {<br>\r
+\r
+ void\r
+ *newptr;<br>\r
+\r
+ newptr =\r
+ realloc (ptr, newsize);<br>\r
+\r
+ if (newptr ==\r
+ NULL && newsize != 0) {<br>\r
+\r
+ \r
+ \r
+ /* Splint would complain,<br>\r
+\r
+ \r
+ \r
+ but this is correct. */<br>\r
+\r
+ \r
+ \r
+ free (ptr);<br>\r
+\r
+ \r
+ \r
+ return NULL;<br>\r
+\r
+ }<br>\r
+\r
+ return\r
+ newptr;<br>\r
+\r
+ }<br>\r
+\r
+ /*@=usereleased@*/<br>\r
+\r
+ <p>It would also be possible to use a function that always\r
+ returns a valid pointer, and separately indicates whether\r
+ it managed to change the size to that desired by the\r
+ caller.</p>\r
+ </div>\r
+</body>\r
+</html>\r
andersk / splint.git / commitdiff
