core/compiler/alien/malloc.facts

   1 IN: libc
   2 USING: help ;
   3
   4 HELP: malloc ( size -- alien )
   5 { $values { "size" "a non-negative integer" } { "alien" "an alien address" } }
   6 { $description "Allocates a block of " { $snippet "size" } " bytes from the operating system. The contents of the block are undefined."
   7 $terpri
   8 "Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." }
   9 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;
  10
  11 HELP: calloc ( count size -- alien )
  12 { $values { "count" "a non-negative integer" } { "size" "a non-negative integer" } { "alien" "an alien address" } }
  13 { $description "Allocates a block of " { $snippet "count * size" } " bytes from the operating system. The contents of the block are initially zero."
  14 $terpri
  15 "Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." }
  16 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;
  17
  18 HELP: realloc ( alien size -- newalien )
  19 { $values { "alien" "an alien address" } { "size" "a non-negative integer" } { "newalien" "an alien address" } }
  20 { $description "Allocates a new block of " { $snippet "size" } " bytes from the operating system. The contents of " { $snippet "alien" } ", which itself must be a block previously returned by " { $link malloc } " or " { $link realloc } ", are copied into the new block, and the old block is freed."
  21 $terpri
  22 "Outputs " { $link f } " if memory allocation failed, so calls to this word should be followed by a call to " { $link check-ptr } "." }
  23 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;
  24
  25 HELP: memcpy ( dst src size -- )
  26 { $values { "dst" "an alien address" } { "src" "an alien address" } { "size" "a non-negative integer" } }
  27 { $description "Copies " { $snippet "size" } " bytes from " { $snippet "src" } " to " { $snippet "dst" } "." }
  28 { $warning "As per the BSD C library documentation, the behavior is undefined if the source and destination overlap." } ;
  29
  30 HELP: check-ptr
  31 { $values { "c-ptr" "an alien address, byte array, or " { $link f } } { "checked" "an alien address or byte array with non-zero address" } }
  32 { $description "Throws an error if the input is " { $link f } ". Otherwise the object remains on the data stack. This word should be used to check the return values of " { $link malloc } " and " { $link realloc } " before use." }
  33 { $error-description "Callers of " { $link malloc } " and " { $link realloc } " should use " { $link check-ptr } " to throw an error in the case of a memory allocation failure." } ;
  34
  35 HELP: free ( ptr -- )
  36 { $values { "ptr" "an alien address" } }
  37 { $description "Deallocates a block of memory allocated by " { $link malloc } ", " { $link calloc } " or " { $link realloc } "." } ;
  38
  39 HELP: with-malloc
  40 { $values { "n" "a positive integer" } { "quot" "a quotation with stack effect " { $snippet "( c-ptr -- )" } } }
  41 { $description "Allocates a zeroed block of " { $snippet "n" } " bytes and passes it to the quotation. When the quotation returns, the block is freed." } ;