gh-107959: clarify Unix-availability of `os.lchmod()` (GH-107960)

POSIX specifies that implementations are not required to support changing the
file mode of symbolic links, but may do so.
Consequently, `lchmod()` is not part of POSIX (but mentioned for implementations
which do support the above).

The current wording of the availability of `os.lchmod()` is rather vague and
improved to clearly tell which POSIX/Unix/BSD-like support the function in
general (those that support changing the file mode of symbolic links).
Further, some examples of major implementations are added.

Data for the BSDs taken from their online manpages.

Signed-off-by: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index e5ac9afc3c6fd919e6763e2bbe13ac00cb7020f5..9d2a3d65069253a57bb4876b42a471dd98c595ad 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -2160,9 +2160,12 @@ features:
    for possible values of *mode*.  As of Python 3.3, this is equivalent to
    ``os.chmod(path, mode, follow_symlinks=False)``.
 
+   ``lchmod()`` is not part of POSIX, but Unix implementations may have it if
+   changing the mode of symbolic links is supported.
+
    .. audit-event:: os.chmod path,mode,dir_fd os.lchmod
 
-   .. availability:: Unix.
+   .. availability:: Unix, not Linux, FreeBSD >= 1.3, NetBSD >= 1.3, not OpenBSD
 
    .. versionchanged:: 3.6
       Accepts a :term:`path-like object`.