Standard C Library Functions
====================================

Functions from the C language specification.


malloc
---------

Creates a fresh allocation on the heap.  The Grackle allocator always
succeeds, returning a non-null pointer.

::

   void* malloc( size_t size )

``malloc`` allocates an object of ``size`` bytes in the heap and
returns a pointer to he beginning of the object.  In all cases,
``malloc`` will succeed and return an non-null pointer distinct from
all previously-returned pointers.  In the special case that 0 bytes
are requested, a valid non-null pointer is nonetheless returned; but this
pointer must not be used to read or write memory.

The ``size`` argument to ``malloc`` may be a symbolic value.

calloc
-------

Create a fresh allocation on the heap and set every byte in the object
to the 0 value.  Except as explicitly listed below, ``calloc``
will always succeed, returning a non-null pointer.

::

   void* calloc( size_t count, size_t size )

``calloc`` function contiguously allocates enough space for ``count``
objects that are ``size`` bytes of memory each and
returns a pointer to the allocated memory.
The allocated memory is filled with bytes of value zero.

``calloc`` will fail if the multiplication of ``count`` with ``size`` overflows.
If either ``count`` or ``size`` is zero, the result is identical to
calling ``malloc`` with size 0.  Similar to ``memset``, the arguments
to ``calloc`` must be concrete; symbolic arguments will cause the call
to fail.


free
--------

Deallocate memory previously allocated by ``malloc`` or ``calloc``.

::

   void free( void* ptr )

``free`` deallocates heap objects obtained from ``malloc`` or
``calloc``.  This function succeeds and does nothing if passed
the null pointer.  Otherwise, the argument must be a live (i.e., not
previously deallocated) pointer equal to the return value of a
previous call to ``malloc`` or ``calloc``.


memset
----------

Fill a region of memory with a constant byte value.

::

   void* memset( void* b, int c, size_t len )

``memset`` writes ``len`` bytes of value ``c`` (converted to an
unsigned char) to the string ``b``.  *NOTE* that the ``len``
argument cannot be a symbolic value, although the ``b`` and ``c``
may be symbolic.  This call will fail if any byte
in the indicated range falls outside the allocation to which ``b`` belongs.
The return value is the first argument, ``b``.

memcpy
--------

Copy a region of memory to another disjoint region of memory.

::

   void* memcpy( void* dst, void* src, size_t n )

Copy ``n`` bytes from the region pointed to by ``src`` into the
region pointed to by ``src``.  These two regions are required to be
disjoint; otherwise this call will fail.  The return value of this
function is the first argument ``dst``.

All arguments to this function may be symbolic.

memmove
---------

Copy a region of memory to another, possibly overlapping, region of
memory.

::

   void* memmove( void* dst, void* src, size_t n )

Copy ``n`` bytes from the region pointed to by ``src`` into the
region pointed to by ``src``.  These two regions are allowed to
overlap; in which case the behavior is equivalent to first copying
from ``src`` to a disjoint temporary buffer and then copying this
buffer into ``dst``.  The return value of this function
is the first argument, ``dst``.

All arguments to this function may be symbolic.

printf
--------

Format output and print it on the standard output stream.

::

   int printf( const char* format, ... )

Format the given arguments according to the ``format`` string and
print the result on standard out.  Our ``printf`` is a reasonably
complete implementation of the C standard ``printf`` (caveats below);
see the standard man page for ``printf`` for details.  The
return value of ``printf`` is the number characters printed.

The following features are *not* currently supported:

- The ``a`` and ``A`` floating-point conversions.
- The wide character/string conversions, ``%lc`` and ``%ls``.
- The ``*`` and ``*m$`` precision specifiers that read precision
  from an argument.
- Any locale-specific behavior.

Note that the format string and any strings printed  using a ``%s``
conversion are required to be concrete.  Symbolic integers and
floating-point values will simply be formatted as a sequence of '?'
symbols.