basis/libc/libc-docs.factor

   1 USING: help.markup help.syntax alien destructors ;
   2 IN: libc
   3
   4 HELP: malloc
   5 { $values { "size" "a non-negative integer" } { "alien" c-ptr } }
   6 { $description "Allocates a block of " { $snippet "size" } " bytes from the operating system. The contents of the block are undefined." }
   7 { $errors "Throws an error if memory allocation failed." }
   8 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;
   9
  10 HELP: calloc
  11 { $values { "count" "a non-negative integer" } { "size" "a non-negative integer" } { "alien" c-ptr } }
  12 { $description "Allocates a block of " { $snippet "count * size" } " bytes from the operating system. The contents of the block are initially zero." }
  13 { $errors "Throws an error if memory allocation failed." }
  14 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;
  15
  16 HELP: realloc
  17 { $values { "alien" c-ptr } { "size" "a non-negative integer" } { "newalien" c-ptr } }
  18 { $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." }
  19 { $errors "Throws an error if memory allocation failed." }
  20 { $warning "Don't forget to deallocate the memory with a call to " { $link free } "." } ;
  21
  22 HELP: memcpy
  23 { $values { "dst" c-ptr } { "src" c-ptr } { "size" "a non-negative integer" } }
  24 { $description "Copies " { $snippet "size" } " bytes from " { $snippet "src" } " to " { $snippet "dst" } "." }
  25 { $warning "According to the BSD C library documentation, the behavior is undefined if the source and destination overlap." } ;
  26
  27 HELP: check-ptr
  28 { $values { "c-ptr" "an alien address, byte array, or " { $link f } } }
  29 { $description "Throws an error if the input is " { $link f } ". Otherwise the object remains on the data stack." } ;
  30
  31 HELP: free
  32 { $values { "alien" c-ptr } }
  33 { $description "Deallocates a block of memory allocated by " { $link malloc } ", " { $link calloc } " or " { $link realloc } "." } ;
  34
  35 HELP: (free)
  36 { $values { "alien" c-ptr } }
  37 { $description "Deallocates a block of memory allocated by an external C library." } ;
  38
  39 HELP: &free
  40 { $values { "alien" c-ptr } }
  41 { $description "Marks the block of memory for unconditional deallocation at the end of the current " { $link with-destructors } " scope." } ;
  42
  43 HELP: |free
  44 { $values { "alien" c-ptr } }
  45 { $description "Marks the object for deallocation in the event of an error at the end of the current " { $link with-destructors } " scope." } ;
  46
  47 ! Defined in alien-docs.factor
  48 ABOUT: "malloc"