RFC 7: Use VSILFILE for VSI*L Functions

Author: Eric Doenges
Contact: Eric.Doenges@…
Status: Proposed

Purpose

To change the API for the VSI*L family of functions to use a new data-type VSILFILE instead of the current FILE.

Background, Rationale

Currently, GDAL offers two APIs to abstract file access functions (referred to as VSI* and VSI*L in this document). Both APIs claim to operate on FILE pointers; however, the VSI*L functions can only operate on FILE pointers created by the VSIFOpenL function. This is because VSIFOpenL returns a pointer to an internal C++ class typecast to a FILE pointer, not an actual FILE pointer. This makes it impossible for the compiler to warn when the VSI* and VSI*L functions are inappropriately mixed.

Proposed Fix

A new opaque data-type VSILFILE shall be declared. All VSI*L functions shall be changed to use this new type instead of FILE. Additionally, any GDAL code that uses the VSI*L functions must be changed to use this data-type as well.

Compatibility Issues, Transition timeline

In order to allow the compiler to detect inappropriate parameters passed to any of the VSI*L functions, VSILFILE would have to be declared with the help of an empty forward declaration, i.e.

typedef struct VSILFILE VSILFILE

with the struct VSILFILE itself left undefined. However, this would break source compatibility for any existing code using the VSI*L API.

Therefore, VSILFILE* will be declared as a void pointer for now, and the change to a distinct pointer type deferred to a future release of gdal that is not constrained with backward compatibility issues. While this will not solve the primary issue (no warnings/errors from the compiler), looking at the declarations of the VSI*L functions will at least make it immediately clear that these functions cannot be expected to work if passed a FILE pointer.