[1/2] system_data_types.7: Document size_t

  Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 99 insertions(+), 4 deletions(-)
  

* Alejandro Colomar via Libc-alpha:

> +Used for a count of bytes.  It is the result of the
> +.I sizeof
> +operator.
> +According to the C language standard,
> +it shall be an unsigned integer type
> +capable of storing values in the range [0,
> +.BR SIZE_MAX ].

Thanks for working on this.

Maybe add that this commonly maps to unsigned int or unsigned long, and
that the length modifier for printf and scanf is z, commently used as
%zu or %zx (%zd is for ssize_t).

Florian
  

Hello Florian,

On 2020-09-18 16:34, Florian Weimer wrote:
 > * Alejandro Colomar via Libc-alpha:
 >
 >> +Used for a count of bytes.  It is the result of the
 >> +.I sizeof
 >> +operator.
 >> +According to the C language standard,
 >> +it shall be an unsigned integer type
 >> +capable of storing values in the range [0,
 >> +.BR SIZE_MAX ].
 >
 > Thanks for working on this.

:-)

 > Maybe add that this commonly maps to unsigned int or unsigned long, and

I thought the same in the beginning,
but then Michael convinced me to not do it.

On 2020-09-13 22:20, Michael Kerrisk (man-pages) wrote:
 >>>> Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned?
 >>> POSIX doesn't specify, I think.>
 >>> One other thing the page should show of course is definition of the
 >>> structure types.
 >> Yes.
 >>
 >>
 >>      timer_t     <time.h> or <sys/types.h>
 >>          POSIX timer ID.
 >>
 >>          typedef void *timer_t;
 > Here I would *not* show these kinds of typedefs. The point is
 > that these types should be treated as being somewhat unknown
 > (e.g., for casts in printf()). Here, I think instead maybe we
 > just have a statement that POSIX makes no specific requirements
 > for the representation of this type.

I think I prefer to leave it opaque, showing only the requirements
that POSIX and C make.

There's really not much gain (basically uint and ulong cover most of the
possibilities; and still it's not a guarantee).
And readers might write non-portable code because of reading that.

On 2020-09-18 16:34, Florian Weimer wrote:
 > that the length modifier for printf and scanf is z, commently used as
 > %zu or %zx (%zd is for ssize_t).

Good idea.

Would you prefer that, or just refer to printf(3) in See also?.

 >
 > Florian
 >

Thanks,

Alex
  

* Alejandro Colomar:

> I think I prefer to leave it opaque, showing only the requirements
> that POSIX and C make.
>
> There's really not much gain (basically uint and ulong cover most of the
> possibilities; and still it's not a guarantee).
> And readers might write non-portable code because of reading that.

My idea was it that it stresses that you have to use %zu in order to be
portable.  %lu works almost everywhere, so that's any easy mistake to
make because it still leads to -Werror build failures on s390 (31-bit).
Likewise for %ld for ptrdiff_t, it should be %td.

> On 2020-09-18 16:34, Florian Weimer wrote:
>> that the length modifier for printf and scanf is z, commently used as
>> %zu or %zx (%zd is for ssize_t).
>
> Good idea.
>
> Would you prefer that, or just refer to printf(3) in See also?.

I think it makes sense to spell out %zu and %zx explicitly.

Thanks,
Florian
  

On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote:
> the length modifier for printf and scanf is z, commently used as
> %zu or %zx (%zd is for ssize_t).

While %zd works for ssize_t in glibc, POSIX doesn't guarantee that it'll work, 
as ssize_t might not have the same width as size_t. (If memory serves this goes 
back to the bad old days when size_t was 64 bits and ssize_t 32 bits on some 
platforms.) So if we document %zd we should say it's a GNU extension to POSIX, 
or something like that.
  

* Paul Eggert:

> On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote:
>> the length modifier for printf and scanf is z, commently used as
>> %zu or %zx (%zd is for ssize_t).
>
> While %zd works for ssize_t in glibc, POSIX doesn't guarantee that
> it'll work, as ssize_t might not have the same width as size_t. (If
> memory serves this goes back to the bad old days when size_t was 64
> bits and ssize_t 32 bits on some platforms.) So if we document %zd we
> should say it's a GNU extension to POSIX, or something like that.

