alloc.html (3864B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the alloc library interface</title> 7 <meta name="Description" content="skalibs: the alloc library interface" /> 8 <meta name="Keywords" content="skalibs c unix alloc library libstddjb" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>alloc</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/alloc.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>alloc</tt> is the skalibs heap memory manager. It's actually a 32 wrapper for the 33 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/malloc.html">malloc()</a> 34 series of functions; it unifies a few system-dependent <tt>malloc</tt> 35 behaviours. It's also the API to implement and preload if for some 36 reason you need to plug in your own allocator: replacing <tt>alloc()</tt> 37 is much easier than replacing <tt>malloc()</tt> safely. 38 </p> 39 40 <p> 41 <strong> As a general rule, you should not be using the <tt>alloc</tt> 42 interface directly. </strong> Allocating and freeing individual cells 43 in the heap is a recipe for heap fragmentation, as well as cell 44 tracking nightmares leading to memory leaks. <strong> You should use 45 the higher-level <a href="stralloc.html">stralloc</a> and 46 <a href="genalloc.html">genalloc</a> interfaces </strong> to handle dynamic 47 arrays of objects. 48 </p> 49 50 <p> 51 C's lack of automatic management of heap memory is not a drawback: it's 52 a feature of the language. It allows for code that is one or two orders 53 of magnitude faster than the equivalent in a higher-level language, 54 and very low on resources consumption. However, it requires more attention 55 from the programmer. Good APIs can significantly reduce the difficulty of 56 keeping track of every heap-allocated cell, and every smart programmer 57 should favor them over basic interfaces like <tt>malloc()</tt>. 58 </p> 59 60 <p> 61 <tt>alloc</tt> is used internally by skalibs to implement 62 <a href="stralloc.html">stralloc</a>, and nowhere else. 63 </p> 64 65 <h2> Functions </h2> 66 67 <p> 68 <code> void *alloc (size_t len) </code> <br /> 69 Allocates a block of <em>len</em> bytes in the heap and returns a pointer 70 to the start of the block (or NULL if it failed). 71 If <em>len</em> is 0, the function returns a unique pointer that 72 cannot be written to, but that is <em>not null</em>. Note that this is 73 different from the required C99 behaviour for <tt>malloc()</tt>. 74 </p> 75 76 <p> 77 <code> void alloc_free (void *p) </code> <br /> 78 Frees the block of heap memory pointed to by <em>p</em>. 79 </p> 80 81 <p> 82 <code> int alloc_realloc (char **p, size_t newlen) </code> <br /> 83 Redimension the block of heap memory pointed to by *<em>p</em> to 84 <em>newlen</em> bytes. The block may have to be moved, in which case 85 *<em>p</em> will be modified. Normally returns 1; if an error occurred, 86 returns 0 and sets errno, and neither *<em>p</em> nor its contents are 87 modified. Note that <em>p</em> must be a pointer to a <tt>char *</tt>, 88 because polymorphism isn't possible here (for reasons that have to do 89 with pointer representation in C). 90 </p> 91 92 <p> 93 <code> int alloc_re (char **p, size_t oldlen, size_t newlen) </code> <br /> 94 Legacy interface for reallocation. It works like <tt>alloc_realloc</tt>, 95 except that the original block length must be provided as the <em>oldlen</em> 96 argument. 97 </p> 98 99 </body> 100 </html>