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