[Bug 1089] Are headers complete enough?

------- Additional Comments From [email protected]  2005-10-11 16:09 -------
I'm still wrestling with this question, and thought that a comparison of how the
LSB, the System V generic ABI and POSIX separately deal with the area of data
definitions.

The System V generic ABI says:

"Standard header files that describe system data are available for C
application developers to use. These files are referred to by their name
in angle brackets: <[[name]].h>, <sys/[[name]].h> and <X11/[[name]].h
>. Included in these headers are macro definitions, data definitions,
and function declarations. The parts of the header files specified in
the ANSI C standard are the only parts available to strictly-conforming
ANSI C applications. Similarly, only the portions of the header files
defined in the POSIX P1003.1 Operating System Standard are available to
strictly POSIX-conforming applications.

Some of the following header files define interfaces directly available
to applications, and those interfaces will be common to systems on all
processors. Other header files show specific implementations of standard
interfaces, where the implementation or data definitions might change
from one processor to another. The ABI does not distinguish between
these files. It gives data definitions to promote binary application
portability, not to repeat source interface definitions available
elsewhere. System providers and application developers should use the ABI
to supplement—not to replace—source interface definition documents.

The application execution environment presents the interfaces described below,
but the ABI does not require the presence of the header files themselves. In
other words, an ABI-conforming system is not required to provide an application
development environment."

The architecture specific underlying ABI docs DO include function prototypes.
=================

The LSB currently says:
"This section defines global identifiers and their values that are
associated with interfaces contained in [[libc]]. These definitions are
organized into groups that correspond to system headers. This convention
is used as a convenience for the reader, and does not imply the existence
of these headers, or their content.

These definitions are intended to supplement those provided in the
referenced underlying specifications.

This specification uses the ISO C (1999) C Language as the reference
programming language, and data definitions are specified in ISO C
format. The C language is used here as a convenient notation. Using a C
language description of these data objects does not preclude their use
by other programming languages."

The data defs DO NOT include function prototypes (today).
==========

POSIX has a section on header files that says:
"This chapter describes the contents of headers.

Headers contain function prototypes, the definition of symbolic
constants, common structures, preprocessor macros, and defined
types. Each function in the System Interfaces volume of IEEE Std
1003.1-2001 specifies the headers that an application shall include
in order to use that function. In most cases, only one header is
required. These headers are present on an application development
system; they need not be present on the target execution system."

POSIX headers DO include function prototypes.
======================================================================

POSIX is of course a source standard only. So it stops at defining
symbols (i.e. it defines the name not the value), gives only partial
data structure definitions (common structure members) etc. The LSB has
to give values, and make objects have sizes (i.e. it has to describe
the exact layout of a structure, including all members).

An LSB conforming system is a "target execution system" in POSIX
terms. The LSB need not be language specific (but uses C as the language
to exposit the requirements).

So ... I believe that the following changes ARE in order:
1. data definitions should include function prototypes
2. the introduction to the data definitions section needs to emphasize the
relationship between a "data definition <<header>>" and a system header.
3. The data definitions needs to repeat some of the things from the underlying
gABI document.

Proposed new intro to data definitions:
"This section defines global identifiers and their values that are
associated with interfaces contained in [[libc]]. These definitions are
organized into groups that correspond to system headers. This convention
is used as a convenience for the reader, and does not imply the existence
of these headers, or their content. 

This section gives data definitions to promote binary application
portability, not to repeat source interface definitions available
elsewhere. System providers and application developers should use this ABI
to supplement—not to replace—source interface definition documents.

This specification uses the ISO C (1999) C Language as the reference
programming language, and data definitions are specified in ISO C
format. The C language is used here as a convenient notation. Using a C
language description of these data objects does not preclude their use
by other programming languages."

   
 
--    
Configure bugmail: http://bugs.linuxbase.org/userprefs.cgi?tab=email   
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.