.. _path_fd:
* **specifying a file descriptor:**
- For some functions, the *path* argument can be not only a string giving a path
- name, but also a file descriptor. The function will then operate on the file
- referred to by the descriptor. (For POSIX systems, Python will call the
- ``f...`` version of the function.)
-
- You can check whether or not *path* can be specified as a file descriptor on
- your platform using :data:`os.supports_fd`. If it is unavailable, using it
- will raise a :exc:`NotImplementedError`.
+ Normally the *path* argument provided to functions in the :mod:`os` module
+ must be a string specifying a file path. However, some functions now
+ alternatively accept an open file descriptor for their *path* argument.
+ The function will then operate on the file referred to by the descriptor.
+ (For POSIX systems, Python will call the variant of the function prefixed
+ with ``f`` (e.g. call ``fchdir`` instead of ``chdir``).)
+
+ You can check whether or not *path* can be specified as a file descriptor
+ for a particular function on your platform using :data:`os.supports_fd`.
+ If this functionality is unavailable, using it will raise a
+ :exc:`NotImplementedError`.
- If the function also supports *dir_fd* or *follow_symlinks* arguments, it is
+ If the function also supports *dir_fd* or *follow_symlinks* arguments, it's
an error to specify one of those when supplying *path* as a file descriptor.
.. _dir_fd:
should be a file descriptor referring to a directory, and the path to operate
on should be relative; path will then be relative to that directory. If the
path is absolute, *dir_fd* is ignored. (For POSIX systems, Python will call
- the ``...at`` or ``f...at`` version of the function.)
+ the variant of the function with an ``at`` suffix and possibly prefixed with
+ ``f`` (e.g. call ``faccessat`` instead of ``access``).
- You can check whether or not *dir_fd* is supported on your platform using
- :data:`os.supports_dir_fd`. If it is unavailable, using it will raise a
- :exc:`NotImplementedError`.
+ You can check whether or not *dir_fd* is supported for a particular function
+ on your platform using :data:`os.supports_dir_fd`. If it's unavailable,
+ using it will raise a :exc:`NotImplementedError`.
.. _follow_symlinks:
* **not following symlinks:** If *follow_symlinks* is
``False``, and the last element of the path to operate on is a symbolic link,
- the function will operate on the symbolic link itself instead of the file the
- link points to. (For POSIX systems, Python will call the ``l...`` version of
- the function.)
+ the function will operate on the symbolic link itself rather than the file
+ pointed to by the link. (For POSIX systems, Python will call the ``l...``
+ variant of the function.)
- You can check whether or not *follow_symlinks* is supported on your platform
- using :data:`os.supports_follow_symlinks`. If it is unavailable, using it
- will raise a :exc:`NotImplementedError`.
+ You can check whether or not *follow_symlinks* is supported for a particular
+ function on your platform using :data:`os.supports_follow_symlinks`.
+ If it's unavailable, using it will raise a :exc:`NotImplementedError`.
.. availability:: Unix.
.. versionadded:: 3.3
- Added support for specifying an open file descriptor for *path*,
+ Added support for specifying *path* as an open file descriptor,
and the *dir_fd* and *follow_symlinks* arguments.
.. versionchanged:: 3.6
The *path* parameter became optional.
.. versionadded:: 3.3
- Added support for specifying an open file descriptor for *path*.
+ Added support for specifying *path* as an open file descriptor.
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added.
.. versionadded:: 3.3
- Added support for specifying an open file descriptor for *path*.
+ Added support for specifying *path* as an open file descriptor.
.. versionchanged:: 3.4
The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`,
.. data:: supports_dir_fd
- A :class:`~collections.abc.Set` object indicating which functions in the
- :mod:`os` module permit use of their *dir_fd* parameter. Different platforms
- provide different functionality, and an option that might work on one might
- be unsupported on another. For consistency's sakes, functions that support
- *dir_fd* always allow specifying the parameter, but will raise an exception
- if the functionality is not actually available.
-
- To check whether a particular function permits use of its *dir_fd*
- parameter, use the ``in`` operator on ``supports_dir_fd``. As an example,
- this expression determines whether the *dir_fd* parameter of :func:`os.stat`
- is locally available::
+ A :class:`set` object indicating which functions in the :mod:`os`
+ module accept an open file descriptor for their *dir_fd* parameter.
+ Different platforms provide different features, and the underlying
+ functionality Python uses to implement the *dir_fd* parameter is not
+ available on all platforms Python supports. For consistency's sake,
+ functions that may support *dir_fd* always allow specifying the
+ parameter, but will throw an exception if the functionality is used
+ when it's not locally available. (Specifying ``None`` for *dir_fd*
+ is always supported on all platforms.)
+
+ To check whether a particular function accepts an open file descriptor
+ for its *dir_fd* parameter, use the ``in`` operator on ``supports_dir_fd``.
+ As an example, this expression evaluates to ``True`` if :func:`os.stat`
+ accepts open file descriptors for *dir_fd* on the local platform::
os.stat in os.supports_dir_fd
- Currently *dir_fd* parameters only work on Unix platforms; none of them work
- on Windows.
+ Currently *dir_fd* parameters only work on Unix platforms;
+ none of them work on Windows.
.. versionadded:: 3.3
.. data:: supports_effective_ids
- A :class:`~collections.abc.Set` object indicating which functions in the
- :mod:`os` module permit use of the *effective_ids* parameter for
- :func:`os.access`. If the local platform supports it, the collection will
- contain :func:`os.access`, otherwise it will be empty.
+ A :class:`set` object indicating whether :func:`os.access` permits
+ specifying ``True`` for its *effective_ids* parameter on the local platform.
+ (Specifying ``False`` for *effective_ids* is always supported on all
+ platforms.) If the local platform supports it, the collection will contain
+ :func:`os.access`; otherwise it will be empty.
- To check whether you can use the *effective_ids* parameter for
- :func:`os.access`, use the ``in`` operator on ``supports_effective_ids``,
- like so::
+ This expression evaluates to ``True`` if :func:`os.access` supports
+ ``effective_ids=True`` on the local platform::
os.access in os.supports_effective_ids
- Currently *effective_ids* only works on Unix platforms; it does not work on
- Windows.
+ Currently *effective_ids* is only supported on Unix platforms;
+ it does not work on Windows.
.. versionadded:: 3.3
.. data:: supports_fd
- A :class:`~collections.abc.Set` object indicating which functions in the
+ A :class:`set` object indicating which functions in the
:mod:`os` module permit specifying their *path* parameter as an open file
- descriptor. Different platforms provide different functionality, and an
- option that might work on one might be unsupported on another. For
- consistency's sakes, functions that support *fd* always allow specifying
- the parameter, but will raise an exception if the functionality is not
- actually available.
+ descriptor on the local platform. Different platforms provide different
+ features, and the underlying functionality Python uses to accept open file
+ descriptors as *path* arguments is not available on all platforms Python
+ supports.
- To check whether a particular function permits specifying an open file
+ To determine whether a particular function permits specifying an open file
descriptor for its *path* parameter, use the ``in`` operator on
- ``supports_fd``. As an example, this expression determines whether
- :func:`os.chdir` accepts open file descriptors when called on your local
+ ``supports_fd``. As an example, this expression evaluates to ``True`` if
+ :func:`os.chdir` accepts open file descriptors for *path* on your local
platform::
os.chdir in os.supports_fd
.. data:: supports_follow_symlinks
- A :class:`~collections.abc.Set` object indicating which functions in the
- :mod:`os` module permit use of their *follow_symlinks* parameter. Different
- platforms provide different functionality, and an option that might work on
- one might be unsupported on another. For consistency's sakes, functions that
- support *follow_symlinks* always allow specifying the parameter, but will
- raise an exception if the functionality is not actually available.
-
- To check whether a particular function permits use of its *follow_symlinks*
- parameter, use the ``in`` operator on ``supports_follow_symlinks``. As an
- example, this expression determines whether the *follow_symlinks* parameter
- of :func:`os.stat` is locally available::
+ A :class:`set` object indicating which functions in the :mod:`os` module
+ accept ``False`` for their *follow_symlinks* parameter on the local platform.
+ Different platforms provide different features, and the underlying
+ functionality Python uses to implement *follow_symlinks* is not available
+ on all platforms Python supports. For consistency's sake, functions that
+ may support *follow_symlinks* always allow specifying the parameter, but
+ will throw an exception if the functionality is used when it's not locally
+ available. (Specifying ``True`` for *follow_symlinks* is always supported
+ on all platforms.)
+
+ To check whether a particular function accepts ``False`` for its
+ *follow_symlinks* parameter, use the ``in`` operator on
+ ``supports_follow_symlinks``. As an example, this expression evaluates
+ to ``True`` if you may specify ``follow_symlinks=False`` when calling
+ :func:`os.stat` on the local platform::
os.stat in os.supports_follow_symlinks
following symlinks <follow_symlinks>`.
.. versionadded:: 3.3
- Added support for specifying an open file descriptor for *path*,
+ Added support for specifying *path* as an open file descriptor,
and the *dir_fd*, *follow_symlinks*, and *ns* parameters.
.. versionchanged:: 3.6
.. availability:: Unix, Windows.
.. versionadded:: 3.3
- Added support for specifying an open file descriptor for *path*
+ Added support for specifying *path* as an open file descriptor
for :func:`execve`.
.. versionchanged:: 3.6
projects / python / commitdiff