I didn't know that.  It's a good suggestion, thanks.

Florian
  

On 9/18/20 1:27 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Merged.

Thanks,

Michael

> ---
>  man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
>  1 file changed, 99 insertions(+), 4 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 84fea85b9..041e7e243 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -92,6 +92,101 @@ See also:
>  .\".I siginfo_t
>  .\"type in this page.
>  .TP
> +.I size_t
> +.IP
> +Include:
> +.I <stddef.h>
> +or
> +.IR <sys/types.h> ;
> +or
> +.I <aio.h>
> +or
> +.I <glob.h>
> +or
> +.I <grp.h>
> +or
> +.I <iconv.h>
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <ndbm.h>
> +or
> +.I <pwd.h>
> +or
> +.I <regex.h>
> +or
> +.I <search.h>
> +or
> +.I <signal.h>
> +or
> +.I <stdio.h>
> +or
> +.I <stdlib.h>
> +or
> +.I <string.h>
> +or
> +.I <strings.h>
> +or
> +.I <sys/mman.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/sem.h>
> +or
> +.I <sys/shm.h>
> +or
> +.I <sys/socket.h>
> +or
> +.I <sys/uio.h>
> +or
> +.I <time.h>
> +or
> +.I <unistd.h>
> +or
> +.I <wchar.h>
> +or
> +.IR <wordexp.h> .
> +.IP
> +Used for a count of bytes.  It is the result of the
> +.I sizeof
> +operator.
> +According to the C language standard,
> +it shall be an unsigned integer type
> +capable of storing values in the range [0,
> +.BR SIZE_MAX ].
> +.IP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.IP
> +Notes:
> +.IR <aio.h> ,
> +.IR <glob.h> ,
> +.IR <grp.h> ,
> +.IR <iconv.h> ,
> +.IR <mqueue.h> ,
> +.IR <pwd.h> ,
> +.IR <signal.h>
> +and
> +.IR <sys/socket.h>
> +define
> +.I size_t
> +since POSIX.1-2008.
> +.IP
> +See also:
> +.BR fread (3),
> +.BR fwrite (3),
> +.BR memcmp (3),
> +.BR memcpy (3),
> +.BR memset (3),
> +.BR offsetof (3)
> +.IP
> +See also the
> +.I ssize_t
> +and
> +.I ptrdiff_t
> +types in this page.
> +.TP
>  .I ssize_t
>  .IP
>  Include:
> @@ -127,10 +222,10 @@ See also:
>  .BR recv (2),
>  .BR send (2),
>  .BR write (2)
> -.\".IP	FIXME: When size_t is added, uncomment
> -.\"See also the
> -.\".I size_t
> -.\"type in this page.
> +.IP
> +See also the
> +.I size_t
> +type in this page.
>  .TP
>  .I suseconds_t
>  .IP
>
  

On Fri, Sep 18, 2020 at 01:27:55PM +0200, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
>  1 file changed, 99 insertions(+), 4 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 84fea85b9..041e7e243 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7

The distinction might not be worth highlighting here, but types like
size_t are a bit special in that they come from the C standards and
assumptions about them are really built into the compiler.

The system can define its own size_t, but it had better be equivalent
to the compiler's definition otherwise bad things will
happen...


> @@ -92,6 +92,101 @@ See also:
>  .\".I siginfo_t
>  .\"type in this page.
>  .TP
> +.I size_t
> +.IP
> +Include:
> +.I <stddef.h>
> +or

Where does this arbitrary-looking list of headers come from?

From the C standards at least, <stddef.h> seems to be the canonical
header for this type.


> +.IR <sys/types.h> ;
> +or
> +.I <aio.h>
> +or
> +.I <glob.h>
> +or
> +.I <grp.h>
> +or
> +.I <iconv.h>
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>

[...]

Cheers
---Dave
  

Hi Dave,

