Merge remote-tracking branch 'upstream/main' into fwdref-format

Author: JelleZijlstra

Doc/library/fcntl.rst

@@ -82,65 +82,82 @@ descriptor.
 The module defines the following functions:
 
 
-.. function:: fcntl(fd, cmd, arg=0)
+.. function:: fcntl(fd, cmd, arg=0, /)
 
    Perform the operation *cmd* on file descriptor *fd* (file objects providing
    a :meth:`~io.IOBase.fileno` method are accepted as well).  The values used
    for *cmd* are operating system dependent, and are available as constants
    in the :mod:`fcntl` module, using the same names as used in the relevant C
-   header files. The argument *arg* can either be an integer value, or a
-   :class:`bytes` object. With an integer value, the return value of this
-   function is the integer return value of the C :c:func:`fcntl` call.  When
-   the argument is bytes it represents a binary structure, e.g. created by
-   :func:`struct.pack`. The binary data is copied to a buffer whose address is
+   header files. The argument *arg* can either be an integer value, a
+   :class:`bytes` object, or a string.
+   The type and size of *arg* must match the type and size of
+   the argument of the operation as specified in the relevant C documentation.
+
+   When *arg* is an integer, the function returns the integer
+   return value of the C :c:func:`fcntl` call.
+
+   When the argument is bytes, it represents a binary structure,
+   for example, created by :func:`struct.pack`.
+   A string value is encoded to binary using the UTF-8 encoding.
+   The binary data is copied to a buffer whose address is
    passed to the C :c:func:`fcntl` call.  The return value after a successful
    call is the contents of the buffer, converted to a :class:`bytes` object.
    The length of the returned object will be the same as the length of the
-   *arg* argument. This is limited to 1024 bytes. If the information returned
-   in the buffer by the operating system is larger than 1024 bytes, this is
-   most likely to result in a segmentation violation or a more subtle data
-   corruption.
+   *arg* argument. This is limited to 1024 bytes.
 
    If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
 
+   .. note::
+      If the type or the size of *arg* does not match the type or size
+      of the argument of the operation (for example, if an integer is
+      passed when a pointer is expected, or the information returned in
+      the buffer by the operating system is larger than 1024 bytes),
+      this is most likely to result in a segmentation violation or
+      a more subtle data corruption.
+
    .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
 
 
-.. function:: ioctl(fd, request, arg=0, mutate_flag=True)
+.. function:: ioctl(fd, request, arg=0, mutate_flag=True, /)
 
    This function is identical to the :func:`~fcntl.fcntl` function, except
    that the argument handling is even more complicated.
 
-   The *request* parameter is limited to values that can fit in 32-bits.
+   The *request* parameter is limited to values that can fit in 32-bits
+   or 64-bits, depending on the platform.
    Additional constants of interest for use as the *request* argument can be
    found in the :mod:`termios` module, under the same names as used in
    the relevant C header files.
 
-   The parameter *arg* can be one of an integer, an object supporting the
-   read-only buffer interface (like :class:`bytes`) or an object supporting
-   the read-write buffer interface (like :class:`bytearray`).
+   The parameter *arg* can be an integer, a :term:`bytes-like object`,
+   or a string.
+   The type and size of *arg* must match the type and size of
+   the argument of the operation as specified in the relevant C documentation.
 
-   In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
+   If *arg* does not support the read-write buffer interface or
+   the *mutate_flag* is false, behavior is as for the :func:`~fcntl.fcntl`
    function.
 
-   If a mutable buffer is passed, then the behaviour is determined by the value of
-   the *mutate_flag* parameter.
-
-   If it is false, the buffer's mutability is ignored and behaviour is as for a
-   read-only buffer, except that the 1024 byte limit mentioned above is avoided --
-   so long as the buffer you pass is at least as long as what the operating system
-   wants to put there, things should work.
-
-   If *mutate_flag* is true (the default), then the buffer is (in effect) passed
-   to the underlying :func:`ioctl` system call, the latter's return code is
+   If *arg* supports the read-write buffer interface (like :class:`bytearray`)
+   and *mutate_flag* is true (the default), then the buffer is (in effect) passed
+   to the underlying :c:func:`!ioctl` system call, the latter's return code is
    passed back to the calling Python, and the buffer's new contents reflect the
