This is a (VERY) revised version of ERN 633 (AI 2001-03-29). Don and
I both agree that this unambiguously and clearly says what the function
actually does in practice. (Don tells me he has concerns about the example
as well, with details forthcoming.)
It looks rather different for a number of reasons: a lot of jumping about
to different topics was eliminated, yielding better flow, several shortened
sentences, and pointing out some remaining holes. (The bit about the
"first equal sign before the comma" is directly a consequence of recognizing
what was needed in reordered text.)
It also became clear that "tokens" was a poorly chosen name; by renaming
it, a bunch of semantic ambiguities went away. (There were several places
where ordinary english "token[s]" was used to refer to the content of
optionp, which I find, even with italics properly provided, adds to the
confusion.
Donn
OBJECTION Enhancement Request Number
633
yyyyyy@xxxxxxxxxxxxx Bug in xsid5 Assorted (rdvk#
637)
[DST-832] Mon, 5 Feb 2001 19:57:19 -0800
____________________________________________________________________________
_
Accept_____ Accept as marked below_____ Duplicate_____
Reject_____
Rationale for rejected or partial changes:
____________________________________________________________________________
_
Page: 1049 Line: 18719 Section: getsubopt
Problem:
"Similarly, because the equal sign separates a token from its value,
undefined behavior will result if the application passes a token
that contains an equal sign."
"A token" here is reasonably read as one of the input arguments,
and thus would require that the application pre-parse the input.
Here's an attempt at rewriting the whole paragraph so it says something
useful, and I hope accurate.
(I also dropped the requirement that it come from getopt(), because
that isn't necessary.)
Action:
I think this says what was intended unambiguously
1) Replace all uses of tokens (the identifier, not the plural english word!)
with "keylistp". I have done so below. (The english text uses "token"
in such a way that it is easily confused with the identifier "tokens".)
(If there's significant objection to that renaming, I can live with
"tokensp", but I think that just "tokens" is a bad idea.)
2) Replace the whole description with:
The getsubopt( ) function shall parse suboption arguments in a flag
argument. Such options often result from the use of getopt( ).
The getsubopt( ) argument _optionp_ is a pointer to a pointer to
the option argument string. The suboption arguments shall be
separated by commas and each may consist of either a single token,
or a token-value pair separated by an equal sign.
The _keylistp_ argument shall be a pointer to a vector of strings.
The end of the vector is identified by a null pointer. Each entry
in the vector is one of the possible tokens that might be found
in *_optionp_. Because commas delimit suboption arguments in
_optionp_, they should not appear in any of the strings pointed
to by _keylistp_. Similarly, because an equal sign separates a token
from its value, the application should not include an equal sign
in any of the strings pointed to by _keylistp_.
The _valuep_ argument is the address of a value string pointer.
If a comma appears in _optionp_, it shall be interpreted as a
sub-option separator. After commas have been processed, if there
are one or more equal signs in a sub-option string, the first equal
sign in any sub-option string shall be interpreted as a separator
between a token and a value. Subsequent equal signs in a sub-option
string shall be interpreted as part of the value.
If the string at *_optionp_ contains only one suboption argument,
(equivalently, no commas) getsubopt( ) shall update *_optionp_ to
point to the nul character at the end of the string. Otherwise,
it shall isolate the suboption argument by replacing the comma
separator with a nul character, and shall update *_optionp_ to
point to the start of the next suboption argument. If the suboption
argument has an associated value (equivalently, contains an equal
sign), getsubopt( ) shall update *_valuep_ to point to the value's
first character. Otherwise, it shall set *_valuep_ to a null pointer.
The calling program may use this information to determine whether
the presence or absence of a value for the suboption is an error.
Additionally, when getsubopt( ) fails to match the suboption argument
with a token in the _keylistp_ array, the calling program should
decide if this is an error, or if the unrecognized option should
be processed in another way.
|