mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-23 17:03:23 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

Docs: Remove links to external C functions and macros in os.rst (#108138)

Browse source 
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
This commit is contained in:
Erlend E. Aasland 2023-08-19 19:03:26 +02:00 • committed by GitHub
parent 633ea217a8
commit c31c61c04e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 27 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

52
Doc/library/os.rst
View file

@ -215,7 +215,7 @@ process and user.
On some platforms, including FreeBSD and macOS, setting ``environ`` may On some platforms, including FreeBSD and macOS, setting ``environ`` may
cause memory leaks. Refer to the system documentation for 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. You can delete items in this mapping to unset environment variables.
:func:`unsetenv` will be called automatically when an item is deleted from :func:`unsetenv` will be called automatically when an item is deleted from
@ -564,7 +564,7 @@ process and user.
.. note:: .. note::
On some platforms, including FreeBSD and macOS, setting ``environ`` may 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 .. audit-event:: os.putenv key,value os.putenv
@ -646,7 +646,7 @@ process and user.
.. function:: setpgrp() .. 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. which version is implemented (if any). See the Unix manual for the semantics.
.. availability:: Unix, not Emscripten, not WASI. .. availability:: Unix, not Emscripten, not WASI.
@ -654,7 +654,7 @@ process and user.
.. function:: setpgid(pid, pgrp, /) .. 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 process with id *pid* to the process group with id *pgrp*. See the Unix manual
for the semantics. for the semantics.
@ -1077,7 +1077,7 @@ as internal buffering of data.
.. function:: fsync(fd) .. function:: fsync(fd)
Force write of file with filedescriptor *fd* to disk. On Unix, this calls the 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 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 ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
@ -2304,7 +2304,7 @@ features:
.. function:: lstat(path, *, dir_fd=None) .. 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 Similar to :func:`~os.stat`, but does not follow symbolic links. Return a
:class:`stat_result` object. :class:`stat_result` object.
@ -3147,14 +3147,16 @@ features:
Windows file attributes: ``dwFileAttributes`` member of the Windows file attributes: ``dwFileAttributes`` member of the
``BY_HANDLE_FILE_INFORMATION`` structure returned by ``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. constants in the :mod:`stat` module.
.. attribute:: st_reparse_tag .. 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. 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 The standard module :mod:`stat` defines functions and constants that are
useful for extracting information from a :c:struct:`stat` structure. (On useful for extracting information from a :c:struct:`stat` structure. (On
@ -3212,7 +3214,7 @@ features:
.. function:: statvfs(path) .. 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 an object whose attributes describe the filesystem on the given path, and
correspond to the members of the :c:struct:`statvfs` structure, namely: correspond to the members of the :c:struct:`statvfs` structure, namely:
:attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`, :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`,
@ -4303,7 +4305,7 @@ written in Python, such as a mail server's external command delivery program.
setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ setpgroup=None, resetids=False, setsid=False, setsigmask=(), \
setsigdef=(), scheduler=None) 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`. Most users should use :func:`subprocess.run` instead of :func:`posix_spawn`.
@ -4339,16 +4341,16 @@ written in Python, such as a mail server's external command delivery program.
Performs ``os.dup2(fd, new_fd)``. Performs ``os.dup2(fd, new_fd)``.
These tuples correspond to the C library These tuples correspond to the C library
:c:func:`posix_spawn_file_actions_addopen`, :c:func:`!posix_spawn_file_actions_addopen`,
:c:func:`posix_spawn_file_actions_addclose`, and :c:func:`!posix_spawn_file_actions_addclose`, and
:c:func:`posix_spawn_file_actions_adddup2` API calls used to prepare :c:func:`!posix_spawn_file_actions_adddup2` API calls used to prepare
for the :c:func:`posix_spawn` call itself. for the :c:func:`!posix_spawn` call itself.
The *setpgroup* argument will set the process group of the child to the value 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 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 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 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 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 GID of the child to the real UID and GID of the parent process. If the
@ -4356,27 +4358,27 @@ written in Python, such as a mail server's external command delivery program.
the parent. In either case, if the set-user-ID and set-group-ID permission 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 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 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 If the *setsid* argument is ``True``, it will create a new session ID
for ``posix_spawn``. *setsid* requires :c:macro:`POSIX_SPAWN_SETSID` for ``posix_spawn``. *setsid* requires :c:macro:`!POSIX_SPAWN_SETSID`
or :c:macro:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError` or :c:macro:`!POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError`
is raised. is raised.
The *setsigmask* argument will set the signal mask to the signal set The *setsigmask* argument will set the signal mask to the signal set
specified. If the parameter is not used, then the child inherits the specified. If the parameter is not used, then the child inherits the
parent's signal mask. This argument corresponds to the C library 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 The *sigdef* argument will reset the disposition of all signals in the set
specified. This argument corresponds to the C library 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 The *scheduler* argument must be a tuple containing the (optional) scheduler
policy and an instance of :class:`sched_param` with the scheduler parameters. 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 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 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. flags.
.. audit-event:: os.posix_spawn path,argv,env os.posix_spawn .. audit-event:: os.posix_spawn path,argv,env os.posix_spawn
@ -4389,7 +4391,7 @@ written in Python, such as a mail server's external command delivery program.
setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ setpgroup=None, resetids=False, setsid=False, setsigmask=(), \
setsigdef=(), scheduler=None) 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 Similar to :func:`posix_spawn` except that the system searches
for the *executable* file in the list of directories specified by the for the *executable* file in the list of directories specified by the
@ -4570,7 +4572,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 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 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. :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 There is no option to wait for the application to close, and no way to retrieve
@ -4580,7 +4582,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 :func:`os.path.normpath` function to ensure that paths are properly encoded for
Win32. 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 function is not resolved until this function is first called. If the function
cannot be resolved, :exc:`NotImplementedError` will be raised. cannot be resolved, :exc:`NotImplementedError` will be raised.