-   action of the :func:`ioctl`.  This is a slight simplification, because if the
+   action of the :c:func:`ioctl`.  This is a slight simplification, because if the
    supplied buffer is less than 1024 bytes long it is first copied into a static
    buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back
    into the supplied buffer.
 
    If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised.
 
+   .. note::
+      If the type or size of *arg* does not match the type or size
+      of the operation's argument (for example, if an integer is
+      passed when a pointer is expected, or the information returned in
+      the buffer by the operating system is larger than 1024 bytes,
+      or the size of the mutable bytes-like object is too small),
+      this is most likely to result in a segmentation violation or
+      a more subtle data corruption.
+
    An example::
 
       >>> import array, fcntl, struct, termios, os
@@ -157,7 +174,7 @@ The module defines the following functions:
    .. audit-event:: fcntl.ioctl fd,request,arg fcntl.ioctl
 
 
-.. function:: flock(fd, operation)
+.. function:: flock(fd, operation, /)
 
    Perform the lock operation *operation* on file descriptor *fd* (file objects providing
    a :meth:`~io.IOBase.fileno` method are accepted as well). See the Unix manual
@@ -169,7 +186,7 @@ The module defines the following functions:
    .. audit-event:: fcntl.flock fd,operation fcntl.flock
 
 
