[PATCH] fsync.2: no writability requirements, must operate on directories

[PATCH] fsync.2: no writability requirements, must operate on directories

[наб]

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

POSIX has for a long time implied that directories are fsyncable,
and since Issue 8 explicitly specifies directory syncing semantics:
  https://www.austingroupbugs.net/view.php?id=672

Simultaneously, directories being unopenable for writing is a
Longest-Standing UNIX Semantic, present in the UNIX Programmer's Manual
under directory (V), and has always been enshrined in the standards.

Kill the FUD that says that some UNIXes require the fd to be writable:
they /must not/ and this confuses users:
  https://101010.pl/@eater@cijber.social/110824211348995583

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man2/fsync.2 | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/man2/fsync.2 b/man2/fsync.2
index 1043e6a1b..9ced40b28 100644
--- a/man2/fsync.2
+++ b/man2/fsync.2
@@ -155,12 +155,6 @@ .SH VERSIONS
 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 .\" -1: unavailable, 0: ask using sysconf().
 .\" glibc defines them to 1.
-.PP
-On some UNIX systems (but not Linux),
-.I fd
-must be a
-.I writable
-file descriptor.
 .SH STANDARDS
 POSIX.1-2008.
 .SH HISTORY
-- 
2.39.2

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

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1515 bytes --]

Hi!

On 2023-08-03 13:52, наб wrote:
> POSIX has for a long time implied that directories are fsyncable,
> and since Issue 8 explicitly specifies directory syncing semantics:
>   https://www.austingroupbugs.net/view.php?id=672
> 
> Simultaneously, directories being unopenable for writing is a
> Longest-Standing UNIX Semantic, present in the UNIX Programmer's Manual
> under directory (V), and has always been enshrined in the standards.
> 
> Kill the FUD that says that some UNIXes require the fd to be writable:
> they /must not/ and this confuses users:
>   https://101010.pl/@eater@cijber.social/110824211348995583
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>  man2/fsync.2 | 6 ------
>  1 file changed, 6 deletions(-)
> 
> diff --git a/man2/fsync.2 b/man2/fsync.2
> index 1043e6a1b..9ced40b28 100644
> --- a/man2/fsync.2
> +++ b/man2/fsync.2
> @@ -155,12 +155,6 @@ .SH VERSIONS
>  .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
>  .\" -1: unavailable, 0: ask using sysconf().
>  .\" glibc defines them to 1.
> -.PP
> -On some UNIX systems (but not Linux),
> -.I fd
> -must be a
> -.I writable
> -file descriptor.

But that's still true.  HP-UX and AIX had that issue.  I'd move
that paragraph to HISTORY, and say "some old UNIX systems".

Cheers,
Alex

>  .SH STANDARDS
>  POSIX.1-2008.
>  .SH HISTORY

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1642 bytes --]

On 2023-08-03 15:22, Alejandro Colomar wrote:
> Hi!
> 
> On 2023-08-03 13:52, наб wrote:
>> POSIX has for a long time implied that directories are fsyncable,
>> and since Issue 8 explicitly specifies directory syncing semantics:
>>   https://www.austingroupbugs.net/view.php?id=672
>>
>> Simultaneously, directories being unopenable for writing is a
>> Longest-Standing UNIX Semantic, present in the UNIX Programmer's Manual
>> under directory (V), and has always been enshrined in the standards.
>>
>> Kill the FUD that says that some UNIXes require the fd to be writable:
>> they /must not/ and this confuses users:
>>   https://101010.pl/@eater@cijber.social/110824211348995583
>>
>> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
>> ---
>>  man2/fsync.2 | 6 ------
>>  1 file changed, 6 deletions(-)
>>
>> diff --git a/man2/fsync.2 b/man2/fsync.2
>> index 1043e6a1b..9ced40b28 100644
>> --- a/man2/fsync.2
>> +++ b/man2/fsync.2
>> @@ -155,12 +155,6 @@ .SH VERSIONS
>>  .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
>>  .\" -1: unavailable, 0: ask using sysconf().
>>  .\" glibc defines them to 1.
>> -.PP
>> -On some UNIX systems (but not Linux),
>> -.I fd
>> -must be a
>> -.I writable
>> -file descriptor.
> 
> But that's still true.  HP-UX and AIX had that issue.  I'd move
> that paragraph to HISTORY, and say "some old UNIX systems".

