Revert last commit due to changed semantics found by make release.
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)
make RETURN VALUES more concise
and fix two instances of "new sentence, new line" while here
feedback and ok jmc@, ok doug@
s_client: don't call shutdown on a non-existent socket descriptor.

from Dmitry Eremin-Solenikov <dbaryshkov@gmail.com>
ok beck@, deraadt@
SSL: Fix memory leak in d2i_SSL_SESSION.

Modified version of patch from Dmitry Eremin-Solenikov.

==28360== 98 bytes in 2 blocks are definitely lost in loss record 7 of 7
==28360==    at 0x402AC54: realloc (in /usr/lib/valgrind/vgpreload_memcheck-x86-linux.so)
==28360==    by 0x40E2D2C: ASN1_STRING_set (asn1_lib.c:393)
==28360==    by 0x40EC22C: asn1_ex_c2i (tasn_dec.c:959)
==28360==    by 0x40EC632: asn1_d2i_ex_primitive (tasn_dec.c:824)
==28360==    by 0x40ED2E6: ASN1_item_ex_d2i (tasn_dec.c:230)
==28360==    by 0x40ED421: ASN1_item_d2i (tasn_dec.c:133)
==28360==    by 0x40F0335: d2i_ASN1_OCTET_STRING (tasn_typ.c:75)
==28360==    by 0x405FD6D: d2i_SSL_SESSION (ssl_asn1.c:367)
==28360==    by 0x405DD6E: ssl3_send_newsession_ticket (s3_srvr.c:2743)
==28360==    by 0x405EA48: ssl3_accept (s3_srvr.c:665)
==28360==    by 0x4067C34: SSL_accept (ssl_lib.c:922)
==28360==    by 0x404E97B: ssl23_get_client_hello (s23_srvr.c:573)

ok miod@ beck@
digests: *_LONG_LOG2 is not used, stop talking about it.

Modified patch from Dmitry Eremin-Solenikov

leave the sole public define in ripemd.h

ok deraadt@ miod@
List extensions in the STANDARDS section, replacing some text below CAVEATS.
Remove excessive technicalities on zero-sized objects as suggested by deraadt@.
contributions and ok deraadt@, ok jmc@ on an earlier version
Avoid writing in second person in malloc.3

ok deraadt@
Use arc4random_buf() instead of RAND_bytes() or RAND_pseudo_bytes().

arc4random_buf() is guaranteed to always succeed - it is worth noting
that a number of the replaced function calls were already missing return
value checks.

ok deraadt@
None of these need <openssl/rand.h>
Use arc4random_buf() instead of RAND_bytes() or RAND_pseudo_bytes() (most
with unchecked return values).
None of these need <openssl/rand.h>
Use arc4random_buf() instead of RAND(_pseudo)?_bytes().

ok bcook@
Place most of the RAND_* functions under #ifndef LIBRESSL_INTERNAL (some
are still needed for the engine). Our code should use arc4random instead.
#undef LIBRESSL_INTERNAL for the RAND_pseudo_bytes() test.
Avoid a NULL pointer dereference that can be triggered by
SSL3_RT_HANDSHAKE replays.

Reported by Markus Stenberg <markus.stenberg at iki.fi> - thanks!

ok deraadt@