-.. function:: lockf(fd, cmd, len=0, start=0, whence=0)
+.. function:: lockf(fd, cmd, len=0, start=0, whence=0, /)
 
    This is essentially a wrapper around the :func:`~fcntl.fcntl` locking calls.
    *fd* is the file descriptor (file objects providing a :meth:`~io.IOBase.fileno`

Doc/library/multiprocessing.rst

@@ -670,6 +670,25 @@ The :mod:`multiprocessing` package mostly replicates the API of the
 
       .. versionadded:: 3.3
 
+   .. method:: interrupt()
+
+      Terminate the process. Works on POSIX using the :py:const:`~signal.SIGINT` signal.
+      Behavior on Windows is undefined.
+
+      By default, this terminates the child process by raising :exc:`KeyboardInterrupt`.
+      This behavior can be altered by setting the respective signal handler in the child
+      process :func:`signal.signal` for :py:const:`~signal.SIGINT`.
+
+      Note: if the child process catches and discards :exc:`KeyboardInterrupt`, the
+      process will not be terminated.
+
+      Note: the default behavior will also set :attr:`exitcode` to ``1`` as if an
+      uncaught exception was raised in the child process. To have a different
+      :attr:`exitcode` you may simply catch :exc:`KeyboardInterrupt` and call
+      ``exit(your_code)``.
+
+      .. versionadded:: next
+
    .. method:: terminate()
 
       Terminate the process.  On POSIX this is done using the :py:const:`~signal.SIGTERM` signal;

Doc/whatsnew/3.14.rst

@@ -972,6 +972,10 @@ multiprocessing
   The :func:`set` in :func:`multiprocessing.Manager` method is now available.
   (Contributed by Mingyu Park in :gh:`129949`.)
 
+* Add :func:`multiprocessing.Process.interrupt` which terminates the child
+  process by sending :py:const:`~signal.SIGINT`. This enables "finally" clauses
+  and printing stack trace for the terminated process.
+  (Contributed by Artem Pulkin in :gh:`131913`.)
 
 operator
 --------

Lib/multiprocessing/popen_fork.py

@@ -54,6 +54,9 @@ def _send_signal(self, sig):
                 if self.wait(timeout=0.1) is None:
                     raise
 
+    def interrupt(self):
+        self._send_signal(signal.SIGINT)
+
     def terminate(self):
         self._send_signal(signal.SIGTERM)
 

Lib/multiprocessing/process.py

@@ -125,6 +125,13 @@ def start(self):
         del self._target, self._args, self._kwargs
         _children.add(self)
 
+    def interrupt(self):
+        '''
+        Terminate process; sends SIGINT signal
+        '''
+        self._check_closed()
+        self._popen.interrupt()
+
     def terminate(self):
         '''
         Terminate process; sends SIGTERM signal or uses TerminateProcess()

Lib/test/_test_multiprocessing.py

@@ -512,15 +512,20 @@ def _test_process_mainthread_native_id(cls, q):
     def _sleep_some(cls):
         time.sleep(100)
 
+    @classmethod
+    def _sleep_no_int_handler(cls):
+        signal.signal(signal.SIGINT, signal.SIG_DFL)
+        cls._sleep_some()
+
     @classmethod
     def _test_sleep(cls, delay):
         time.sleep(delay)
 
-    def _kill_process(self, meth):
+    def _kill_process(self, meth, target=None):
         if self.TYPE == 'threads':
             self.skipTest('test not appropriate for {}'.format(self.TYPE))
 
-        p = self.Process(target=self._sleep_some)
+        p = self.Process(target=target or self._sleep_some)
         p.daemon = True
         p.start()
 
@@ -567,6 +572,19 @@ def handler(*args):
 
         return p.exitcode
 
+    @unittest.skipIf(os.name == 'nt', "POSIX only")
+    def test_interrupt(self):
+        exitcode = self._kill_process(multiprocessing.Process.interrupt)
+        self.assertEqual(exitcode, 1)
+        # exit code 1 is hard-coded for uncaught exceptions
+        # (KeyboardInterrupt in this case)
+        # in multiprocessing.BaseProcess._bootstrap
+
+    @unittest.skipIf(os.name == 'nt', "POSIX only")
+    def test_interrupt_no_handler(self):
+        exitcode = self._kill_process(multiprocessing.Process.interrupt, target=self._sleep_no_int_handler)
+        self.assertEqual(exitcode, -signal.SIGINT)
+
     def test_terminate(self):
         exitcode = self._kill_process(multiprocessing.Process.terminate)
         self.assertEqual(exitcode, -signal.SIGTERM)

Lib/test/support/os_helper.py

@@ -657,7 +657,7 @@ def fd_count():
     """
     if sys.platform.startswith(('linux', 'android', 'freebsd', 'emscripten')):
         fd_path = "/proc/self/fd"
-    elif sys.platform == "darwin":
+    elif support.is_apple:
         fd_path = "/dev/fd"
     else:
         fd_path = None

Lib/test/test_socket.py

@@ -2647,14 +2647,13 @@ def testBluetoothConstants(self):
             socket.BT_POWER
             socket.BT_CHANNEL_POLICY
             socket.BT_CHANNEL_POLICY_BREDR_ONLY
-            socket.BT_PHY
-            socket.BT_PHY_BR_1M_1SLOT
-            socket.BT_MODE
-            socket.BT_MODE_BASIC
-            socket.BT_VOICE
-            socket.BT_VOICE_TRANSPARENT
-            socket.BT_VOICE_CVSD_16BIT
-            socket.BT_CODEC
+            if hasattr(socket, 'BT_PHY'):
+                socket.BT_PHY_BR_1M_1SLOT
+            if hasattr(socket, 'BT_MODE'):
+                socket.BT_MODE_BASIC
+            if hasattr(socket, 'BT_VOICE'):
+                socket.BT_VOICE_TRANSPARENT
+                socket.BT_VOICE_CVSD_16BIT
             socket.L2CAP_LM
             socket.L2CAP_LM_MASTER
             socket.L2CAP_LM_AUTH

Misc/NEWS.d/next/Build/2025-04-20-20-07-44.gh-issue-132758.N2a3wp.rst

@@ -0,0 +1 @@
+Fix building with tail call interpreter and pystats.

Misc/NEWS.d/next/Library/2025-04-12-19-42-51.gh-issue-131913.twOx7K.rst

@@ -0,0 +1 @@
+Add a shortcut function :func:`multiprocessing.Process.interrupt` alongside the existing :func:`multiprocessing.Process.terminate` and :func:`multiprocessing.Process.kill` for an improved control over child process termination.