Wrong `follow_symlinks` default fallback implementation

[yhx-12243]

Bug report

Bug description:

By https://github.com/python/cpython/blob/96b392d/Modules/posixmodule.c#L4274, if follow_symlinks = True, Python will choose to call syscall link rather than linkat. However, the behavior of link will have AT_SYMLINK_FOLLOW unset, which leads an opposite behavior.

import os
os.link('link', 'another-file')

CPython versions tested on:

CPython main branch

Operating systems tested on:

Linux

### Tasks

Linked PRs

• gh-119885: follow_symlinks in os.link() #119886

[eryksun]

I investigated this problem about 4 years ago for issue gh-85527. It seems nothing was done to fix the implementation. It still defaults to follow_symlinks=True, and the behavior still depends on the platform's implementation of link() and whether src_dir_fd or dst_dir_fd is passed. For example, apparently link() actually follows symlinks on macOS, which POSIX allows. (I don't use macOS, so I'm just repeating what was stated on the previous issue.)

By 'fixing' the code like this for Linux, you're breaking it for macOS, which would have no way to not follow symlinks. Instead, the implementation should always use linkat() if it's available. Maybe the default in 3.14 should be follow_symlinks=None, and use false as the real default on all platforms except for macOS. That would preserve existing default behavior in practice (documentation aside), except for the previously inconsistent behavior when src_dir_fd or dst_dir_fd was passed.

I'd prefer for the symlink-following behavior to be documented as platform-dependent if follow_symlinks isn't supported. For Windows, there's a noteworthy inconsistency with POSIX. CreateHardLinkW() is implemented to not follow symlinks, but, unlike POSIX, creating a hardlink to a directory symlink is disallowed because the symlink itself is a directory.

[yhx-12243]

I think this issue is different to that one where that can be regarded as a API change request, this is a behavior correction without API change (keeps the default value True) and I've add the corresponding tests.

[eryksun]

The support for follow_symlinks was implemented incorrectly when it was added in 3.3 (2012), so this has been broken for 12 years. It should never depend on calling the platform link() when linkat() is available, since POSIX allows the symlink behavior to be defined by the implementation. If HAVE_LINKAT_RUNTIME is defined, then use linkat(). Otherwise follow_symlinks is not supported, so link() is used, and the fact that the symlink behavior is platform-dependent should be documented.

The behavior of os.link(src, dst) on Linux and BSD can certainly change in 3.14, but changing it for earlier versions seems dubious to me. The current overall behavior has been in place since follow_symlinks support was added in 3.3, and the default behavior of os.link(src, dst) has never changed since Python 1.x in the 1990s. It has always depended on the behavior of the platform link(), which doesn't follow symlinks on Linux and BSD and does follow symlinks on macOS (2001+).

In Python 3.11-3.13, I'd prefer to change the default to follow_symlinks=False, except if __APPLE__ is defined the default should be follow_symlinks=True. Then change the documentation to make the default follow_symlinks=False, but note the exception that it's True on macOS. In 3.14, I'd prefer to make it consistently follow_symlinks=False, which to me seems to be the more intuitive behavior for hardlinks, which is why it's the default behavior of POSIX linkat().

[yhx-12243]

However changing the default value follows_symlinks=False may leads a big compatibility break than what currently #119886 does, at least I think so.

[eryksun]

The actual behavior has always been follow_symlinks=False, except on macOS, or except if src_dir_fd or dst_dir_fd is passed as a real file descriptor.