svn commit: r196752 - head/lib/libc/stdtime
Bruce Evans
brde at optusnet.com.au
Fri Sep 4 05:21:21 UTC 2009
On Fri, 4 Sep 2009, Bruce Evans wrote:
> On Thu, 3 Sep 2009, [utf-8] Dag-Erling Smørgrav wrote:
>
>> What do you think of the attached patch?
Oops, it is more broken than I noticed. Almost all ctype man pages
already documented the requirements in even more detail than POSIX,
since Andrey fixed the missing documentation to almost catch up with
C99 and POSIX in Y2K, and tjr added more details on 6 Oct 2002. E.g.,
in isalpha.3:
% The value of the argument must be representable as an
% .Vt "unsigned char"
% or the value of
% .Dv EOF .
This is the same as in POSIX except the POSIX wording is better (e.g.,
the above only says implicitly that the behaviour is undefined if
"must" is not satisfied). It took too many commits (revs 1.8-1.10) to
get this far.
% ...
% .Sh COMPATIBILITY
% The
% .Bx 4.4
% extension of accepting arguments outside of the range of the
% .Vt "unsigned char"
% type in locales with large character sets is considered obsolete
% and may not be supported in future releases.
% The
% .Fn iswalpha
% function should be used instead.
This was added in rev.1.16. It also has bugs from not being merged with
the old documentation about this problem -- it contradicts the "must",
yet still doesn't say what the behaviour is for args outside the range:
- are they classified as non-alpha, or are characters with (positive)
values outside the range actually possible in some locales, with
these characters being classified as alpha by this function and
handled correctly by all ctype functions
- we now have future releases, and the above says that these releases
are not permitted to support this behaviour, so why do we still have
it ;-)
- what happens for the corresponding problem with iswalpha -- will the
FreeBSD extension of not having these problems ever be documented
or not permitted or actually go away?
> % Index: lib/libc/locale/iscntrl.3
> % ===================================================================
> % --- lib/libc/locale/iscntrl.3 (revision 196695)
> % +++ lib/libc/locale/iscntrl.3 (working copy)
> % @@ -32,7 +32,7 @@
> % .\" @(#)iscntrl.3 8.1 (Berkeley) 6/4/93
> % .\" $FreeBSD$
> % .\"
> % -.Dd July 17, 2005
> % +.Dd September 3, 2009
> % .Dt ISCNTRL 3
> % .Os
> % .Sh NAME
> % @@ -65,6 +65,15 @@
> % .It "\&031\ EM \t032\ SUB \t033\ ESC \t034\ FS \t035\ GS"
> % .It "\&036\ RS \t037\ US \t177\ DEL"
> % .El
> % +.Pp
> % +.Em NOTE :
> % +if the value passed to the
> % +.Fn iscntrl
> % +function is a
> % +.Vt signed char ,
> % +as is usually the case, it must be cast to an
> % +.Vt unsigned char
> % +to avoid sign-extension errors.
>
> This wording is poor. It should be something like "if the value to be
> passed is represented as a signed char" ... I don't know a good easy
> way to fix "must be cast ... to avoid sign-extension errors". The
"value to be passed" is wrong too, since the problematic negative values
must not be passed.
Anyway, teaching how to apply casts to satisfy the requirements of the API
should be duplicated ad nauseum in man pages even less than the requirements
of the API.
Bruce
More information about the svn-src-head
mailing list