s/old/ancient/  :)

> 
> Cheers,
> Alex
> 
>>  .SH STANDARDS
>>  POSIX.1-2008.
>>  .SH HISTORY
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[наб]

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

On Thu, Aug 03, 2023 at 03:22:50PM +0200, Alejandro Colomar wrote:
> > diff --git a/man2/fsync.2 b/man2/fsync.2
> > index 1043e6a1b..9ced40b28 100644
> > --- a/man2/fsync.2
> > +++ b/man2/fsync.2
> > @@ -155,12 +155,6 @@ .SH VERSIONS
> >  .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
> >  .\" -1: unavailable, 0: ask using sysconf().
> >  .\" glibc defines them to 1.
> > -.PP
> > -On some UNIX systems (but not Linux),
> > -.I fd
> > -must be a
> > -.I writable
> > -file descriptor.
> But that's still true.  HP-UX and AIX had that issue.  I'd move
> that paragraph to HISTORY, and say "some old UNIX systems".
Apparently still true on AIX, fsync(2) "Last Updated: 2023-03-24"
(https://www.ibm.com/docs/en/aix/7.3?topic=f-fsync-fsync-range-subroutine)
says
  Note: The file identified by the FileDescriptor parameter must be open
  for writing when the fsync subroutine is issued or the call is
  unsuccessful. This restriction was not enforced in BSD systems. The
  fsync_range subroutine does not require write access.
and
  EBADF  The FileDescriptor parameter is not a valid file descriptor
         open for writing.

So this purely-nominal restriction is likely to go away because
Issue 8 requires directories to be fsync()able. It appears that classic
UNIXes https://www.austingroupbugs.net/view.php?id=672 (comment 0001499)
simply had no need for fsync() on directories and thus we 


No clue about recent HP-UX, no offline documentation seems to be extant.


History-wise, this is invented in 4.1c.1BSD in its present-day form,
then SysVr4 copies it but plain invents the writability restriction,
so this interface is just plain broken on SysV, good job AT&T.

Try this on for size:
-- >8 --
Subject: [PATCH v2] fsync.2: no writability requirements, must operate on
 directories

POSIX has for a long time implied that directories are fsyncable,
and since Issue 8 explicitly specifies directory syncing semantics:
  https://www.austingroupbugs.net/view.php?id=672

Simultaneously, directories being unopenable for writing is a
Longest-Standing UNIX Semantic, present in the UNIX Programmer's Manual
under directory (V), and has always been enshrined in the standards.

Replace the FUD that says that some UNIXes require the fd to be writable:
they /must not/ and this confuses users:
  https://101010.pl/@eater@cijber.social/110824211348995583
with mentioning explicitly that HP-UX and AIX (by name) are just broken.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man2/fsync.2 | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/man2/fsync.2 b/man2/fsync.2
index 1043e6a1b..6a7739056 100644
--- a/man2/fsync.2
+++ b/man2/fsync.2
@@ -155,12 +155,6 @@ .SH VERSIONS
 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 .\" -1: unavailable, 0: ask using sysconf().
 .\" glibc defines them to 1.
-.PP
-On some UNIX systems (but not Linux),
-.I fd
-must be a
-.I writable
-file descriptor.
 .SH STANDARDS
 POSIX.1-2008.
 .SH HISTORY
@@ -181,6 +175,13 @@ .SH HISTORY
 or
 .BR sdparm (8)
 to guarantee safe operation.
+.PP
+Under AT&T UNIX System V Release 4
+.I fd
+needs to be opened for writing.
+This is by itself incompatible with the original BSD interface,
+and is now forbidden by POSIX,
+but nevertheless survives in HP-UX and AIX.
 .SH SEE ALSO
 .BR sync (1),
 .BR bdflush (2),
-- 
2.39.2

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

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[Jakub Wilk]

* наб <nabijaczleweli@nabijaczleweli.xyz>, 2023-08-03 16:20:
>Replace the FUD

Do you mean to imply that this paragraph was added in bad faith?
Because that's how it sounds.

-- 
Jakub Wilk

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[наб]

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

On Thu, Aug 03, 2023 at 05:18:38PM +0200, Jakub Wilk wrote:
> * наб <nabijaczleweli@nabijaczleweli.xyz>, 2023-08-03 16:20:
> > Replace the FUD
> Do you mean to imply that this paragraph was added in bad faith?
> Because that's how it sounds.
I think it's definitely being adversarial to the reader, yes.
Hard to come up with a better newbie trap than vaguely saying
"on some (possibly popular) systems you need a property
 which fundamentally excludes half of the use-cases",
bonus points for making that property an
obscure-if-you-don't-know-about-it operation on directories,
documented once half-way through the fifty errors in open(2).

It would have cost approximately nothing to include HP-UX and AIX in the
text (especially since they're already in the commit message),
or to mention the directory syncing usecase explicitly here,
or up to 5 minutes to arrive at the bisection I got,
or write this in a way that isn't FUD,
so it must've been on purpose.

Best,

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

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[G. Branden Robinson]

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

Hi наб,

At 2023-08-03T18:54:14+0200, наб wrote:
> I think it's definitely being adversarial to the reader, yes.  Hard to
> come up with a better newbie trap than vaguely saying "on some
> (possibly popular) systems you need a property which fundamentally
> excludes half of the use-cases", bonus points for making that property
> an obscure-if-you-don't-know-about-it operation on directories,
> documented once half-way through the fifty errors in open(2).
> 
> It would have cost approximately nothing to include HP-UX and AIX in
> the text (especially since they're already in the commit message), or
> to mention the directory syncing usecase explicitly here, or up to 5
> minutes to arrive at the bisection I got, or write this in a way that
> isn't FUD, so it must've been on purpose.

It might have been an effort at making the more robust to obsolescence.
Who knows what AIX or HP-UX will do with fsync(2)?  Will their vendors
let the Linux man-pages community know if their kernels change?  How
many Linux man-pages contributors have access to these systems to check?

Possibly better would have been to gather (from Guillem Jover,
apparently) the `uname -r` versions of HP-UX and AIX and annotate those
specifically.  Anyone who didn't run those systems could ignore the
admonition, anyone had those exact versions would be advised, and
anyone who ran a different version of them would know they'd probably
have to test the implementation themselves.

There are sometimes innocent explanations for things.  (But the
exceptions really do sting.)

Regards,
Branden

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

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[Guillem Jover]

Hi!

On Thu, 2023-08-03 at 16:20:10 +0200, наб wrote:
> On Thu, Aug 03, 2023 at 03:22:50PM +0200, Alejandro Colomar wrote:
> > > diff --git a/man2/fsync.2 b/man2/fsync.2
> > > index 1043e6a1b..9ced40b28 100644
> > > --- a/man2/fsync.2
> > > +++ b/man2/fsync.2
> > > @@ -155,12 +155,6 @@ .SH VERSIONS
> > >  .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
> > >  .\" -1: unavailable, 0: ask using sysconf().
> > >  .\" glibc defines them to 1.
> > > -.PP
> > > -On some UNIX systems (but not Linux),
> > > -.I fd
> > > -must be a
> > > -.I writable
> > > -file descriptor.
> > But that's still true.  HP-UX and AIX had that issue.  I'd move
> > that paragraph to HISTORY, and say "some old UNIX systems".

> Apparently still true on AIX, fsync(2) "Last Updated: 2023-03-24"
> (https://www.ibm.com/docs/en/aix/7.3?topic=f-fsync-fsync-range-subroutine)
> says
>   Note: The file identified by the FileDescriptor parameter must be open
>   for writing when the fsync subroutine is issued or the call is
>   unsuccessful. This restriction was not enforced in BSD systems. The
>   fsync_range subroutine does not require write access.
> and
>   EBADF  The FileDescriptor parameter is not a valid file descriptor
>          open for writing.

Yes. Also from current dpkg git HEAD on "AIX power8-aix 2 7 00F9C1964C00":

  checking whether fsync works on directories... no

out of:

  https://git.dpkg.org/cgit/dpkg/dpkg.git/tree/m4/dpkg-funcs.m4#n28

> So this purely-nominal restriction is likely to go away because
> Issue 8 requires directories to be fsync()able. It appears that classic
> UNIXes https://www.austingroupbugs.net/view.php?id=672 (comment 0001499)
> simply had no need for fsync() on directories and thus we 

That's still not released though? And after skimming over the proposed
changes, I'm not sure they match reality either on Linux? For example,
the current amount of fsync() done by dpkg for all filesystem objects
(not just the db it had always historically done) was precisely to
avoid 0-sized files that it was getting on abrupt system termination
at least on ext3 and ext4(?). (I'm not sure whether this has improved
since then though, but at the time the Linux filesystem developers
pretty much said this was a problem with userland code as developers
were "writing buggy code".)

> No clue about recent HP-UX, no offline documentation seems to be extant.

The page I found at the time is still on the Internet Archive:

  https://web.archive.org/web/20080906221105/http://h30097.www3.hp.com/docs/base_doc/DOCUMENTATION/V50_HTML/MAN/MAN2/0033____.HTM

but I do not have access to a current HP-UX system, so not sure
whether that might have changed.

Ref:
<https://lore.kernel.org/linux-man/20120101024916.GA16572@gaara.hadrons.org/>

> Try this on for size:
> -- >8 --
> Subject: [PATCH v2] fsync.2: no writability requirements, must operate on
>  directories
> 
> POSIX has for a long time implied that directories are fsyncable,
> and since Issue 8 explicitly specifies directory syncing semantics:
>   https://www.austingroupbugs.net/view.php?id=672

See above.

> Simultaneously, directories being unopenable for writing is a
> Longest-Standing UNIX Semantic, present in the UNIX Programmer's Manual
> under directory (V), and has always been enshrined in the standards.

> Replace the FUD that says that some UNIXes require the fd to be writable:
> they /must not/ and this confuses users:
>   https://101010.pl/@eater@cijber.social/110824211348995583
> with mentioning explicitly that HP-UX and AIX (by name) are just broken.

To me whether this is supposed to conform to some historic semantics
does not seem very relevant when making code portable, and when that
contradicts the specific system explicit documentation and behavior.
And then "FUD" seems completely out of line here (even though I didn't
write that man page update), and incorrect, because there _are_ such
systems in existence…

> @@ -181,6 +175,13 @@ .SH HISTORY
>  or
>  .BR sdparm (8)
>  to guarantee safe operation.
> +.PP
> +Under AT&T UNIX System V Release 4
> +.I fd
> +needs to be opened for writing.
> +This is by itself incompatible with the original BSD interface,
> +and is now forbidden by POSIX,
> +but nevertheless survives in HP-UX and AIX.
>  .SH SEE ALSO
>  .BR sync (1),
>  .BR bdflush (2),

My intention when I mentioned the currently documented behavior in 2012,
was to help other people that might stumble over this portability issue.
If the current documentation is not clear, then let's improve it. But
this update seems more confusing than helpful to me, in addition of
being wrong as there's no current POSIX version that forbids this.

Thanks,
Guillem

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[наб]

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

Hi!

On Fri, Aug 04, 2023 at 12:07:38PM +0200, Guillem Jover wrote:
> On Thu, 2023-08-03 at 16:20:10 +0200, наб wrote:
> > On Thu, Aug 03, 2023 at 03:22:50PM +0200, Alejandro Colomar wrote:
> > > > diff --git a/man2/fsync.2 b/man2/fsync.2
> > > > index 1043e6a1b..9ced40b28 100644
> > > > --- a/man2/fsync.2
> > > > +++ b/man2/fsync.2
> > > > @@ -155,12 +155,6 @@ .SH VERSIONS
> > > >  .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
> > > >  .\" -1: unavailable, 0: ask using sysconf().
> > > >  .\" glibc defines them to 1.
> > > > -.PP
> > > > -On some UNIX systems (but not Linux),
> > > > -.I fd
> > > > -must be a
> > > > -.I writable
> > > > -file descriptor.
> > > But that's still true.  HP-UX and AIX had that issue.  I'd move
> > > that paragraph to HISTORY, and say "some old UNIX systems".
> > Apparently still true on AIX, fsync(2) "Last Updated: 2023-03-24"
> > (https://www.ibm.com/docs/en/aix/7.3?topic=f-fsync-fsync-range-subroutine)
> > says
> >   Note: The file identified by the FileDescriptor parameter must be open
> >   for writing when the fsync subroutine is issued or the call is
> >   unsuccessful. This restriction was not enforced in BSD systems. The
> >   fsync_range subroutine does not require write access.
> > and
> >   EBADF  The FileDescriptor parameter is not a valid file descriptor
> >          open for writing.
> Yes. Also from current dpkg git HEAD on "AIX power8-aix 2 7 00F9C1964C00":
>   checking whether fsync works on directories... no
> out of:
>   https://git.dpkg.org/cgit/dpkg/dpkg.git/tree/m4/dpkg-funcs.m4#n28
> 
> > So this purely-nominal restriction is likely to go away because
> > Issue 8 requires directories to be fsync()able. It appears that classic
> > UNIXes https://www.austingroupbugs.net/view.php?id=672 (comment 0001499)
> > simply had no need for fsync() on directories and thus we 
> That's still not released though? And after skimming over the proposed
> changes, I'm not sure they match reality either on Linux? For example,
> the current amount of fsync() done by dpkg for all filesystem objects
> (not just the db it had always historically done) was precisely to
> avoid 0-sized files that it was getting on abrupt system termination
> at least on ext3 and ext4(?). (I'm not sure whether this has improved
> since then though, but at the time the Linux filesystem developers
> pretty much said this was a problem with userland code as developers
> were "writing buggy code".)
Fair cop I s'pose, the directory wording is new in Draft 3.
You should probably post to austin-group-l@ if you think they don't
match reality under Linux.

> My intention when I mentioned the currently documented behavior in 2012,
> was to help other people that might stumble over this portability issue.
> If the current documentation is not clear, then let's improve it. But
> this update seems more confusing than helpful to me, in addition of
> being wrong as there's no current POSIX version that forbids this.
It's muddled by coupling it to the directory semantics which are clearly
still in flux.

I read, fsync():
36407  ERRORS
36408  The fsync( ) function shall fail if:
36409    [EBADF] The fildes argument is not a valid descriptor.
36410    [EINTR] The fsync( ) function was interrupted by a signal.
36411    [EINVAL] The fildes argument does not refer to a file on which this operation is possible.
36412    [EIO] An I/O error occurred while reading from or writing to the file system.
36413  In the event that any of the queued I/O operations fail, fsync( ) shall return the error conditions
36414  defined for read( ) and write( ).

36417  APPLICATION USAGE
36418  The fsync( ) function should be used by programs which require modifications to a file to be
36419  completed before continuing; for example, a program which contains a simple transaction
36420  facility might use it to ensure that all modifications to a file or files caused by a transaction are
36421  recorded.

36422  An application that modifies a directory, for example, by creating a file in the directory, can 
36423  invoke fsync( ) on the directory to ensure that the directory’s entries and file attributes are
36424  synchronized. For most applications, synchronizing the directory’s entries should not be
36425  necessary (see XBD Section 4.11, on page 98).

I read, fdatasync():
31161  ERRORS
31162  The fdatasync( ) function shall fail if:
31163    [EBADF]  The fildes argument is not a valid file descriptor.
31164    [EINVAL] This implementation does not support synchronized I/O for this file.
31165  In the event that any of the queued I/O operations fail, fdatasync( ) shall return the error
31166  conditions defined for read( ) and write( ).

31169  APPLICATION USAGE
31170  Note that even if the file descriptor is not open for writing, if there are any pending write
31171  requests on the underlying file, then that I/O will be completed prior to the return of fdatasync( ).

31172  An application that modifies a directory, for example, by creating a file in the directory, can 
31173  invoke fdatasync( ) on the directory to ensure that the directory’s entries are synchronized, 
31174  although for most applications this should not be necessary (see XBD Section 4.11, on page 98).

Synchronized I/O Data Integrity Completion:
2599  For the purpose of this definition, an operation that reads or searches a directory is considered to
2600  be a read operation, an operation that modifies a directory is considered to be a write operation,
2601  and a directory’s entries are considered to be the data read or written.

As being able to f[data]sync() directories being required if the system
supports the Synchronised I/O option or the File Synchronisation option.


The first paragraph in fdatasync() APPLICATION USAGE appears in
Issue 8 2016, which cites
  https://www.austingroupbugs.net/view.php?id=501
which fixes an editorial error by matching fdatasync() and aio_fsync()
to fsync() in making EBADF only for invalid fds.

So, prior to Issue 8, fsync() and fdatasync() are allowed to EINVAL
if they get a directory (maybe in Issue 8 as well, sure, doesn't matter),
but they are /not/ allowed to EBADF if the fd is not writable
(for fdatasync() since 2016 by accident, and
 for fsync() since it was released in Issue 3).

Thus, it's obvious to me that yes, the SysVr4 interface and HP-UX/AIX
interfaces /are/ fundamentally broken and have /always/ been
fundamentally broken, and that the actual semantics for fsync()ing
directories, while defined in Issue 8 Draft 3, are irrelevant here.

> > Replace the FUD that says that some UNIXes require the fd to be writable:
> > they /must not/ and this confuses users:
> >   https://101010.pl/@eater@cijber.social/110824211348995583
> > with mentioning explicitly that HP-UX and AIX (by name) are just broken.
> To me whether this is supposed to conform to some historic semantics
> does not seem very relevant when making code portable, and when that
> contradicts the specific system explicit documentation and behavior.
> And then "FUD" seems completely out of line here (even though I didn't
> write that man page update), and incorrect, because there _are_ such
> systems in existence…
Well, eater was denied progress out of fear of unportability due to
uncertainty in the documentation, so, intentional or not, well.

The correct way of spelling this is
"HP-UX and AIX are broken and need fd to be opened for writing"
and generalising this to a vague "some UNIX systems"
is just needlessly hostile to the user.

v3 in followup.

Best,

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

[PATCH v3] fsync.2: no writability requirements

[наб]

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

Since Issue 3 (original release), fsync() was required to operate on
all valid fds. Since Issue 7 2018, fdatasync() is as well (and required
writability only by editorial mistake):
  https://www.austingroupbugs.net/view.php?id=501

"Some UNIXes require the fd to be writable" is a
needlessly-adversarial-to-the-user ‒
  https://101010.pl/@eater@cijber.social/110824211348995583
‒ way of saying "HP-UX and AIX have always been broken": just say that.

Originally appeared in 4.2BSD (4.1c.2BSD) so touch that as well since
we're mentioning the original interface.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man2/fsync.2 | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/man2/fsync.2 b/man2/fsync.2
index 1043e6a1b..036af0a9e 100644
--- a/man2/fsync.2
+++ b/man2/fsync.2
@@ -155,16 +155,10 @@ .SH VERSIONS
 .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
 .\" -1: unavailable, 0: ask using sysconf().
 .\" glibc defines them to 1.
-.PP
-On some UNIX systems (but not Linux),
-.I fd
-must be a
-.I writable
-file descriptor.
 .SH STANDARDS
 POSIX.1-2008.
 .SH HISTORY
-POSIX.1-2001, 4.3BSD.
+POSIX.1-2001, 4.2BSD.
 .PP
 In Linux 2.2 and earlier,
 .BR fdatasync ()
@@ -181,6 +175,13 @@ .SH HISTORY
 or
 .BR sdparm (8)
 to guarantee safe operation.
+.PP
+Under AT&T UNIX System V Release 4
+.I fd
+needs to be opened for writing.
+This is by itself incompatible with the original BSD interface
+and forbidden by POSIX,
+but nevertheless survives in HP-UX and AIX.
 .SH SEE ALSO
 .BR sync (1),
 .BR bdflush (2),
-- 
2.39.2

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

Re: [PATCH v3] fsync.2: no writability requirements

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1941 bytes --]

Hi!

On 2023-08-04 17:03, наб wrote:
> Since Issue 3 (original release), fsync() was required to operate on
> all valid fds. Since Issue 7 2018, fdatasync() is as well (and required
> writability only by editorial mistake):
>   https://www.austingroupbugs.net/view.php?id=501
> 
> "Some UNIXes require the fd to be writable" is a
> needlessly-adversarial-to-the-user ‒
>   https://101010.pl/@eater@cijber.social/110824211348995583
> ‒ way of saying "HP-UX and AIX have always been broken": just say that.
> 
> Originally appeared in 4.2BSD (4.1c.2BSD) so touch that as well since
> we're mentioning the original interface.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Patch applied.  Thanks,

Alex

> ---
>  man2/fsync.2 | 15 ++++++++-------
>  1 file changed, 8 insertions(+), 7 deletions(-)
> 
> diff --git a/man2/fsync.2 b/man2/fsync.2
> index 1043e6a1b..036af0a9e 100644
> --- a/man2/fsync.2
> +++ b/man2/fsync.2
> @@ -155,16 +155,10 @@ .SH VERSIONS
>  .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
>  .\" -1: unavailable, 0: ask using sysconf().
>  .\" glibc defines them to 1.
> -.PP
> -On some UNIX systems (but not Linux),
> -.I fd
> -must be a
> -.I writable
> -file descriptor.
>  .SH STANDARDS
>  POSIX.1-2008.
>  .SH HISTORY
> -POSIX.1-2001, 4.3BSD.
> +POSIX.1-2001, 4.2BSD.
>  .PP
>  In Linux 2.2 and earlier,
>  .BR fdatasync ()
> @@ -181,6 +175,13 @@ .SH HISTORY
>  or
>  .BR sdparm (8)
>  to guarantee safe operation.
> +.PP
> +Under AT&T UNIX System V Release 4
> +.I fd
> +needs to be opened for writing.
> +This is by itself incompatible with the original BSD interface
> +and forbidden by POSIX,
> +but nevertheless survives in HP-UX and AIX.
>  .SH SEE ALSO
>  .BR sync (1),
>  .BR bdflush (2),

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[Sam James]

наб <nabijaczleweli@nabijaczleweli.xyz> writes:

> [[PGP Signed Part:Undecided]]
> POSIX has for a long time implied that directories are fsyncable,
> and since Issue 8 explicitly specifies directory syncing semantics:
>   https://www.austingroupbugs.net/view.php?id=672
>
> Simultaneously, directories being unopenable for writing is a
> Longest-Standing UNIX Semantic, present in the UNIX Programmer's Manual
> under directory (V), and has always been enshrined in the standards.
>
> Kill the FUD that says that some UNIXes require the fd to be writable:
> they /must not/ and this confuses users:
>   https://101010.pl/@eater@cijber.social/110824211348995583

Must not, or need not be?

>
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
>  man2/fsync.2 | 6 ------
>  1 file changed, 6 deletions(-)
>
> diff --git a/man2/fsync.2 b/man2/fsync.2
> index 1043e6a1b..9ced40b28 100644
> --- a/man2/fsync.2
> +++ b/man2/fsync.2
> @@ -155,12 +155,6 @@ .SH VERSIONS
>  .\" POSIX.1-2001: It shall be defined to -1 or 0 or 200112L.
>  .\" -1: unavailable, 0: ask using sysconf().
>  .\" glibc defines them to 1.
> -.PP
> -On some UNIX systems (but not Linux),
> -.I fd
> -must be a
> -.I writable
> -file descriptor.
>  .SH STANDARDS
>  POSIX.1-2008.
>  .SH HISTORY

Re: [PATCH] fsync.2: no writability requirements, must operate on directories

[наб]

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

On Thu, Aug 03, 2023 at 05:07:00PM +0100, Sam James wrote:
> наб <nabijaczleweli@nabijaczleweli.xyz> writes:
> > Kill the FUD that says that some UNIXes require the fd to be writable:
> > they /must not/ and this confuses users:
> >   https://101010.pl/@eater@cijber.social/110824211348995583
> Must not, or need not be?
Mustn't require writability, since they needn't be writable.
Admittedly, this is probably sub-optimal phrasing.

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