Specify which documentation you found a problem with
docs/libcurl/curl_version_info.md
The problem
The documentation talks about the caller setting the age parameter appropriately, so that:
libcurl always returns a proper struct that your program understands, while programs in the future might get a different struct.
Later, it also says about age:
You are however guaranteed to get a struct that you have a matching struct for in the header, as you tell libcurl your "age" with the input argument.
However, that age parameter is currently completely ignored in the function. This means that if the returned struct changes in a backward-incompatible way in the future, a future application dynamically-linked to an older libcurl will receive the older struct, despite asking for a newer one, contrary to the documentation.
Since there is no way to return an error indication to the caller if this ever occurs, this documented behaviour can never be honoured. This also means that the implication that the returned struct may some day be incompatible can also never occur without also breaking the ABI.
Applications relying on this behaviour even in the face of backwards-compatible struct changes will also end up with a OOB read. For example, an application might need the feature_names field, so it sets stamp to CURLVERSION_ELEVENTH. However, the binary is run on an old OS with libcurl 7.86.0 that doesn't have this field. The application believes the guarantee libcurl always returns a proper struct that your program understands and reads that field (an OOB read) and even if that itself doesn't result in a segfault, when it dereferences that pointer it just read, it will almost be guaranteed one.
A thoughtful programmer should realize that this reading of the documentation does not and cannot make sense, but we shouldn't be making these kind of impossible guarantees.
This guarantee in the documentation should be removed. Instead, the caller should be admonished instead to check the returned age parameter in the struct. If that value is less than CURLVERSION_NOW (or another fixed CURLVERSION_* value determined by the developer), then the struct should not be dereferenced or it could result in a OOB read. This should be made explicit rather than implicit, as it is now.
Furthermore, if we ever want to reserve the ability to change the struct in backward-incompatible ways using the age parameter, we need to define a way of returning an error if the age request can't be satisfied. This could be by returning NULL or by defining an error field in the struct. Or, we drop the idea that we could ever do this.
Specify which documentation you found a problem with
docs/libcurl/curl_version_info.md
The problem
The documentation talks about the caller setting the
ageparameter appropriately, so that:Later, it also says about age:
However, that age parameter is currently completely ignored in the function. This means that if the returned struct changes in a backward-incompatible way in the future, a future application dynamically-linked to an older libcurl will receive the older struct, despite asking for a newer one, contrary to the documentation.
Since there is no way to return an error indication to the caller if this ever occurs, this documented behaviour can never be honoured. This also means that the implication that the returned struct may some day be incompatible can also never occur without also breaking the ABI.
Applications relying on this behaviour even in the face of backwards-compatible struct changes will also end up with a OOB read. For example, an application might need the
feature_namesfield, so it sets stamp toCURLVERSION_ELEVENTH. However, the binary is run on an old OS with libcurl 7.86.0 that doesn't have this field. The application believes the guarantee libcurl always returns a proper struct that your program understands and reads that field (an OOB read) and even if that itself doesn't result in a segfault, when it dereferences that pointer it just read, it will almost be guaranteed one.A thoughtful programmer should realize that this reading of the documentation does not and cannot make sense, but we shouldn't be making these kind of impossible guarantees.
This guarantee in the documentation should be removed. Instead, the caller should be admonished instead to check the returned age parameter in the struct. If that value is less than
CURLVERSION_NOW(or another fixedCURLVERSION_*value determined by the developer), then the struct should not be dereferenced or it could result in a OOB read. This should be made explicit rather than implicit, as it is now.Furthermore, if we ever want to reserve the ability to change the struct in backward-incompatible ways using the age parameter, we need to define a way of returning an error if the age request can't be satisfied. This could be by returning NULL or by defining an error field in the struct. Or, we drop the idea that we could ever do this.