[OpenAFS-devel] Shipping afs/afs.h

[Andrew Deason]

I've had a few people complain to me about compilation failures in
afs/afs.h when trying to build third-party stuff that uses openafs
libraries. One such report is RT 131737.

I was kinda surprised that this is a public, shipped, header. This is
the header that has kernel client stuff like struct vcache, struct
vrequest, etc etc. Those are things I considered very internal, so I
thought the header was supposed to be, too. But we do ship afs.h, and it
looks like we've shipped it ~forever. It's always contained about the
same contents, but builds started failing with 1.6 since the
introduction of afs_ucred_t, as well as other refactorings.

We used to have a 'struct AFS_UCRED' or something like that, where
AFS_UCRED was #define'd to the actual cred structure when building in
the kernel. But for 3rd-party stuff including afs.h, 'struct AFS_UCRED'
was nothing, but an undefined structure is okay. An undefined type,
afs_ucred_t, of course is not okay. I think there may be some other
unavoidable errors on other platforms, but that one is the clearest.

So, the problems with using this header should be clear; in my opinion,
it seems like it should #error immediately without -DKERNEL. But what is
this header needed for? In RT 131737 it doesn't appear to be needed for
anything with libnss-afs. Based on another report, it appears to have
been used to get at least "AFS_SYSCALL" and "NOPAG" in the past.

"AFS_SYSCALL" should not be needed by anything anymore, since it should
be using the platform-specific syscall mechanism and should be calling
lpioctl() or something. "NOPAG" is returned by afs_get_pag_from_groups,
which I don't think was intended to be public, but we don't really have
any other interface, so some things are using it.


So, what should the shipped afs/afs.h contain? It should at least exist,
even if it contains nothing, so existing code that #includes it will not
break. Does anyone know what definitions outside code may be depending
on this file to provide? Or should it just be effectively empty, but
provide a warning of some kind?

-- 
Andrew Deason
adeason@sinenomine.net