Revamp malloc.3 by reordering the sections and rewriting parts.

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)

0 files changed, 0 insertions, 0 deletions