gh-136413: Add os.linkat() function

Author: vstinner

Doc/library/os.rst

@@ -2046,6 +2046,39 @@ features:
   If it's unavailable, using it will raise a :exc:`NotImplementedError`.
 
 
+.. data:: AT_FDCWD
+
+   .. availability:: Linux.
+
+.. data:: AT_EMPTY_PATH
+
+   If *src_path* is an empty string, create a link to the file referenced by
+   *src_dir_fd* (which may have been obtained using the open(2) :data:`O_PATH`
+   flag).  In this case, *src_dir_fd* can refer to any type of file except a
+   directory.  This will generally not work if the file has a link count of
+   zero (files created with :data:`O_TMPFILE` and without :data:`O_EXCL` are an
+   exception).
+
+   The caller must have the ``CAP_DAC_READ_SEARCH`` capability in order to use
+   this flag.
+
+   .. availability:: Linux >= 2.6.39.
+
+.. data:: AT_SYMLINK_FOLLOW
+
+   By default, :func:`linkat`, does not dereference *src_path* if it is a
+   symbolic link (like :func:`link`). The flag :data:`!AT_SYMLINK_FOLLOW` can
+   be specified in flags to cause *src_path* to be dereferenced if it is a
+   symbolic link.
+
+   If procfs is mounted, this can be used as an alternative to
+   :data:`AT_EMPTY_PATH`, like this::
+
+       os.linkat(os.AT_FDCWD, "/proc/self/fd/<fd>",
+                 dst_dir_fd, dst_name, os.AT_SYMLINK_FOLLOW)
+
+   .. availability:: Linux >= 2.6.18.
+
 
 .. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)
 
@@ -2354,6 +2387,36 @@ features:
       Accepts a :term:`path-like object` for *src* and *dst*.
 
 
+.. function:: linkat(src_dir_fd, src_path, dst_dir_fd, dst_path, flags, /)
+
+   The :func:`!linkat` function operates in exactly the same way as
+   :func:`link`, except for the differences described here.
+
+   If the pathname given in *src_path* is relative, then it is interpreted
+   relative to the directory referred to by the file descriptor *src_dir_fd*
+   (rather than relative to the current working directory of the calling
+   process, as is done by link() for a relative pathname).
+
+   If *src_path* is relative and *src_dir_fd* is the special value
+   :data:`AT_FDCWD`, then *src_path* is interpreted relative to the current
+   working directory of the calling process (like :func:`link`).
+
+   If *src_path* is absolute, then *src_dir_fd* is ignored.
+
+   The interpretation of *dst_path* is as for *src_path*, except that a
+   relative pathname is interpreted relative to the directory referred to
+   by the file descriptor *dst_dir_fd*.
+
+   The following values can be bitwise ORed in flags:
+
+   * :data:`AT_EMPTY_PATH`
+   * :data:`AT_SYMLINK_FOLLOW`
+
+   .. audit-event:: os.linkat src_dir_fd,src_path,dst_dir_fd,dst_path,flags os.linkat
+
+   .. availability:: Unix.
+
+
 .. function:: listdir(path='.')
 
    Return a list containing the names of the entries in the directory given by

Doc/whatsnew/3.15.rst

@@ -119,6 +119,14 @@ math
   (Contributed by Bénédikt Tran in :gh:`135853`.)
 
 
+os
+--
+
+* Added :func:`os.linkat` to create a hard link with flags.
+  Added also constants :data:`os.AT_EMPTY_PATH`, :data:`os.AT_FDCWD` and
+  :data:`os.AT_SYMLINK_FOLLOW`.
+  (Contributed by Victor Stinner in :gh:`136413`.)
+
 os.path
 -------
 

Include/internal/pycore_global_objects_fini_generated.h

@@ -410,6 +410,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(dont_inherit)
         STRUCT_FOR_ID(dst)
         STRUCT_FOR_ID(dst_dir_fd)
+        STRUCT_FOR_ID(dst_path)
         STRUCT_FOR_ID(eager_start)
         STRUCT_FOR_ID(effective_ids)
         STRUCT_FOR_ID(element_factory)
@@ -729,6 +730,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(spam)
         STRUCT_FOR_ID(src)
         STRUCT_FOR_ID(src_dir_fd)
+        STRUCT_FOR_ID(src_path)
         STRUCT_FOR_ID(stacklevel)
         STRUCT_FOR_ID(start)
         STRUCT_FOR_ID(statement)

Include/internal/pycore_global_strings.h

@@ -2655,6 +2655,58 @@ def test_unicode_name(self):
         self.file2 = self.file1 + "2"
         self._test_link(self.file1, self.file2)
 
+
+@unittest.skipUnless(hasattr(os, 'linkat'), 'requires os.linkat')
+class LinkAtTests(unittest.TestCase):
+    def test_no_flags(self):
+        # create hard link with no flags
+        src = "linkat_src"
+        self.addCleanup(os_helper.unlink, src)
+        with open(src, "w", encoding='utf8') as fp:
+            fp.write("hello")
+
+        dst = "linkat_dst"
+        self.addCleanup(os_helper.unlink, dst)
+        os.linkat(os.AT_FDCWD, src, os.AT_FDCWD, dst)  # flags=0
+
+        with open(dst, encoding='utf8') as fp:
+            self.assertEqual(fp.read(), 'hello')
+
+        # destination already exists
+        src2 = "linkat_src2"
+        self.addCleanup(os_helper.unlink, src2)
+        with open(src2, "w", encoding='utf8') as fp:
+            fp.write("PYTHON")
+
+        with self.assertRaises(FileExistsError):
+            os.linkat(os.AT_FDCWD, src2, os.AT_FDCWD, dst)  # flags=0
+
+    def check_flag(self, flag):
+        filename = os_helper.TESTFN
+        self.addCleanup(os_helper.unlink, filename)
+
+        fd = os.open(os.path.curdir, os.O_WRONLY | os.O_TMPFILE, 0o600)
+        os.write(fd, b"hello")
+        if flag == os.AT_EMPTY_PATH:
+            os.linkat(fd, b"",
+                      os.AT_FDCWD, filename,
+                      os.AT_EMPTY_PATH)
+        else:
+            os.linkat(fd, f"/proc/self/fd/{fd}",
+                      os.AT_FDCWD, filename,
+                      os.AT_SYMLINK_FOLLOW)
+        os.close(fd)
+
+        with open(filename, encoding='utf8') as fp:
+            self.assertEqual(fp.read(), 'hello')
+
+    def test_empty_path(self):
+        self.check_flag(os.AT_EMPTY_PATH)
+
+    def test_symlink_follow(self):
+        self.check_flag(os.AT_SYMLINK_FOLLOW)
+
+
 @unittest.skipIf(sys.platform == "win32", "Posix specific tests")
 class PosixUidGidTests(unittest.TestCase):
     # uid_t and gid_t are 32-bit unsigned integers on Linux

Include/internal/pycore_runtime_init_generated.h

@@ -0,0 +1,4 @@
+Added :func:`os.linkat` to create a hard link with flags. Patch by Victor
+Added also constants :data:`os.AT_EMPTY_PATH`, :data:`os.AT_FDCWD` and
+:data:`os.AT_SYMLINK_FOLLOW`.
+Stinner.