17806 - The value of the out_flags fields when PR_Poll returns 0 or -1

Status: RESOLVED FIXED

(NSPR :: NSPR, defect, P3)

Description

[Wan-Teh Chang]

The value of the out_flags fields of PRPollDesc structures
is meaningful only when PR_Poll succeeds (returning a positive
number).  When PR_Poll returns -1 (error) or 0 (timeout),
the out_flags fields must not be examined.

There are two problems that need to be fixed.
1. Documentation: the above behavior is not clearly documented.
   NSPR doc says:
       On return, the out_flags field of the PRPollDesc data
       structure is set to indicate what kind of I/O is ready
       on the respective descriptor.
   The comments in prio.h say:
       Upon return from this call PRPollDesc.out_flags will
       be set to indicate what kind of i/o can be performed
       on the respective descriptor.
   We should change "On return" to "On successful return" and
   add "if PR_Poll returns 0 or -1, the out_flags fields do
   not contain meaningful values and should not be examined".
2. Implementation: the current implementation of PR_Poll uses
   the out_flags fields as temporary variables.  When PR_Poll
   returns 0 or -1, it does not reset the out_flags fields to
   0.  While the caller should not examine the out_flags fields
   in this case, as defensive programming we should zero the
   out_flags fields.

Comment 1

[Wan-Teh Chang]

I fixed the comments for PR_Poll in prio.h and the documentation
for PR_Poll to say that the out_flags fields must not be used if
PR_Poll returns 0 or -1.
/cvsroot/mozilla/nsprpub/pr/include/prio.h, revisions 3.26 and 3.27
/cvsroot/mozilla-org/html/docs/refList/refNSPR/priofnc.html, revision 1.4

I decided to not change the implementation of PR_Poll.  I think
the advantage to be gained is small and it may promote incorrect
programming.  Callers of PR_Poll should only check the out_flags
fields on successful return as documented.

Marked the bug fixed.