MFC r258148,r258149,r258150,r258152,r258153,r258154,r258181,r258182:

r258148:

Add a note that this file is compiled as part of the kernel and libc.

Requested by:	kib

r258149:

Change cap_rights_merge(3) and cap_rights_remove(3) to return pointer
to the destination cap_rights_t structure.

This already matches manual page.

r258150:

Sync return value with actual implementation.

r258151:

Style.

r258152:

Precisely document capability rights here too (they are already documented
in rights(4)).

r258153:

The CAP_LINKAT, CAP_MKDIRAT, CAP_MKFIFOAT, CAP_MKNODAT, CAP_RENAMEAT,
CAP_SYMLINKAT and CAP_UNLINKAT capability rights make no sense without
the CAP_LOOKUP right, so include this rights.

r258154:

- Move CAP_EXTATTR_* and CAP_ACL_* rights to index 1 to have more room
  in index 0 for the future.
- Move CAP_BINDAT and CAP_CONNECTAT rights to index 0 so we can include
  CAP_LOOKUP right in them.
- Shuffle the bits around so there are no gaps. This is last chance to do
  that as all moved rights are not used yet.

r258181:

Replace CAP_POLL_EVENT and CAP_POST_EVENT capability rights (which I had
a very hard time to fully understand) with much more intuitive rights:

	CAP_EVENT - when set on descriptor, the descriptor can be monitored
		with syscalls like select(2), poll(2), kevent(2).

	CAP_KQUEUE_EVENT - When set on a kqueue descriptor, the kevent(2)
		syscall can be called on this kqueue to with the eventlist
		argument set to non-NULL value; in other words the given
		kqueue descriptor can be used to monitor other descriptors.
	CAP_KQUEUE_CHANGE - When set on a kqueue descriptor, the kevent(2)
		syscall can be called on this kqueue to with the changelist
		argument set to non-NULL value; in other words it allows to
		modify events monitored with the given kqueue descriptor.

Add alias CAP_KQUEUE, which allows for both CAP_KQUEUE_EVENT and
CAP_KQUEUE_CHANGE.

Add backward compatibility define CAP_POLL_EVENT which is equal to CAP_EVENT.

r258182:

Correct right names.

Sponsored by:	The FreeBSD Foundation
Approved by:	re (kib)