This entry could just as easily been titled "Why Bad Documentation is Worse Than No Documentation".
I noticed that some functions from strsun.h are now part of the DDI. Great, I thought, I'll update my driver to use them as part of the general GLDv3 cleanup.
One major surprise, which I spent about 5-6 hours figuring out tonight. mcopymsg(9f) has a side effect that isn't documented!
Specifically, it does freemsg() on the buffer passed in.
The manual page says nothing about this. And reading logically from the name, you'd not think it would do this. The side effect should never have been designed in, in the first place. But if the man page referenced this side effect, I might, just might have caught this problem a couple of hours ago.
In my particular case, it was causing hard hangs most of the time. Until I finally got a panic that pointed me into the root of the problem. (Yes, I probably should have set kmem_flags != 0. Next time.)
/me throws brick at whoever wrote and edited the man page. /me throws pallet of bricks at whoever designed mcopymsg with this side effect in the first place
Arrgh. Well, this will probably help me figure out several problems I've run into lately.
posted by Garrett D'Amore at 3:21 AM on May 22, 2007
"Why Side Effects Are Bad"
No comments yet. -