streamWrapper::stream_lock() operation/mode listing is inconsistent

[adam-vessey]

It is presently indicated that valid values are in the set of:

• LOCK_SH
• LOCK_EX
• LOCK_UN
• LOCK_NB

The underlying implementation appears to allow more like:

• LOCK_SH
• LOCK_EX
• LOCK_UN
• LOCK_SH | LOCK_NB (the | denoting a bit-wise OR)
• LOCK_EX | LOCK_NB
• LOCK_UN | LOCK_NB (though this one might not make sense? To release locks non-blockingly?)

The initial comparison should reject LOCK_NB being passed on its own, since LOCK_NB & LOCK_UN == 4 & 3 == 0b100 & 0b011 == 0, and 0 < 1.

Somewhat of an aside, just for context, but: I got looking into this due to Drupal's implementation which makes reference to the presently documented set of values. An aside to the aside: due to Drupal's returning TRUE for operations/modes outside of the given (possibly due to the the concept of success/failure being ambiguous in the function signature?), Drupal can fail to correctly manage locks when attempting to do things with LOCK_NB. Created an issue over there to look at getting it dealt with: https://www.drupal.org/project/drupal/issues/3493632