bpo-39184: Add audit events to functions in `fcntl`, `msvcrt`, `os`, `resource`, `shutil`, `signal`, `syslog` (GH-18407)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index b06a318..af02a37 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -445,6 +445,8 @@
On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may
cause memory leaks. Refer to the system documentation for :c:func:`putenv`.
+ .. audit-event:: os.putenv key,value os.putenv
+
.. versionchanged:: 3.9
The function is now always available.
@@ -640,6 +642,8 @@
don't update ``os.environ``, so it is actually preferable to delete items of
``os.environ``.
+ .. audit-event:: os.unsetenv key os.unsetenv
+
.. versionchanged:: 3.9
The function is now always available and is also available on Windows.
@@ -766,6 +770,8 @@
docs for :func:`chmod` for possible values of *mode*. As of Python 3.3, this
is equivalent to ``os.chmod(fd, mode)``.
+ .. audit-event:: os.chmod path,mode,dir_fd os.fchmod
+
.. availability:: Unix.
@@ -776,6 +782,8 @@
:func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid,
gid)``.
+ .. audit-event:: os.chown path,uid,gid,dir_fd os.fchown
+
.. availability:: Unix.
@@ -883,6 +891,8 @@
:data:`F_ULOCK` or :data:`F_TEST`.
*len* specifies the section of the file to lock.
+ .. audit-event:: os.lockf fd,cmd,len os.lockf
+
.. availability:: Unix.
.. versionadded:: 3.3
@@ -1603,6 +1613,8 @@
This function can raise :exc:`OSError` and subclasses such as
:exc:`FileNotFoundError`, :exc:`PermissionError`, and :exc:`NotADirectoryError`.
+ .. audit-event:: os.chdir path os.chdir
+
.. versionadded:: 3.3
Added support for specifying *path* as a file descriptor
on some platforms.
@@ -1631,6 +1643,8 @@
This function can support :ref:`not following symlinks <follow_symlinks>`.
+ .. audit-event:: os.chflags path,flags os.chflags
+
.. availability:: Unix.
.. versionadded:: 3.3
@@ -1676,6 +1690,8 @@
read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD``
constants or a corresponding integer value). All other bits are ignored.
+ .. audit-event:: os.chmod path,mode,dir_fd os.chmod
+
.. versionadded:: 3.3
Added support for specifying *path* as an open file descriptor,
and the *dir_fd* and *follow_symlinks* arguments.
@@ -1696,6 +1712,8 @@
See :func:`shutil.chown` for a higher-level function that accepts names in
addition to numeric ids.
+ .. audit-event:: os.chown path,uid,gid,dir_fd os.chown
+
.. availability:: Unix.
.. versionadded:: 3.3
@@ -1722,6 +1740,8 @@
descriptor *fd*. The descriptor must refer to an opened directory, not an
open file. As of Python 3.3, this is equivalent to ``os.chdir(fd)``.
+ .. audit-event:: os.chdir path os.fchdir
+
.. availability:: Unix.
@@ -1746,6 +1766,8 @@
not follow symbolic links. As of Python 3.3, this is equivalent to
``os.chflags(path, flags, follow_symlinks=False)``.
+ .. audit-event:: os.chflags path,flags os.lchflags
+
.. availability:: Unix.
.. versionchanged:: 3.6
@@ -1759,6 +1781,8 @@
for possible values of *mode*. As of Python 3.3, this is equivalent to
``os.chmod(path, mode, follow_symlinks=False)``.
+ .. audit-event:: os.chmod path,mode,dir_fd os.lchmod
+
.. availability:: Unix.
.. versionchanged:: 3.6
@@ -1770,6 +1794,8 @@
function will not follow symbolic links. As of Python 3.3, this is equivalent
to ``os.chown(path, uid, gid, follow_symlinks=False)``.
+ .. audit-event:: os.chown path,uid,gid,dir_fd os.lchown
+
.. availability:: Unix.
.. versionchanged:: 3.6
@@ -1784,6 +1810,8 @@
supply :ref:`paths relative to directory descriptors <dir_fd>`, and :ref:`not
following symlinks <follow_symlinks>`.
+ .. audit-event:: os.link src,dst,src_dir_fd,dst_dir_fd os.link
+
.. availability:: Unix, Windows.
.. versionchanged:: 3.2
@@ -1886,6 +1914,8 @@
It is also possible to create temporary directories; see the
:mod:`tempfile` module's :func:`tempfile.mkdtemp` function.
+ .. audit-event:: os.mkdir path,mode,dir_fd os.mkdir
+
.. versionadded:: 3.3
The *dir_fd* argument.
@@ -1918,6 +1948,8 @@
This function handles UNC paths correctly.
+ .. audit-event:: os.mkdir path,mode,dir_fd os.makedirs
+
.. versionadded:: 3.2
The *exist_ok* parameter.
@@ -2083,6 +2115,8 @@
This function is semantically identical to :func:`unlink`.
+ .. audit-event:: os.remove path,dir_fd os.remove
+
.. versionadded:: 3.3
The *dir_fd* argument.
@@ -2103,6 +2137,8 @@
they are empty. Raises :exc:`OSError` if the leaf directory could not be
successfully removed.
+ .. audit-event:: os.remove path,dir_fd os.removedirs
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -2128,6 +2164,8 @@
If you want cross-platform overwriting of the destination, use :func:`replace`.
+ .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.rename
+
.. versionadded:: 3.3
The *src_dir_fd* and *dst_dir_fd* arguments.
@@ -2147,6 +2185,8 @@
This function can fail with the new directory structure made if you lack
permissions needed to remove the leaf directory or file.
+ .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.renames
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *old* and *new*.
@@ -2162,6 +2202,8 @@
This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to
supply :ref:`paths relative to directory descriptors <dir_fd>`.
+ .. audit-event:: os.rename src,dst,src_dir_fd,dst_dir_fd os.replace
+
.. versionadded:: 3.3
.. versionchanged:: 3.6
@@ -2178,6 +2220,8 @@
This function can support :ref:`paths relative to directory descriptors
<dir_fd>`.
+ .. audit-event:: os.rmdir path,dir_fd os.rmdir
+
.. versionadded:: 3.3
The *dir_fd* parameter.
@@ -2821,6 +2865,8 @@
:exc:`OSError` is raised when the function is called by an unprivileged
user.
+ .. audit-event:: os.symlink src,dst,dir_fd os.symlink
+
.. availability:: Unix, Windows.
.. versionchanged:: 3.2
@@ -2873,6 +2919,8 @@
traditional Unix name. Please see the documentation for
:func:`remove` for further information.
+ .. audit-event:: os.remove path,dir_fd os.unlink
+
.. versionadded:: 3.3
The *dir_fd* parameter.
@@ -2910,6 +2958,8 @@
:ref:`paths relative to directory descriptors <dir_fd>` and :ref:`not
following symlinks <follow_symlinks>`.
+ .. audit-event:: os.utime path,times,ns,dir_fd os.utime
+
.. versionadded:: 3.3
Added support for specifying *path* as an open file descriptor,
and the *dir_fd*, *follow_symlinks*, and *ns* parameters.
@@ -3135,6 +3185,8 @@
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
+ .. audit-event:: os.getxattr path,attribute os.getxattr
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@@ -3149,6 +3201,8 @@
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
+ .. audit-event:: os.listxattr path os.listxattr
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
@@ -3163,6 +3217,8 @@
This function can support :ref:`specifying a file descriptor <path_fd>` and
:ref:`not following symlinks <follow_symlinks>`.
+ .. audit-event:: os.removexattr path,attribute os.removexattr
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@@ -3186,6 +3242,8 @@
A bug in Linux kernel versions less than 2.6.39 caused the flags argument
to be ignored on some filesystems.
+ .. audit-event:: os.setxattr path,attribute,value,flags os.setxattr
+
.. versionchanged:: 3.6
Accepts a :term:`path-like object` for *path* and *attribute*.
@@ -3248,6 +3306,8 @@
<https://msdn.microsoft.com/44228cf2-6306-466c-8f16-f513cd3ba8b5>`_
for more information about how DLLs are loaded.
+ .. audit-event:: os.add_dll_directory path os.add_dll_directory
+
.. availability:: Windows.
.. versionadded:: 3.8
@@ -3480,6 +3540,8 @@
Note that some platforms including FreeBSD <= 6.3 and Cygwin have
known issues when using ``fork()`` from a thread.
+ .. audit-event:: os.fork "" os.fork
+
.. versionchanged:: 3.8
Calling ``fork()`` in a subinterpreter is no longer supported
(:exc:`RuntimeError` is raised).
@@ -3499,6 +3561,8 @@
master end of the pseudo-terminal. For a more portable approach, use the
:mod:`pty` module. If an error occurs :exc:`OSError` is raised.
+ .. audit-event:: os.forkpty "" os.forkpty
+
.. versionchanged:: 3.8
Calling ``forkpty()`` in a subinterpreter is no longer supported
(:exc:`RuntimeError` is raised).
@@ -3525,6 +3589,8 @@
See also :func:`signal.pthread_kill`.
+ .. audit-event:: os.kill pid,sig os.kill
+
.. versionadded:: 3.2
Windows support.
@@ -3537,6 +3603,8 @@
Send the signal *sig* to the process group *pgid*.
+ .. audit-event:: os.killpg pgid,sig os.killpg
+
.. availability:: Unix.