On 2020-09-28 15:41, Dave Martin wrote:
> On Fri, Sep 18, 2020 at 01:27:55PM +0200, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>   man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
>>   1 file changed, 99 insertions(+), 4 deletions(-)
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index 84fea85b9..041e7e243 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
> 
> The distinction might not be worth highlighting here, but types like
> size_t are a bit special in that they come from the C standards and
> assumptions about them are really built into the compiler.
> 
> The system can define its own size_t, but it had better be equivalent
> to the compiler's definition otherwise bad things will
> happen...
> 
> 
>> @@ -92,6 +92,101 @@ See also:
>>   .\".I siginfo_t
>>   .\"type in this page.
>>   .TP
>> +.I size_t
>> +.IP
>> +Include:
>> +.I <stddef.h>
>> +or
> 
> Where does this arbitrary-looking list of headers come from?

There are two parts:  left to the ';', and right to the ';'.

Left: The canonical C standard header, and the canonical POSIX header, 
in alphabetical order.

Right: All other headers that shall define the header, according to 
either the C or the POSIX standards, in alphabetical order.

Cheers,

Alex

> 
>  From the C standards at least, <stddef.h> seems to be the canonical
> header for this type.
> 
> 
>> +.IR <sys/types.h> ;
>> +or
>> +.I <aio.h>
>> +or
>> +.I <glob.h>
>> +or
>> +.I <grp.h>
>> +or
>> +.I <iconv.h>
>> +or
>> +.I <monetary.h>
>> +or
>> +.I <mqueue.h>
> 
> [...]
> 
> Cheers
> ---Dave
>
  

Hi, Alex!

At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
> > Where does this arbitrary-looking list of headers come from?
> 
> There are two parts:  left to the ';', and right to the ';'.
> 
> Left: The canonical C standard header, and the canonical POSIX header,
> in alphabetical order.
> 
> Right: All other headers that shall define the header, according to
> either the C or the POSIX standards, in alphabetical order.

That's not a bad scheme but it is not inferable from the current man
page text; I almost commented on the inconsistency in one of my earlier
messages but deemed it out of scope.  Please document it, perhaps in an
introductory paragraph at the top of the Description section.

Or, you could spend a word to do the same work:

gid_t   Include: <sys/types.h>.  Alternatively, <grp.h>, <pwd.h>,
<signal.h>, <stropts.h>, <sys/ipc.h>, <sys/stat.h>, or <unistd.h>.

Regards,
Branden
  

On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
> > > Where does this arbitrary-looking list of headers come from?
> > 
> > There are two parts:  left to the ';', and right to the ';'.
> > 
> > Left: The canonical C standard header, and the canonical POSIX header,
> > in alphabetical order.
> > 
> > Right: All other headers that shall define the header, according to
> > either the C or the POSIX standards, in alphabetical order.

To clarify, does POSIX _guarantee_ that all of those headers define this
type?  (I admit I'm too lazy to search through the POSIX standard for an
answer to this).

If not, this list would serve only to legitimise bad habits and it may
be better to leave it out.


> That's not a bad scheme but it is not inferable from the current man
> page text; I almost commented on the inconsistency in one of my earlier
> messages but deemed it out of scope.  Please document it, perhaps in an
> introductory paragraph at the top of the Description section.

Ack, I think it would be better to state this explicity rather than
having some terse syntax that people need to understand.


IIUC, a program intended to be fully portable between C implementations
must include <stddef.h>, not rely on one of the others.

(In practice it seems reasonable to include any header that is specified
to declare types or function prototypes that themselves require a
definition of size_t, but this is awkward to describe, and not explicit
in the standard.)

[...]

Cheers
---Dave
  

Hi Branden,

On 2020-09-28 15:55, G. Branden Robinson wrote:
 > Hi, Alex!
 >
 > At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
 >>> Where does this arbitrary-looking list of headers come from?
 >>
 >> There are two parts:  left to the ';', and right to the ';'.
 >>
 >> Left: The canonical C standard header, and the canonical POSIX header,
 >> in alphabetical order.
 >>
 >> Right: All other headers that shall define the header, according to
 >> either the C or the POSIX standards, in alphabetical order.
 >
 > That's not a bad scheme but it is not inferable from the current man
 > page text; I almost commented on the inconsistency in one of my earlier
 > messages but deemed it out of scope.  Please document it, perhaps in an
 > introductory paragraph at the top of the Description section.
 >
 > Or, you could spend a word to do the same work:
 >
 > gid_t   Include: <sys/types.h>.  Alternatively, <grp.h>, <pwd.h>,
 > <signal.h>, <stropts.h>, <sys/ipc.h>, <sys/stat.h>, or <unistd.h>.
 >
 > Regards,
 > Branden
 >
