Skip to content

[3.11] Docs: Remove links to external C functions and macros in os.rst (GH-108138) #108144

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 19, 2023
Merged

[3.11] Docs: Remove links to external C functions and macros in os.rst (GH-108138) #108144

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 27 additions & 25 deletions Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,7 @@ process and user.

On some platforms, including FreeBSD and macOS, setting ``environ`` may
cause memory leaks. Refer to the system documentation for
:c:func:`putenv`.
:c:func:`!putenv`.

You can delete items in this mapping to unset environment variables.
:func:`unsetenv` will be called automatically when an item is deleted from
Expand Down Expand Up @@ -553,7 +553,7 @@ process and user.
.. note::

On some platforms, including FreeBSD and macOS, setting ``environ`` may
cause memory leaks. Refer to the system documentation for :c:func:`putenv`.
cause memory leaks. Refer to the system documentation for :c:func:`!putenv`.

.. audit-event:: os.putenv key,value os.putenv

Expand Down Expand Up @@ -597,15 +597,15 @@ process and user.

.. function:: setpgrp()

Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on
Call the system call :c:func:`!setpgrp` or ``setpgrp(0, 0)`` depending on
which version is implemented (if any). See the Unix manual for the semantics.

.. availability:: Unix, not Emscripten, not WASI.


.. function:: setpgid(pid, pgrp, /)

Call the system call :c:func:`setpgid` to set the process group id of the
Call the system call :c:func:`!setpgid` to set the process group id of the
process with id *pid* to the process group with id *pgrp*. See the Unix manual
for the semantics.

Expand Down Expand Up @@ -971,7 +971,7 @@ as internal buffering of data.
.. function:: fsync(fd)

Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function.
native :c:func:`!fsync` function; on Windows, the MS :c:func:`!_commit` function.

If you're starting with a buffered Python :term:`file object` *f*, first do
``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
Expand Down Expand Up @@ -2127,7 +2127,7 @@ features:

.. function:: lstat(path, *, dir_fd=None)

Perform the equivalent of an :c:func:`lstat` system call on the given path.
Perform the equivalent of an :c:func:`!lstat` system call on the given path.
Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
:class:`stat_result` object.

Expand Down Expand Up @@ -2936,14 +2936,16 @@ features:

Windows file attributes: ``dwFileAttributes`` member of the
``BY_HANDLE_FILE_INFORMATION`` structure returned by
:c:func:`GetFileInformationByHandle`. See the ``FILE_ATTRIBUTE_*``
:c:func:`!GetFileInformationByHandle`.
See the :const:`!FILE_ATTRIBUTE_* <stat.FILE_ATTRIBUTE_ARCHIVE>`
constants in the :mod:`stat` module.

.. attribute:: st_reparse_tag

When :attr:`st_file_attributes` has the ``FILE_ATTRIBUTE_REPARSE_POINT``
When :attr:`st_file_attributes` has the :const:`~stat.FILE_ATTRIBUTE_REPARSE_POINT`
set, this field contains the tag identifying the type of reparse point.
See the ``IO_REPARSE_TAG_*`` constants in the :mod:`stat` module.
See the :const:`IO_REPARSE_TAG_* <stat.IO_REPARSE_TAG_SYMLINK>`
constants in the :mod:`stat` module.

The standard module :mod:`stat` defines functions and constants that are
useful for extracting information from a :c:struct:`stat` structure. (On
Expand Down Expand Up @@ -2982,7 +2984,7 @@ features:

.. function:: statvfs(path)

Perform a :c:func:`statvfs` system call on the given path. The return value is
Perform a :c:func:`!statvfs` system call on the given path. The return value is
an object whose attributes describe the filesystem on the given path, and
correspond to the members of the :c:struct:`statvfs` structure, namely:
:attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
Expand Down Expand Up @@ -4063,7 +4065,7 @@ written in Python, such as a mail server's external command delivery program.
setpgroup=None, resetids=False, setsid=False, setsigmask=(), \
setsigdef=(), scheduler=None)

Wraps the :c:func:`posix_spawn` C library API for use from Python.
Wraps the :c:func:`!posix_spawn` C library API for use from Python.

Most users should use :func:`subprocess.run` instead of :func:`posix_spawn`.

Expand Down Expand Up @@ -4099,44 +4101,44 @@ written in Python, such as a mail server's external command delivery program.
Performs ``os.dup2(fd, new_fd)``.

