The old man page had a lot of useful information, but it was all mixed
together which made it difficult to reference.  The main theme in this
commit is that the sections are more focused:
* DESCRIPTION describes the overall behavior
* RETURN VALUES describes what it may return (including implementation
defined values)
* EXAMPLES shows why we recently started an audit on malloc and realloc
usage in the tree.
* Added CAVEATS which describes what is implementation defined, gotchas
and security implications of misusing these functions
* Added IDIOMS which describes how these functions should or
should not be used
The MALLOC_OPTIONS section was left unchanged.  Function names were
added to DIAGNOSTICS and STANDARDS.  The MALLOC_OPTIONS and DIAGNOSTICS
sections were pushed down in the page so more pertinent information is
higher up.
This has gone through several revisions thanks to input from deraadt@
and schwarze@.  Ingo also helped with some of the mandoc formatting.
OK schwarze@ (as far as it is a good starting point and the code
snippets look ok)