Thanks!

We talked about it. I wasn't convinced by my scheme,
but we couldn't come up with a better solution, so we kept that.

For the readers, it wasn't clear, but for the developers of the page,
I wrote a comment at the beginning of the page,
which I hope was clear enough:

.\" Layout:
.\"	A list of type names (the struct/union keyword will be omitted).
.\"	Each entry will have the following parts:
.\"		* Include
.\"			The headers will be in the following order:
.\"			1) The main header that shall define the type
.\"			   according to the C Standard,
.\"			   and
.\"			   the main header that shall define the type
.\"			   according to POSIX,
.\"			   in alphabetical order.
.\"			;
.\"			2) All other headers that shall define the type
.\"			   as described in the previous header(s)
.\"			   according to the C Standard or POSIX,
.\"			   in alphabetical order.
.\"			*) All headers that define the type
.\"			   *if* the type is not defined by C nor POSIX,
.\"			   in alphabetical order.
.\"
.\"		* Definition (no "Definition" header)
.\"			Only struct/union types will have definition;
.\"			typedefs will remain opaque.
.\"
.\"		* Description (no "Description" header)
.\"			A few lines describing the type.
.\"
.\"		* Conforming to
.\"			Format: CXY and later; POSIX.1-XXXX and later.
.\"			Forget about pre-C99 C standards (i.e., C89/C90)
.\"
.\"		* Notes (optional)
.\"
.\"		* See also

But I like very much your "Alternatively, " wording.  I'll use it!

Thanks,

Alex
  

Hi Dave!

On 2020-09-28 16:15, Dave Martin wrote:
> On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote:
>> Hi, Alex!
>>
>> At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
>>>> Where does this arbitrary-looking list of headers come from?
>>>
>>> There are two parts:  left to the ';', and right to the ';'.
>>>
>>> Left: The canonical C standard header, and the canonical POSIX header,
>>> in alphabetical order.
>>>
>>> Right: All other headers that shall define the header, according to
>>> either the C or the POSIX standards, in alphabetical order.
> 
> To clarify, does POSIX _guarantee_ that all of those headers define this
> type?  (I admit I'm too lazy to search through the POSIX standard for an
> answer to this).

Yes, POSIX does guarantee that all those headers define the type.

> 
> If not, this list would serve only to legitimise bad habits and it may
> be better to leave it out.
> 
> 
>> That's not a bad scheme but it is not inferable from the current man
>> page text; I almost commented on the inconsistency in one of my earlier
>> messages but deemed it out of scope.  Please document it, perhaps in an
>> introductory paragraph at the top of the Description section.
> 
> Ack, I think it would be better to state this explicity rather than
> having some terse syntax that people need to understand.

Would you like to propose something?

> 
> 
> IIUC, a program intended to be fully portable between C implementations
> must include <stddef.h>, not rely on one of the others.

Yes, in principle, programmers should use the first header in the list.
However, we listed all of them for completeness.  We only listed headers 
that guarantee to define the type, thogh, either by C or POSIX:


.\" Layout:
.\"	A list of type names (the struct/union keyword will be omitted).
.\"	Each entry will have the following parts:
.\"		* Include
.\"			The headers will be in the following order:
.\"			1) The main header that shall define the type
.\"			   according to the C Standard,
.\"			   and
.\"			   the main header that shall define the type
.\"			   according to POSIX,
.\"			   in alphabetical order.
.\"			;
.\"			2) All other headers that shall define the type
.\"			   as described in the previous header(s)
.\"			   according to the C Standard or POSIX,
.\"			   in alphabetical order.
.\"			*) All headers that define the type
.\"			   *if* the type is not defined by C nor POSIX,
.\"			   in alphabetical order.
.\"
.\"		* Definition (no "Definition" header)
.\"			Only struct/union types will have definition;
.\"			typedefs will remain opaque.
.\"
.\"		* Description (no "Description" header)
.\"			A few lines describing the type.
.\"
.\"		* Conforming to
.\"			Format: CXY and later; POSIX.1-XXXX and later.
.\"			Forget about pre-C99 C standards (i.e., C89/C90)
.\"
.\"		* Notes (optional)
.\"
.\"		* See also

