newlib/libc/stdlib/malloc.c

   1 /* VxWorks provides its own version of malloc, and we can't use this
   2    one because VxWorks does not provide sbrk.  So we have a hook to
   3    not compile this code.  */
   4
   5 /* The routines here are simple cover fns to the routines that do the real
   6    work (the reentrant versions).  */
   7 /* FIXME: Does the warning below (see WARNINGS) about non-reentrancy still
   8    apply?  A first guess would be "no", but how about reentrancy in the *same*
   9    thread?  */
  10
  11 #ifdef MALLOC_PROVIDED
  12
  13 int _dummy_malloc = 1;
  14
  15 #else
  16
  17 /*
  18 FUNCTION
  19 <<malloc>>, <<realloc>>, <<free>>---manage memory
  20
  21 INDEX
  22         malloc
  23 INDEX
  24         realloc
  25 INDEX
  26         reallocf
  27 INDEX
  28         free
  29 INDEX
  30         memalign
  31 INDEX
  32         malloc_usable_size
  33 INDEX
  34         _malloc_r
  35 INDEX
  36         _realloc_r
  37 INDEX
  38         _reallocf_r
  39 INDEX
  40         _free_r
  41 INDEX
  42         _memalign_r
  43 INDEX
  44         _malloc_usable_size_r
  45
  46 SYNOPSIS
  47         #include <stdlib.h>
  48         void *malloc(size_t <[nbytes]>);
  49         void *realloc(void *<[aptr]>, size_t <[nbytes]>);
  50         void *reallocf(void *<[aptr]>, size_t <[nbytes]>);
  51         void free(void *<[aptr]>);
  52
  53         void *memalign(size_t <[align]>, size_t <[nbytes]>);
  54
  55         size_t malloc_usable_size(void *<[aptr]>);
  56
  57         void *_malloc_r(void *<[reent]>, size_t <[nbytes]>);
  58         void *_realloc_r(void *<[reent]>,
  59                          void *<[aptr]>, size_t <[nbytes]>);
  60         void *_reallocf_r(void *<[reent]>,
  61                          void *<[aptr]>, size_t <[nbytes]>);
  62         void _free_r(void *<[reent]>, void *<[aptr]>);
  63
  64         void *_memalign_r(void *<[reent]>,
  65                           size_t <[align]>, size_t <[nbytes]>);
  66
  67         size_t _malloc_usable_size_r(void *<[reent]>, void *<[aptr]>);
  68
  69 DESCRIPTION
  70 These functions manage a pool of system memory.
  71
  72 Use <<malloc>> to request allocation of an object with at least
  73 <[nbytes]> bytes of storage available.  If the space is available,
  74 <<malloc>> returns a pointer to a newly allocated block as its result.
  75
  76 If you already have a block of storage allocated by <<malloc>>, but
  77 you no longer need all the space allocated to it, you can make it
  78 smaller by calling <<realloc>> with both the object pointer and the
  79 new desired size as arguments.  <<realloc>> guarantees that the
  80 contents of the smaller object match the beginning of the original object.
  81
  82 Similarly, if you need more space for an object, use <<realloc>> to
  83 request the larger size; again, <<realloc>> guarantees that the
  84 beginning of the new, larger object matches the contents of the
  85 original object.
  86
  87 When you no longer need an object originally allocated by <<malloc>>
  88 or <<realloc>> (or the related function <<calloc>>), return it to the
  89 memory storage pool by calling <<free>> with the address of the object
  90 as the argument.  You can also use <<realloc>> for this purpose by
  91 calling it with <<0>> as the <[nbytes]> argument.
  92
  93 The <<reallocf>> function behaves just like <<realloc>> except if the
  94 function is required to allocate new storage and this fails.  In this
  95 case <<reallocf>> will free the original object passed in whereas
  96 <<realloc>> will not.
  97
  98 The <<memalign>> function returns a block of size <[nbytes]> aligned
  99 to a <[align]> boundary.  The <[align]> argument must be a power of
 100 two.
 101
 102 The <<malloc_usable_size>> function takes a pointer to a block
 103 allocated by <<malloc>>.  It returns the amount of space that is
 104 available in the block.  This may or may not be more than the size
 105 requested from <<malloc>>, due to alignment or minimum size
 106 constraints.
 107
 108 The alternate functions <<_malloc_r>>, <<_realloc_r>>, <<_reallocf_r>>,
 109 <<_free_r>>, <<_memalign_r>>, and <<_malloc_usable_size_r>> are reentrant
 110 versions.  The extra argument <[reent]> is a pointer to a reentrancy structure.
 111
 112 If you have multiple threads of execution which may call any of these
 113 routines, or if any of these routines may be called reentrantly, then
 114 you must provide implementations of the <<__malloc_lock>> and
 115 <<__malloc_unlock>> functions for your system.  See the documentation
 116 for those functions.
 117
 118 These functions operate by calling the function <<_sbrk_r>> or
 119 <<sbrk>>, which allocates space.  You may need to provide one of these
 120 functions for your system.  <<_sbrk_r>> is called with a positive
 121 value to allocate more space, and with a negative value to release
 122 previously allocated space if it is no longer required.
 123 @xref{Stubs}.
 124
 125 RETURNS
 126 <<malloc>> returns a pointer to the newly allocated space, if
 127 successful; otherwise it returns <<NULL>>.  If your application needs
 128 to generate empty objects, you may use <<malloc(0)>> for this purpose.
 129
 130 <<realloc>> returns a pointer to the new block of memory, or <<NULL>>
 131 if a new block could not be allocated.  <<NULL>> is also the result
 132 when you use `<<realloc(<[aptr]>,0)>>' (which has the same effect as
 133 `<<free(<[aptr]>)>>').  You should always check the result of
 134 <<realloc>>; successful reallocation is not guaranteed even when
 135 you request a smaller object.
 136
 137 <<free>> does not return a result.
 138
 139 <<memalign>> returns a pointer to the newly allocated space.
 140
 141 <<malloc_usable_size>> returns the usable size.
 142
 143 PORTABILITY
 144 <<malloc>>, <<realloc>>, and <<free>> are specified by the ANSI C
 145 standard, but other conforming implementations of <<malloc>> may
 146 behave differently when <[nbytes]> is zero.
 147
 148 <<memalign>> is part of SVR4.
 149
 150 <<malloc_usable_size>> is not portable.
 151
 152 Supporting OS subroutines required: <<sbrk>>.  */
 153
 154 #include <_ansi.h>
 155 #include <reent.h>
 156 #include <stdlib.h>
 157 #include <malloc.h>
 158
 159 #ifndef _REENT_ONLY
 160
 161 void *
 162 malloc (size_t nbytes)          /* get a block */
 163 {
 164   return _malloc_r (_REENT, nbytes);
 165 }
 166
 167 void
 168 free (void *aptr)
 169 {
 170   _free_r (_REENT, aptr);
 171 }
 172
 173 #endif
 174
 175 #endif /* ! defined (MALLOC_PROVIDED) */