doc: Document that fsync doesn't work on directories on AIX 7.3.

[Collin Funk]

Using the following test program:

    $ cat main.c 
    #include <fcntl.h>
    #include <unistd.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <errno.h>
    
    int
    main (void)
    {
      int fd = open (".", O_DIRECTORY);
      if (fd < 0)
        {
          fprintf (stderr, "open: %s\n", strerror (errno));
          exit (EXIT_FAILURE);
        }
      if (fsync (fd) < 0)
        {
          fprintf (stderr, "fsync: %s\n", strerror (errno));
          exit (EXIT_FAILURE);
        }
      exit (EXIT_SUCCESS);
    }

On GNU/Linux:

    $ ./a.out 
    $ echo $?
    0

On AIX 7.3:

    $ ./a.out
    fsync: Bad file number
    $ echo $?
    1

I found this behavior on an XZ Utils bug report [1].

This patch documents it.

Collin

[1] https://github.com/tukaani-project/xz/issues/188


>From 7075f2377516eef250d2409307219bb80de3d373 Mon Sep 17 00:00:00 2001
Message-ID: <7075f2377516eef250d2409307219bb80de3d373.1753220605.git.collin.fu...@gmail.com>
From: Collin Funk <collin.fu...@gmail.com>
Date: Tue, 22 Jul 2025 14:40:50 -0700
Subject: [PATCH] doc: Document that fsync doesn't work on directories on AIX
 7.3.

Reported by Lakshmi-Surekha <lakshmi.kovv...@ibm.com> in:
<https://github.com/tukaani-project/xz/issues/188>.

* doc/posix-functions/fsync.texi: Document the behavior.
---
 ChangeLog                      | 7 +++++++
 doc/posix-functions/fsync.texi | 5 +++++
 2 files changed, 12 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index ac20d475da..3cebc0d793 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2025-07-22  Collin Funk  <collin.fu...@gmail.com>
+
+	doc: Document that fsync doesn't work on directories on AIX 7.3.
+	Reported by Lakshmi-Surekha <lakshmi.kovv...@ibm.com> in:
+	<https://github.com/tukaani-project/xz/issues/188>.
+	* doc/posix-functions/fsync.texi: Document the behavior.
+
 2025-07-22  Paul Eggert  <egg...@cs.ucla.edu>
 
 	mkdir-p: ENOENT/ENOTDIR safety and consistency
diff --git a/doc/posix-functions/fsync.texi b/doc/posix-functions/fsync.texi
index d9149b4685..924546516b 100644
--- a/doc/posix-functions/fsync.texi
+++ b/doc/posix-functions/fsync.texi
@@ -20,4 +20,9 @@ @node fsync
 If the argument is a read-only file descriptor, this function fails
 with @code{EBADF} on some platforms:
 AIX 7.2, Cygwin 2.9.
+
+@item
+If the argument is a directory file descriptor, this function fails with
+@code{EBADF} on some platforms:
+AIX 7.3.
 @end itemize
-- 
2.50.1