> 
> (In practice it seems reasonable to include any header that is specified
> to declare types or function prototypes that themselves require a
> definition of size_t, but this is awkward to describe, and not explicit
> in the standard.)
> 
> [...]
> 
> Cheers
> ---Dave
> 

Cheers,

Alex
  

Hi Dave,

On Mon, 28 Sep 2020 at 16:15, Dave Martin <Dave.Martin@arm.com> wrote:
>
> On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote:
> > Hi, Alex!
> >
> > At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
> > > > Where does this arbitrary-looking list of headers come from?
> > >
> > > There are two parts:  left to the ';', and right to the ';'.
> > >
> > > Left: The canonical C standard header, and the canonical POSIX header,
> > > in alphabetical order.
> > >
> > > Right: All other headers that shall define the header, according to
> > > either the C or the POSIX standards, in alphabetical order.
>
> To clarify, does POSIX _guarantee_ that all of those headers define this
> type?  (I admit I'm too lazy to search through the POSIX standard for an
> answer to this).
>
> If not, this list would serve only to legitimise bad habits and it may
> be better to leave it out.

As I think Alex has clarified, the info about headers is being taken from POSIX.

> > That's not a bad scheme but it is not inferable from the current man
> > page text; I almost commented on the inconsistency in one of my earlier
> > messages but deemed it out of scope.  Please document it, perhaps in an
> > introductory paragraph at the top of the Description section.
>
> Ack, I think it would be better to state this explicity rather than
> having some terse syntax that people need to understand.

Yes, I think some more explanatory text is probably needed. This page
is still very much a work in progress.

> IIUC, a program intended to be fully portable between C implementations
> must include <stddef.h>, not rely on one of the others.

Just to note a point here: my main concern is portability across POSIX systems.

Thanks,

Michael
  

On Fri, 18 Sep 2020, Paul Eggert wrote:

> On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote:
> > the length modifier for printf and scanf is z, commently used as
> > %zu or %zx (%zd is for ssize_t).
> 
> While %zd works for ssize_t in glibc, POSIX doesn't guarantee that it'll work,
> as ssize_t might not have the same width as size_t. (If memory serves this
> goes back to the bad old days when size_t was 64 bits and ssize_t 32 bits on
> some platforms.) So if we document %zd we should say it's a GNU extension to
> POSIX, or something like that.

%zd is for the signed type corresponding to size_t; that's in ISO C.  The 
GNU extension would be a guarantee that ssize_t is the signed type 
corresponding to size_t (if we do guarantee that).
  

On Mon, 28 Sep 2020, Alejandro Colomar via Libc-alpha wrote:

> > To clarify, does POSIX _guarantee_ that all of those headers define this
> > type?  (I admit I'm too lazy to search through the POSIX standard for an
> > answer to this).
> 
> Yes, POSIX does guarantee that all those headers define the type.

For a lot of cases where a header contains a function using a type in its 
prototype, current POSIX requires that type to be defined in the header, 
but older POSIX permitted it (by virtue of the *_t reservation) but did 
not require it unless XSI extensions were enabled.

The preferred glibc practice in such cases where older POSIX permitted the 
definition and included functions using the type is not to make the 
definition of the type in the header conditional on the POSIX version / 
XSI extensions, but to enable the definition for all standards that 
include the relevant function.  (This simplifies the headers, and also 
simplifies the conform/ tests because they then don't need to handle 
testing for a declaration of a function without being able to write its 
type in the most straightforward way.)

The headers still need to include feature test macro conditionals and 
special handling where a header is required by some standard to declare a 
function without defining the corresponding type name.  (For example, ISO 
C does not permit <stdio.h> to define va_list, so the header has to use an 
implementation-namespace name for that type when declaring vprintf.)