Julio M. Merino Vidal wrote:
> On 23/06/2007, at 20:24, Elad Efrat wrote:
> [...]
>>    Kernel Programming Interface
>>      kauth exports a KPI that allows developers both of NetBSD and
>>      third-party products to authorize requests, access and modify
>>      credentials, create and remove scopes and listeners, and perform
>>      other miscellaneous operations on credentials.
>>
>> here is what it says about accessor/mutators:
>>
>>    Credentials Accessors and Mutators
>>      kauth has a variety of accessor and mutator routines to handle
>>      kauth_cred_t objects.
>>
>>      The following routines can be used to access and modify the user-
>>      and group-ids in a kauth_cred_t:
>> [...]
>> what is so poor about it? what is missing?
> 
> Maybe a rationale for this "complete abstraction" design and emphasizing 
> that accessors and mutators are used to completely hide the 
> implementation details.  This "kind of design" is not common among the 
> kernel's interfaces, unfortunately, so it might be difficult for other 
> developers to guess your initial intentions with the design.

while I think this is nitpicking, I'll address your comments. :)

I think the way from the above suggestion to "poor documentation" is
very far. fwiw, here's the mail sent to the public introducing kauth
a little over a year ago:

http://mail-index.netbsd.org/tech-security/2006/04/18/0000.html

where I said this:

     It's worth noting that the credentials have become an opaque
     type: it's no longer possible to directly access members like
     "effective user-id" or "saved group-id". In fact, there are very few
     cases where you should be doing that. This opacity allows us to
     freely modify the credentials structure.

since then, the issue of kauth's opacity was brought up multiple times,
most notably the commits I quoted in a previous email.

so, true, while this was not made crystal clear in the documentation
(though I tend to have mixed feelings about that, but oh well), I agree
that if the above helps people understand the interface and
implementation it should certainly be added.

-e.