Bug 21708

Summary: kqueue/kevent man pages isn't specific about `timeout'
Product: Documentation Reporter: Ronald F. Guilmette <rfg>
Component: Books & ArticlesAssignee: John-Mark Gurney <jmg>
Status: Closed FIXED    
Severity: Affects Only Me CC: rfg
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Ronald F. Guilmette 2000-10-02 21:20:00 UTC 
	The man page for kqueue/kevent doesn't explicitly say what the
	semantics of the `timeout' parameter for the kqueue(2) function
	are.  Will a call to kqueue() timeout and return to the caller
	(with a return value of zero) when no currently-monitored events
	have occured for the amount of _elapsed_ time specified by the
	`timeout' parameter?  Or will a call to kqueue() timeout and return
	to the caller (with a return value of zero) if no monitored events
	have occured by the time the system's own clock says that we have
	reached the time specified by the `timeout' parameter?

	In short, is the `timeout' parameter for kevent(2) interpreted (by
	the kernel) as a _relative_ time period, or as an _absolute_ time
	specification?

	The kevent(2) man page does not make this clear.

Fix: 

Specify in the manpage that `timeout' is either (a) relative or else
	(b) absolute.
How-To-Repeat: 
	RTFManpage
Comment 1 Jeroen Ruigrok van der Werven freebsd_committer freebsd_triage 2000-11-21 15:22:51 UTC 
State Changed
From-To: open->closed

Document the fact that the time parameter is interpreted as 
a struct timespec.
Comment 2 nik freebsd_committer freebsd_triage 2001-06-26 22:36:46 UTC 
State Changed
From-To: closed->open

Jonathan, you're Mr. Kqueue :-). The question is (from a followup to the 
PR) 

== 
The problem is that it is not specified whether the timeout is treated 
as a _relative_ timespec or as an _absolute_ timespec. 

Just saying that it is a timespec does not resolve the issue. 

P.S.  My own experiments seem to indicate that the timeout value is 
treated as being _relative_ to the present moment, i.e. the moment 
at which the call to kevent(2) is actually made. 
==
Comment 3 nik freebsd_committer freebsd_triage 2001-06-26 22:36:46 UTC 
Responsible Changed
From-To: freebsd-doc->jlemon

jlemon is Mr. kqueue
Comment 4 John-Mark Gurney freebsd_committer freebsd_triage 2003-11-06 18:38:38 UTC 
State Changed
From-To: open->feedback

the documents say: 
If timeout is a non-NULL pointer, it specifies a maximum interval to wait 
interval to me implies relative.   If you disagree, please provide correct 
wording (you don't have to provide a patch, but that'd be very nice).
Comment 5 John-Mark Gurney freebsd_committer freebsd_triage 2003-11-06 18:38:38 UTC 
Responsible Changed
From-To: jlemon->jmg

the documents say: 
If timeout is a non-NULL pointer, it specifies a maximum interval to wait 
interval to me implies relative.   If you disagree, please provide correct 
wording (you don't have to provide a patch, but that'd be very nice).
Comment 6 John-Mark Gurney freebsd_committer freebsd_triage 2003-12-03 18:41:04 UTC 
State Changed
From-To: feedback->closed

guess the submitter doesn't disagree, close this