Revise srt_bstats and srt_bistats API functions to have only one function for retrieving SRT socket statistics

[mbakholdina]

1. Revise srt_bstats and srt_bistats functions in order to have only one function as a result.

Suggested function name: srt_socket_stats or srt_stats.

Currently we have two functions that can be used to retrieve statistics on an SRT socket, they both do almost similar things:

• int srt_bstats(SRTSOCKET u, SRT_TRACEBSTATS * perf, int clear)
• int srt_bistats(SRTSOCKET u, SRT_TRACEBSTATS * perf, int clear, int instantaneous)

2. Update the API-functions.md and statistics.md documentation accordingly.

[heftig]

The latest 1.4.2 "patch" release added fields to the CBytePerfMon struct. Code built against 1.4.1 is not ABI-compatible: perf will not point to structure that's large enough and srt_bstats will write out-of-bounds (buffer overflow). Yet the dynamic linker allowed this to happen because the soname indicated compatibility (see #1592).

If you want to be able to add stats fields in patch releases, please make the new function take a perf_size argument that the caller will fill with sizeof (SRT_TRACEBSTATS). This will allow the function to know which version of the structure was passed when called from code compiled against older headers.

[maxsharabayko]

Hi @heftig

Thank you for your valuable feedback! Community feedback is something we appreciate to improve our workflow.

Indeed, we tend to extend the CBytePerfMon structure in patch versions. There is often something missing in the structure that people would like to have, but we always thought it is not a strong enough motivation to increase the minor version.

The extension of CBytePerfMon is usually done by adding new fields at the end of the structure definition. This approach allows an application that uses the new srt.h version to still work with an older dynamic library of SRT (which is however not a very safe to do in case ABI compatibility is not fully preserved), just not the whole structure will be filled.

However, there is a problem if the dynamic library is updated, but the old structure with a lower size is submitted to srt_bstats(..) because the library does not know the actual size of the structure provided in SRT_TRACEBSTATS * perf, and just fills it according to the size it knows (which is bigger than the one submitted).

If we want to safely extend SRT statistics in patch versions we need to introduce a safer API function to retrieve statistics that would also supply the size of the structure it submits for filling, like you suggest.

BTW, a new API function srt_getversion() was introduced in v1.4.2, which could help a bit in such situations on the application level.