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

Hello,

there is probably a wrong number in description of statfs structure. In description section, struct statfs contains as a last field f_spare[5]. But the /usr/include/bits/statfs.h itself contains f_spare[4] (glibc-headers-2.18 on f20).

Looking into glibc-2.20, there is f_spare[6]. Looks like the structure is gradually evolving :).

Inspecting upstream history (gitk statfs.h), it shows it was f_spare[6] since 1997.

Regards
Jan

Signature · 3 lines

To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

can you help me with this? I have problems finding out why the statfs.h tarball of glibc contains f_spare[6], but the resulting build contains f_spare[4]? There is no patch that changes the 6 to 4. Looking into spec file, I am lost.

there is probably a wrong number in description of statfs structure. In description section, struct statfs contains as a last field f_spare[5]. But the /usr/include/bits/statfs.h itself contains f_spare[4] (glibc-headers-2.18 on f20).

Looking into glibc-2.20, there is f_spare[6]. Looks like the structure is gradually evolving :).

Inspecting upstream history (gitk statfs.h), it shows it was f_spare[6] since 1997.

Quoted 5 lines · Jan Chaloupka

there is probably a wrong number in description of statfs structure. In description section, struct statfs contains as a last field f_spare[5]. But the /usr/include/bits/statfs.h itself contains f_spare[4] (glibc-headers-2.18 on f20).

Quoted 5 lines

Looking into glibc-2.20, there is f_spare[6]. Looks like the structure is gradually evolving :).

Inspecting upstream history (gitk statfs.h), it shows it was f_spare[6] since 1997.

i wonder if we should strip f_spare from the man page. it's not really useful.

the __SWORD_TYPE should probably be replaced with __fsword_t, and drop the __WORDSIZE logic. that gets ugly with syscall ABIs.

-mike

Quoted 6 lines · Mike Frysinger

Quoted 5 lines · Jan Chaloupka

there is probably a wrong number in description of statfs structure. In description section, struct statfs contains as a last field f_spare[5]. But the /usr/include/bits/statfs.h itself contains f_spare[4] (glibc-headers-2.18 on f20).

Quoted 6 lines

Quoted 5 lines

Looking into glibc-2.20, there is f_spare[6]. Looks like the structure is gradually evolving :).

Inspecting upstream history (gitk statfs.h), it shows it was f_spare[6] since 1997.

i wonder if we should strip f_spare from the man page. it's not really useful.

I would prefer to keep f_spare.

As Siddhesh wrote, statfs.h is architecture/OS dependent in general. In a case of fedora (f20, f22) armv7hl, x86_64 and i686 has f_spare[4].

We could add a sentence right under struct statfs:
"Depending on your architecture or OS, length of f_spare of statfs struct can vary."

Quoted 2 lines

the __SWORD_TYPE should probably be replaced with __fsword_t, and drop the __WORDSIZE logic. that gets ugly with syscall ABIs.

I am not sure if __SWORD_TYPE is no longer valid type and is replace
by __fsword_t everywhere (all architectures and OS).

Quoted 12 lines · Jan Chaloupka

Quoted 11 lines · Mike Frysinger

Quoted 10 lines · Jan Chaloupka

there is probably a wrong number in description of statfs structure. In description section, struct statfs contains as a last field f_spare[5]. But the /usr/include/bits/statfs.h itself contains f_spare[4] (glibc-headers-2.18 on f20).

Looking into glibc-2.20, there is f_spare[6]. Looks like the structure is gradually evolving :).

Inspecting upstream history (gitk statfs.h), it shows it was f_spare[6] since 1997.

Quoted 3 lines

Quoted 1 line

i wonder if we should strip f_spare from the man page. it's not really useful.

I would prefer to keep f_spare.

why ? it serves no useful purpose, and people should be including the header to get the definition. the man page is there to describe the fields that actually get used.

Quoted 6 lines

As Siddhesh wrote, statfs.h is architecture/OS dependent in general. In a case of fedora (f20, f22) armv7hl, x86_64 and i686 has f_spare[4].

We could add a sentence right under struct statfs:
"Depending on your architecture or OS, length of f_spare of statfs struct can vary."

this man page is Linux specific

Quoted 5 lines

Quoted 2 lines

the __SWORD_TYPE should probably be replaced with __fsword_t, and drop the __WORDSIZE logic. that gets ugly with syscall ABIs.

I am not sure if __SWORD_TYPE is no longer valid type and is replace
by __fsword_t everywhere (all architectures and OS).

the latest headers use __fsword_t

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.

Quoted 35 lines · Michael Kerrisk (man-pages)

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:

Quoted 6 lines

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 :).