Re: statfs.2: f_spare[4] or f_spare[5]

[Mike Frysinger <vapier-aBrp7R+bbdUdnm+yROfE0A@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 2838 bytes --]

On 05 Feb 2015 10:39, Michael Kerrisk (man-pages) wrote:
> Rich Felker a while back also wrote about problems in the man page:
> http://thread.gmane.org/gmane.linux.man/6749
> 
> [[
> The man page for statfs(2) is using macros which are glibc
> implementation internals (not part of the public interface) for
> defining struct statfs. This leads programmers to believe they should
> use these macros in applications (a cast to __SWORD_TYPE has recently
> appeared in util-linux; see link [1] below) and __SWORD_TYPE isn't
> even the correct type on glibc/x32.
> 
> Note that glibc also has the signedness of these members wrong; in the
> kernel, they're rightfully unsigned for 32-bit and only signed on
> 64-bit (where it doesn't matter). musl does not have this mismatch; we
> use unsigned types where they make sense (e.g. storing unsigned
> filesystem magic numbers that don't fit in signed 32-bit).
> 
> Since the types of these fields are such a mess, I think the man page
> should refrain from documenting specific types, and should include
> advice on safe usage, including how to safely compare f_type -- on
> glibc, the value will wrongly be negative for many filesystems, and
> although default integer promotions will fix this for direct
> comparison with the fs magic constants, the safe way to use f_type
> seems to be explicitly casting it to uint32_t.
> ]]
> 
> So, this all seems a glibc mess to me. However,perhaps I'm not 
> understanding something. What is the glibc expectation, regarding 
> how people should work with these fields? I mean, suppose one wants
> to copy one of the __fsword_t to a local variable, what type is
> one supposed to do? What I'd kind of hope for is publicly export
> system data(s). But lacking that, what does one do? It appears
> that "unsigned int" should do the job. What about the following 
> text for the man page:
> 
>     The  __fsword_t  type  used  for  various  fields in the statfs
>     structure definition is a glibc internal type, not intended for
>     public use.  This leaves the programmer in a bit of a conundrum
>     when trying to copy or compare these fields to local  variables
>     in  a  program.  Using unsigned int for such variables suffices
>     on most systems.

looking at the history of the file in glibc (which stretches back to at least 
1995), i think trying to deal with differences across arches/ABIs/OSs/LFS 
settings has lead it to be macro heavy in favor of the maintainers rather than 
directly considering the usage by developers.  especially since the function 
isn't documented in the glibc manual ... it's being provided more as a low 
level/historical requirement rather than a desire to get it right.

maybe Roland can comment since he's the author of some of these commits :).
-mike

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]