home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / cat3 / realloc.3 < prev    next >
Encoding:
Text File  |  1993-03-03  |  3.5 KB  |  133 lines
  1.  
  2.  
  3.  
  4. MALLOC(3)           MINTLIB LIBRARY FUNCTIONS           MALLOC(3)
  5.  
  6.  
  7. N✓NA✓AM✓ME✓E
  8.        malloc, free, realloc, calloc, alloca - memory allocator
  9.  
  10. S✓SY✓YN✓NO✓OP✓PS✓SI✓IS✓S
  11.        #include <stdlib.h>
  12.  
  13.        void *malloc(size_t size);
  14.  
  15.        void free(void *ptr);
  16.  
  17.        void *realloc(void *ptr, size_t size);
  18.  
  19.        void *calloc(size_t num_elems, size_t elem_size);
  20.  
  21.        void *alloca(size_t size);
  22.  
  23. D✓DE✓ES✓SC✓CR✓RI✓IP✓PT✓TI✓IO✓ON✓N
  24.        These routines provide a general-purpose memory allocation
  25.        package. They maintain a table of free  blocks  for  effi-
  26.        cient  allocation  and  coalescing  of  free storage. When
  27.        there is no suitable space already  free,  the  allocation
  28.        routines call Malloc to get more memory from the system.
  29.  
  30.        Each of the allocation routines returns a pointer to space
  31.        suitably aligned for storage of any type of  object.  Each
  32.        returns  a NULL pointer if the request cannot be completed
  33.        or if an area of size zero is requested.
  34.  
  35.        malloc returns a pointer to  a  block  of  at  least  size
  36.        bytes.
  37.  
  38.        free  releases  a previously allocated block. Its argument
  39.        is a pointer to a block previously  allocated  by  malloc,
  40.        calloc or realloc.
  41.  
  42.        realloc  changes  the size of a block referenced to by ptr
  43.        to size bytes and  returns  a  pointer  to  the  (possibly
  44.        moved)  block.  The  contents  will be unchanged up to the
  45.        lesser of the new and old sizes.  If  unable  to  honor  a
  46.        reallocation  request,  realloc  leaves  it first argument
  47.        unaltered.  Using realloc with a block freed before is  an
  48.        error.
  49.  
  50.        realloc(NULL,  size)  is  the same as malloc(size).  real-
  51.        loc(ptr, 0) is the same as free(ptr).
  52.  
  53.        calloc uses malloc to  allocate  space  for  an  array  of
  54.        num_elems  elements  of  size  elem_size,  initialises the
  55.        space to zeros, and returns a pointer to  the  initialised
  56.        block.
  57.  
  58.        alloca allocates size bytes of space in the stack frame of
  59.        the caller, and returns a pointer to the allocated  block.
  60.        This  temporary  space  is  automatically  freed  when the
  61.  
  62.  
  63.  
  64. MiNT docs 0.1              3 March 1993                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. MALLOC(3)           MINTLIB LIBRARY FUNCTIONS           MALLOC(3)
  71.  
  72.  
  73.        caller returns. Note that if the allocated block is beyond
  74.        the  current  stack limit, the resulting behavior is unde-
  75.        fined.
  76.  
  77. R✓RE✓ET✓TU✓UR✓RN✓N V✓VA✓AL✓LU✓UE✓ES✓S
  78.        On success, malloc, calloc, realloc and  alloca  return  a
  79.        pointer  to space suitably aligned for storage of any type
  80.        of object. On failure, they return NULL.
  81.  
  82. S✓SE✓EE✓E A✓AL✓LS✓SO✓O
  83.        M✓Ma✓al✓ll✓lo✓oc✓c(✓(2✓2)✓),✓, g✓ge✓et✓tr✓rl✓li✓im✓mi✓it✓t(✓(3✓3)✓)
  84.  
  85. W✓WA✓AR✓RN✓NI✓IN✓NG✓GS✓S
  86.        On UN*X machines, malloc and  realloc  return  a  non-NULL
  87.        pointer  if  size  is  0,  and  calloc  returns a non-NULL
  88.        pointer if num_elems or elem_size is 0. The mintlibs  fol-
  89.        low  the  ANSI-C standard and return NULL in these circum-
  90.        stances.
  91.  
  92.        alloca is machine-, compiler-, and most  of  all,  system-
  93.        dependent. Its use is strongly discouraged.
  94.  
  95. N✓NO✓OT✓TE✓ES✓S
  96.        GNU software is uncommonly fond of alloca.
  97.  
  98.        To  use  alloca  with Pure-C in the current version of the
  99.        mintlibs, the caller must be compiled with the  -S  option
  100.        set or the program will crash.
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130. MiNT docs 0.1              3 March 1993                         2
  131.  
  132.  
  133.