Update pmclog(3) and cap_rights_get(3) EXAMPLE section.

[araujo]

Summary

Update the example sections on those manpages to reflect the
discussion about assert(3).

[rgrimes]

lib/libc/gen/cap_rights_get.3

87

The original assert looks to be a valid use of assert, that code is a sanity check that should never occur, if it does occur something has gone wrong inside of getrights or setrights, this code can safely be compiled out.

lib/libpmc/pmclog.3

265

This changes the flow of the code, the switch is now inside an if block that did not exist before. This also fail to abort in the failure case (ev.pl_state != PMCLOG_OK).

[rgrimes]

lib/libpmc/pmclog.3

279

Could be fixed by changing this to
} else {

err(...

}

[brooks]

It looks to me like both of these assert()s are correct.

lib/libc/gen/cap_rights_get.3

87

Agreed.

lib/libpmc/pmclog.3

265

Reading the rest of the manpage, this assert is correct and appropriate. ev.pl_state is set to something other than PCMLOG_OK only when pmclog_read() returns -1.

[araujo]

lib/libpmc/pmclog.3

265

But we can't ignore the possibility of users build it without NDBUG. How to handle that case then?

[brooks]

lib/libpmc/pmclog.3

265

An API not behaving as documented is allowed to lead to undefined behavior. The assert() is there to document and (when enabled) validate a case that "can't happen", not to handle something we are expected to handle (e.g. resource allocation failure).

[araujo]

lib/libpmc/pmclog.3

265

Sure, but in this specific case if ev.pl_state != PMCLOG_OK we probably can't get ev.pl_type, and the switch case will pass silently and there is no default there to deal with this behavior. Am I wrong?

[araujo]

lib/libpmc/pmclog.3

265

Very likely we won't even have pl_state and the switch case will break.

[brooks]

lib/libpmc/pmclog.3

265

Yes, because the rest of the manpage is clear path that a return of 0 from pmclog_read() means a record was successfully read. It is a bug in pmclog_read() if it returns 0 and sets ev.pl_state != PMCLOG_OK. This assert checks for such a bug.

[araujo]

lib/libpmc/pmclog.3

265

Ok, makes sense! Thanks!