#### 3.2.3.2 Examples of `malloc` ¶

If no more space is available, `malloc` returns a null pointer. You should check the value of every call to `malloc`. It is useful to write a subroutine that calls `malloc` and reports an error if the value is a null pointer, returning only if the value is nonzero. This function is conventionally called `xmalloc`. Here it is:

    void *
    xmalloc (size_t size)
    {
      void *value = malloc (size);
      if (value == 0)
        fatal ("virtual memory exhausted");
      return value;
    }

Here is a real example of using `malloc` (by way of `xmalloc`). The function `savestring` will copy a sequence of characters into a newly allocated null-terminated string:

    char *
    savestring (const char *ptr, size_t len)
    {
      char *value = xmalloc (len + 1);
      value[len] = '\0';
      return memcpy (value, ptr, len);
    }

The block that `malloc` gives you is guaranteed to be aligned so that it can hold any type of data. On GNU systems, the address is always a multiple of eight on 32-bit systems, and a multiple of 16 on 64-bit systems. Only rarely is any higher boundary (such as a page boundary) necessary; for those cases, use `aligned_alloc` or `posix_memalign` (see Allocating Aligned Memory Blocks).

Note that the memory located after the end of the block is likely to be in use for something else; perhaps a block already allocated by another call to `malloc`. If you attempt to treat the block as longer than you asked for it to be, you are liable to destroy the data that `malloc` uses to keep track of its blocks, or you may destroy the contents of another block. If you have already allocated a block and discover you want it to be bigger, use `realloc` (see Changing the Size of a Block).

Portability Notes:

- In the GNU C Library, a successful `malloc (0)` returns a non-null pointer to a newly allocated size-zero block; other implementations may return `NULL` instead. POSIX and the ISO C standard allow both behaviors.
- In the GNU C Library, a failed `malloc` call sets `errno`, but ISO C does not require this and non-POSIX implementations need not set `errno` when failing.
- In the GNU C Library, `malloc` always fails when size exceeds `PTRDIFF_MAX`, to avoid problems with programs that subtract pointers or use signed indexes. Other implementations may succeed in this case, leading to undefined behavior later.