These tuples correspond to the C library
:c:func:`posix_spawn_file_actions_addopen`,
:c:func:`posix_spawn_file_actions_addclose`, and
:c:func:`posix_spawn_file_actions_adddup2` API calls used to prepare
for the :c:func:`posix_spawn` call itself.
:c:func:`!posix_spawn_file_actions_addopen`,
:c:func:`!posix_spawn_file_actions_addclose`, and
:c:func:`!posix_spawn_file_actions_adddup2` API calls used to prepare
for the :c:func:`!posix_spawn` call itself.

The *setpgroup* argument will set the process group of the child to the value
specified. If the value specified is 0, the child's process group ID will be
made the same as its process ID. If the value of *setpgroup* is not set, the
child will inherit the parent's process group ID. This argument corresponds
to the C library :c:macro:`POSIX_SPAWN_SETPGROUP` flag.
to the C library :c:macro:`!POSIX_SPAWN_SETPGROUP` flag.

If the *resetids* argument is ``True`` it will reset the effective UID and
GID of the child to the real UID and GID of the parent process. If the
argument is ``False``, then the child retains the effective UID and GID of
the parent. In either case, if the set-user-ID and set-group-ID permission
bits are enabled on the executable file, their effect will override the
setting of the effective UID and GID. This argument corresponds to the C
library :c:macro:`POSIX_SPAWN_RESETIDS` flag.
library :c:macro:`!POSIX_SPAWN_RESETIDS` flag.

If the *setsid* argument is ``True``, it will create a new session ID
for ``posix_spawn``. *setsid* requires :c:macro:`POSIX_SPAWN_SETSID`
or :c:macro:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError`
for ``posix_spawn``. *setsid* requires :c:macro:`!POSIX_SPAWN_SETSID`
or :c:macro:`!POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError`
is raised.

The *setsigmask* argument will set the signal mask to the signal set
specified. If the parameter is not used, then the child inherits the
parent's signal mask. This argument corresponds to the C library
:c:macro:`POSIX_SPAWN_SETSIGMASK` flag.
:c:macro:`!POSIX_SPAWN_SETSIGMASK` flag.

The *sigdef* argument will reset the disposition of all signals in the set
specified. This argument corresponds to the C library
:c:macro:`POSIX_SPAWN_SETSIGDEF` flag.
:c:macro:`!POSIX_SPAWN_SETSIGDEF` flag.

The *scheduler* argument must be a tuple containing the (optional) scheduler
policy and an instance of :class:`sched_param` with the scheduler parameters.
A value of ``None`` in the place of the scheduler policy indicates that is
not being provided. This argument is a combination of the C library
:c:macro:`POSIX_SPAWN_SETSCHEDPARAM` and :c:macro:`POSIX_SPAWN_SETSCHEDULER`
:c:macro:`!POSIX_SPAWN_SETSCHEDPARAM` and :c:macro:`!POSIX_SPAWN_SETSCHEDULER`
flags.

.. audit-event:: os.posix_spawn path,argv,env os.posix_spawn
Expand All @@ -4149,7 +4151,7 @@ written in Python, such as a mail server's external command delivery program.
setpgroup=None, resetids=False, setsid=False, setsigmask=(), \
setsigdef=(), scheduler=None)

Wraps the :c:func:`posix_spawnp` C library API for use from Python.
Wraps the :c:func:`!posix_spawnp` C library API for use from Python.

Similar to :func:`posix_spawn` except that the system searches
for the *executable* file in the list of directories specified by the
Expand Down Expand Up @@ -4330,7 +4332,7 @@ written in Python, such as a mail server's external command delivery program.

Use *show_cmd* to override the default window style. Whether this has any
effect will depend on the application being launched. Values are integers as
supported by the Win32 :c:func:`ShellExecute` function.
supported by the Win32 :c:func:`!ShellExecute` function.

:func:`startfile` returns as soon as the associated application is launched.
There is no option to wait for the application to close, and no way to retrieve
Expand All @@ -4340,7 +4342,7 @@ written in Python, such as a mail server's external command delivery program.
:func:`os.path.normpath` function to ensure that paths are properly encoded for
Win32.

To reduce interpreter startup overhead, the Win32 :c:func:`ShellExecute`
To reduce interpreter startup overhead, the Win32 :c:func:`!ShellExecute`
function is not resolved until this function is first called. If the function
cannot be resolved, :exc:`NotImplementedError` will be raised.

Expand Down