[openssl/openssl] a25715: Improve documentation for BIO_s_mem

[Neil Horman]

  Branch: refs/heads/master
  Home:   https://github.com/openssl/openssl
  Commit: a25715be77ff43cd816a2011fff50b68204e9c0e
      https://github.com/openssl/openssl/commit/a25715be77ff43cd816a2011fff50b68204e9c0e
  Author: Neil Horman <nhorman at gmail.com>
  Date:   2023-08-16 (Wed, 16 Aug 2023)

  Changed paths:
    M doc/man3/BIO_s_mem.pod

  Log Message:
  -----------
  Improve documentation for BIO_s_mem

Recent leak discovered by valgrind:
==1007580== at 0x483C815: malloc (vg_replace_malloc.c:431)
==1007580== by 0x2C2689: CRYPTO_zalloc (in /home/vien/microedge-c/test)
==1007580== by 0x295A17: BUF_MEM_new (in /home/vien/microedge-c/test)
==1007580== by 0x295A78: BUF_MEM_new_ex (in /home/vien/microedge-c/test)
==1007580== by 0x28CACE: mem_new (in /home/vien/microedge-c/test)
==1007580== by 0x285EA8: BIO_new_ex (in /home/vien/microedge-c/test)
==1007580== by 0x231894: convert_pubkey_ECC (tpm2_driver.c:221)
==1007580== by 0x232B73: create_ephemeral_key (tpm2_driver.c:641)
==1007580== by 0x232E1F: tpm_gen_keypair (tpm2_driver.c:695)
==1007580== by 0x22D60A: gen_keypair (se_driver_api.c:275)
==1007580== by 0x21FF35: generate_keypair (dhkey.c:142)
==1007580== by 0x24D4C8: __test_dhkey (dhkey_test.c:55)

led me to find that BIO_get_mem_data is informative only, it does not
transer ownership of a BIO_s_mems data structure to the caller.
Additionally treating it as such leads to the above leak, or possibly
data corruption in the event that BIO_set_close(bio, BIO_NOCLOSE) is not
set properly prior to calling BIO_free.

Made an attempt to fix it in a minimally invasive manner in the 3.1
branch, but based on discussion, its just not safe to do in an API
compatible way, so just document the sematics a little more clearly
here, and fix it properly in a future release

Reviewed-by: Hugo Landau <hlandau at openssl.org>
Reviewed-by: Tomas Mraz <tomas at openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21724)

(cherry picked from commit 66d1658b4d88c66b27a8a538b2fb365ef1907936)