Defect report from : Alexander van Heukelum , n/a
(Please direct followup comments direct to yyyyyyyyyyyyyy@xxxxxxxxxxxxx)
@ page 0 line 0 section 0 editorial {0}
Problem:
Edition of Specification (Year): 2003
Defect code : 3. Clarification required
http://www.opengroup.org/onlinepubs/007904975/basedefs/sys/select.h.html
Problem [A] In the section describing the header file
sys/select, the symbols FD_CLR, FD_ISSET, FD_SET, and FD_ZERO
are explained. This is superfluous, because they are also
explained in the XSH/"System Interfaces"-part of the standard.
Moreover, the typesetting of these functions and the placing of
the list are inconsistent with other parts of the standard.
Problem [B] Below, I sum up the wordings that are used as a
caption of a table of function declarations and/or macro
definitions. If I interpret them correctly, there are only three
possible meanings:
-1- The interface must be declared as a real function,
(the C-library must export the symbol), but may
_additionaly_ be defined as a macro.
-2- The interface shall not be declared as a function,
(the C-library shall not export the symbol), but
it must be available as a macro.
-3- The implementation may choose between 1 and 2.
However, the wordings are not used consistently, which can (and
by Murphy's law will) lead to some confusion. I propose to unify
the wordings.
FUNCTION
--------
http://www.opengroup.org/onlinepubs/007904975/basedefs/aio.h.html
(1a) "The following shall be declared as functions and may
also be defined as macros. Function prototypes shall be
provided."
in the header files aio, arpa/inet, complex, ctype, dirent,
dlfcn, fcntl, fenv, ftw, glob, grp, iconv, inttypes, libgen,
locale, math, mqueue, ndbm, net/if, netdb, nl_types, pthread,
pwd, regex, sched, search, semaphore, setjmp, spawn, stdio,
stdlib, string, strings, stropts, sys/mman, sys/msg,
sys/resource, sys/select, sys/sem, sys/shm, sys/socket,
sys/stat, sys/statvfs, sys/time, sys/uio, sys/wait, syslog,
termios, time, trace, unistd, utmpx, wchar, wctype, and wordexp.
- or (if only item) -
http://www.opengroup.org/onlinepubs/007904975/basedefs/fnmatch.h.html
"The following shall be declared as a function and may
also be defined as a macro. A function prototype shall
be provided."
in the header files fmtmsg, fnmatch, langinfo, monetary, poll,
sys/ipc, sys/timeb, sys/times, ulimit and utime.
http://www.opengroup.org/onlinepubs/007904975/basedefs/ucontext.h.html
(1b) "The following shall be declared as functions and may
also be defined as macros, Function prototypes shall be
provided."
in the header file ucontext.
http://www.opengroup.org/onlinepubs/007904975/basedefs/signal.h.html
(1c) "The following shall be declared as functions and may
also be defined as macros:"
in the header file signal.
- or (if only item) -
http://www.opengroup.org/onlinepubs/007904975/basedefs/sys/utsname.h.html
"The following shall be declared as a function and may
also be defined as a macro:"
in the header file sys/utsname.
MACRO
-----
http://www.opengroup.org/onlinepubs/007904975/basedefs/complex.h.html
(2a) "The <xxxxxxx.h> header shall define the following
macros..." (sometimes followed by a short further
explanation)
in the header files complex, fmtmsg, math, net/if, netdb (4x),
netinet/in (6x), netinet/tcp, stdbool, stddef, stdio, stdlib,
sys/socket (7x), sys/wait, and wchar.
http://www.opengroup.org/onlinepubs/007904975/basedefs/fmtmsg.h.html
(2b) "The <xxxxxxx.h> header shall also define the following
macros for use as return values for fmtmsg():"
in the header file fmtmsg.
http://www.opengroup.org/onlinepubs/007904975/basedefs/wctype.h.html
(2c) "The <xxxxxxx.h> header shall define the following macro
name:"
in the header file wctype.
http://www.opengroup.org/onlinepubs/007904975/basedefs/sys/select.h.html
(2d) "The following shall be defined as a macro:"
in the header file sys/select.
http://www.opengroup.org/onlinepubs/007904975/basedefs/ctype.h.html
(2e) "The following are defined as macros:"
in the header file ctype.
YOUR CHOICE
-----------
http://www.opengroup.org/onlinepubs/007904975/basedefs/arpa/inet.h.html
(3a) "The following shall either be declared as functions,
defined as macros, or both. If functions are declared,
function prototypes shall be provided."
in the header file arpa/inet.
http://www.opengroup.org/onlinepubs/007904975/basedefs/setjmp.h.html
(3b) "The following may be declared as a function, or defined
as a macro, or both. Function prototypes shall be
provided."
in the header file setjmp.
http://www.opengroup.org/onlinepubs/007904975/basedefs/sys/select.h.html
(3c) "Each of the following may be declared as a function, or
defined as a macro, or both:"
in the header file sys/select.
Action:
Problem [A] The section describing the header file sys/select
should be altered in the following ways (the first and last
paragraphs are unchanged, included here for orientation;
comments are marked as {{ this is a comment }}):
--start--
The <sys/select.h> header shall define the fd_set type as a
structure.
{{ A part of the text has been moved down... }}
The following shall be defined as a macro: {{ OR, if the
relevant change of [B] is accepted: "The <sys/select.h> header
shall define the following macro:" }}
FD_SETSIZE
Maximum number of file descriptors in an fd_set structure.
{{ ... to this position... }}
Each of the following may be declared as a function, or
defined as a macro, or both: {{ OR, if the relevant change of
[B] is accepted: "The following shall be declared as functions,
defined as macros, or both. If functions are declared, function
prototypes shall be provided." }}
{{ The following list should be typeset in the same way as
the pselect and select function declarations below. }}
void FD_CLR(int fd, fd_set *fdset); {{ note: semicolon 4x }}
int FD_ISSET(int fd, fd_set *fdset);
void FD_SET(int fd, fd_set *fdset);
void FD_ZERO(fd_set *fdset);
If implemented as macros, these may evaluate their arguments
more than once, so applications should ensure that the arguments
they supply are never expressions with side effects.
{{ ... end of moved part of the text. }}
The following shall be declared as functions and may also be
defined as macros. Function prototypes shall be provided.
--end--
Problem [B]
Proposed changes:
FUNCTION
--------
(1a) (reference version)
http://www.opengroup.org/onlinepubs/007904975/basedefs/ucontext.h.html
(1b) correct the typo (comma instead of full stop) in ucontext.h.
http://www.opengroup.org/onlinepubs/007904975/basedefs/signal.h.html
http://www.opengroup.org/onlinepubs/007904975/basedefs/sys/utsname.h.html
(1c) change the wording in signal.h and sys/utsname.h to add the
obligation to provide a prototype. I filed a bug report earlier
for (1c), but I include it here again for completeness.
MACRO
-----
(2a) (reference version)
http://www.opengroup.org/onlinepubs/007904975/basedefs/fmtmsg.h.html
(2b) The (superfluous) word "also" makes it unclear that the
macros in the following list are the only possible return
values. It should be removed.
http://www.opengroup.org/onlinepubs/007904975/basedefs/wctype.h.html
(2c) The word "name" is used incorrectly here. It should be
removed.
http://www.opengroup.org/onlinepubs/007904975/basedefs/sys/select.h.html
http://www.opengroup.org/onlinepubs/007904975/basedefs/ctype.h.html
(2d) and (2e) These are the only other inconsistancies I could
find. Changing them to "The <sys/select.h> header shall define
the following macro:" and "The <ctype.h> header shall define the
following macros:" would make me happier.
YOUR CHOICE
-----------
http://www.opengroup.org/onlinepubs/007904975/basedefs/arpa/inet.h.html
(3a) The word either implies a choice of 2 possiblities.
However, there are three possibilities. Remove the word
"either", and add "or" after the first comma (so it reads
"... as functions, or defined as macros, or both.")
http://www.opengroup.org/onlinepubs/007904975/basedefs/setjmp.h.html
(3b) The word "may" implies that the interface may in fact be
absent. It should be replaced by "shall". The first sentence,
then, still allows a macro-only interface, but the second
sentence implies that the function should be available too,
which seems to be incorrect. The second sentence should be
changed to "If functions are declared, function prototypes shall
be provided.".
http://www.opengroup.org/onlinepubs/007904975/basedefs/sys/select.h.html
(3c) The word "may" implies that the interface may in fact be
absent. For consistancy, this sentence should be replaced by
"The following shall be declared as functions, defined as
macros, or both. If functions are declared, function prototypes
shall be provided." Also, the list that follows this caption is
typeset differently than usual (see Problem [A]).
|