Examining structures exposed in the API

[Theodore Ts'o]

On Sat, Mar 08, 2003 at 11:09:22PM -0500, Sam Hartman wrote:
> 
> I think structures are also sometimes a win for a named collection of
> arguments to a function.  For example, I think it is correct that
> krb5_get_credentials takes a structure for its search arguments.
> 
> In such cases you need to be prepared to support old versions of your
> structure to maintain ABI compatibility.  I.E. having a
> krb5_search_creds structure would have been fine, but using this same
> structure as the krb5_credentials structure elsewhere in the code is
> not fine at all.

For this case one solution is to add some spare entries to the data
structures:

	struct foo {
		...
		int	spare_int[8];
		void	*spare_ptr[8];
	};

Then define a function which initializes the data structure, and you
can now add new elements to the structure to define new ways to search
for krb5 credentials, for example, while maintaining both ABI and API
compatibility.  There are some gotchas of course; you need to be
careful about situations where off_t might be different types on
different archiectures or operating systems, for example, but on the
whole this trick can be quite useful.

(I'm planning on writing a presentation on issues of preserving ABI's
especially with respect to shared libraries, since this is an issue
which is badly ignored by much of the open source development world
IMHO.  I'm signed up to give a tutorial on the subject at the O'Reilly
OSCON 2003 conference, and again at the next Linux Lunacy Geekcruise,
which is why I've been thinking about this topic quite a bit as of late.)

							- Ted