[f]statfs(2) shaded as deprecated?

* [f]statfs(2) shaded as deprecated?
@ 2023-06-23 19:58 наб
  2023-06-23 20:08 ` Alejandro Colomar
  0 siblings, 1 reply; 11+ messages in thread
From: наб @ 2023-06-23 19:58 UTC (permalink / raw)
  To: Alejandro Colomar (man-pages); +Cc: linux-man

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

Hi!

After the bookworm update I've found that statfs.2 is shaded
[[deprecated]], citing
  LSB has deprecated the library calls statfs() and fstatfs() and tells
  us to use statvfs(3) and fstatvfs(3) instead.

"LSB" doesn't appear to be, well, anything, inasmuch as
  man-pages$ git grep LSB
  Changes.old:        Remove statement that LSB deprecates the functions
  Changes.old:        being deprecated in any of the LSB specs).  Rather, LSB simply
  Changes.old:        doesn't specify these functions.  (LSB 1.3 had a spec of
  man2/statfs.2:LSB has deprecated the library calls
  man3/gets.3:LSB deprecates
  man5/elf.5:.B ELFDATA2LSB
  man-pages$ git grep -i 'standard base'

I, logically, know that LSB refers to the linux standard base, but I
don't see how it's relevant here. What's the stated reason? Is this part
of any publication?

This function is not marked as deprecated in either glibc or musl,
and, indeed, on both implementations statvfs is just
  return statfs_to_statvfs(statfs(...));

Normally, like who cares, and statvfs is the standard interface!,
but they carry disjoint data; they agree on
  f_bavail f_bfree f_blocks f_bsize f_ffree f_files f_flag/f_flags f_frsize f_fsid f_namemax/f_namelen
but struct statvfs has
  fsfilcnt_t f_favail;  /* Number of free inodes for unprivileged users */
to which glibc says
  /* XXX I have no idea how to compute f_favail.  Any idea???  */
  buf->f_favail = buf->f_ffree;
(this bug appears unnoted in the manual) and, much more importantly,
struct statfs has
  __fsword_t f_type;    /* Type of filesystem (see below) */
which is removed in struct statvfs.

(struct statvfs also has one field for f_fsid whereas it's two fields in
 struct statfs, and this is truncated during the conversion;
 this appears to just amount to a loss of entropy, so.)

The standard fully allows having having the field there as an extension,
and thankfully both musl and glibc carry six ints of padding in
struct statvfs, so this could be done, but isn't.

(Indeed, on glibc/Hurd struct statvfs already has an __f_type in there;
 this should be an uncontroversial change.)

Nevertheless, statfs() is shaded deprecated in favour of statvfs(),
contrary to all implementations, on shaky ground, and statvfs() cannot
actually replace statfs().

To this end, then:
  * note that under Linux libcs, f_ffree = f_favail
  * unshade statfs(2) as deprecated
    (instead put a note at the end of the SYNOPSIS saying
     "Use the standard interface (statvfs(3)) unless you need f_type."
     or something to that effect?)
  * post to glibc a patch renaming __f_type to f_type on Hurd
  * post to glibc a patch replacing one of the __f_spares with f_type
  * ibid. but musl
  * once that lands, /then/ maybe mark statfs() as deprecated
    (for weird types and nonportability)
  * add f_type to statvfs(3) as "Filesystem type (Linux only, see
	statfs(2) for possible values)"

I've cooked up the libc patches but wanted to see if we're in agreement
here (and also wanted to have a list link to include in the messages).

Best,
наб

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 11+ messages in thread