diff options
Diffstat (limited to 'Doc/library/os.rst')
| -rw-r--r-- | Doc/library/os.rst | 245 |
1 files changed, 158 insertions, 87 deletions
diff --git a/Doc/library/os.rst b/Doc/library/os.rst index ee378a6..729fa14 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -54,7 +54,7 @@ Notes on the availability of these functions: The name of the operating system dependent module imported. The following names have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, - ``'os2'``, ``'ce'``, ``'java'``. + ``'ce'``, ``'java'``. .. seealso:: :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives @@ -685,17 +685,30 @@ as internal buffering of data. .. function:: dup(fd) - Return a duplicate of file descriptor *fd*. + Return a duplicate of file descriptor *fd*. The new file descriptor is + :ref:`non-inheritable <fd_inheritance>`. + + On Windows, when duplicating a standard stream (0: stdin, 1: stdout, + 2: stderr), the new file descriptor is :ref:`inheritable + <fd_inheritance>`. Availability: Unix, Windows. + .. versionchanged:: 3.4 + The new file descriptor is now non-inheritable. + -.. function:: dup2(fd, fd2) +.. function:: dup2(fd, fd2, inheritable=True) Duplicate file descriptor *fd* to *fd2*, closing the latter first if necessary. + The file descriptor *fd2* is :ref:`inheritable <fd_inheritance>` by default, + or non-inheritable if *inheritable* is ``False``. Availability: Unix, Windows. + .. versionchanged:: 3.4 + Add the optional *inheritable* parameter. + .. function:: fchmod(fd, mode) @@ -846,17 +859,21 @@ as internal buffering of data. Open the file *file* and set various flags according to *flags* and possibly its mode according to *mode*. When computing *mode*, the current umask value is first masked out. Return the file descriptor for the newly opened file. + The new file descriptor is :ref:`non-inheritable <fd_inheritance>`. For a description of the flag and mode values, see the C run-time documentation; flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in - this module too (see :ref:`open-constants`). In particular, on Windows adding + the :mod:`os` module. In particular, on Windows adding :const:`O_BINARY` is needed to open files in binary mode. This function can support :ref:`paths relative to directory descriptors - <dir_fd>`. + <dir_fd>` with the *dir_fd* parameter. Availability: Unix, Windows. + .. versionchanged:: 3.4 + The new file descriptor is now non-inheritable. + .. note:: This function is intended for low-level I/O. For normal usage, use the @@ -867,25 +884,92 @@ as internal buffering of data. .. versionadded:: 3.3 The *dir_fd* argument. +The following constants are options for the *flags* parameter to the +:func:`~os.open` function. They can be combined using the bitwise OR operator +``|``. Some of them are not available on all platforms. For descriptions of +their availability and use, consult the :manpage:`open(2)` manual page on Unix +or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows. + + +.. data:: O_RDONLY + O_WRONLY + O_RDWR + O_APPEND + O_CREAT + O_EXCL + O_TRUNC + + These constants are available on Unix and Windows. + + +.. data:: O_DSYNC + O_RSYNC + O_SYNC + O_NDELAY + O_NONBLOCK + O_NOCTTY + O_SHLOCK + O_EXLOCK + O_CLOEXEC + + These constants are only available on Unix. + + .. versionchanged:: 3.3 + Add :data:`O_CLOEXEC` constant. + +.. data:: O_BINARY + O_NOINHERIT + O_SHORT_LIVED + O_TEMPORARY + O_RANDOM + O_SEQUENTIAL + O_TEXT + + These constants are only available on Windows. + + +.. data:: O_ASYNC + O_DIRECT + O_DIRECTORY + O_NOFOLLOW + O_NOATIME + O_PATH + O_TMPFILE + + These constants are GNU extensions and not present if they are not defined by + the C library. + + .. versionchanged:: 3.4 + Add :data:`O_TMPFILE` constant. It's only available on Linux Kernel 3.11 + or newer. + .. function:: openpty() .. index:: module: pty - Open a new pseudo-terminal pair. Return a pair of file descriptors ``(master, - slave)`` for the pty and the tty, respectively. For a (slightly) more portable - approach, use the :mod:`pty` module. + Open a new pseudo-terminal pair. Return a pair of file descriptors + ``(master, slave)`` for the pty and the tty, respectively. The new file + descriptors are :ref:`non-inheritable <fd_inheritance>`. For a (slightly) more + portable approach, use the :mod:`pty` module. Availability: some flavors of Unix. + .. versionchanged:: 3.4 + The new file descriptors are now non-inheritable. + .. function:: pipe() - Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading - and writing, respectively. + Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for + reading and writing, respectively. The new file descriptor are + :ref:`non-inheritable <fd_inheritance>`. Availability: Unix, Windows. + .. versionchanged:: 3.4 + The new file descriptors are now non-inheritable. + .. function:: pipe2(flags) @@ -1080,78 +1164,6 @@ as internal buffering of data. .. versionadded:: 3.3 -.. _open-constants: - -``open()`` flag constants -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following constants are options for the *flags* parameter to the -:func:`~os.open` function. They can be combined using the bitwise OR operator -``|``. Some of them are not available on all platforms. For descriptions of -their availability and use, consult the :manpage:`open(2)` manual page on Unix -or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows. - - -.. data:: O_RDONLY - O_WRONLY - O_RDWR - O_APPEND - O_CREAT - O_EXCL - O_TRUNC - - These constants are available on Unix and Windows. - - -.. data:: O_DSYNC - O_RSYNC - O_SYNC - O_NDELAY - O_NONBLOCK - O_NOCTTY - O_SHLOCK - O_EXLOCK - O_CLOEXEC - - These constants are only available on Unix. - - .. versionchanged:: 3.3 - Add :data:`O_CLOEXEC` constant. - -.. data:: O_BINARY - O_NOINHERIT - O_SHORT_LIVED - O_TEMPORARY - O_RANDOM - O_SEQUENTIAL - O_TEXT - - These constants are only available on Windows. - - -.. data:: O_ASYNC - O_DIRECT - O_DIRECTORY - O_NOFOLLOW - O_NOATIME - - These constants are GNU extensions and not present if they are not defined by - the C library. - - -.. data:: RTLD_LAZY - RTLD_NOW - RTLD_GLOBAL - RTLD_LOCAL - RTLD_NODELETE - RTLD_NOLOAD - RTLD_DEEPBIND - - See the Unix manual page :manpage:`dlopen(3)`. - - .. versionadded:: 3.3 - - .. _terminal-size: Querying the size of a terminal @@ -1189,6 +1201,49 @@ Querying the size of a terminal Height of the terminal window in characters. +.. _fd_inheritance: + +Inheritance of File Descriptors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.4 + +A file descriptor has an "inheritable" flag which indicates if the file descriptor +can be inherited by child processes. Since Python 3.4, file descriptors +created by Python are non-inheritable by default. + +On UNIX, non-inheritable file descriptors are closed in child processes at the +execution of a new program, other file descriptors are inherited. + +On Windows, non-inheritable handles and file descriptors are closed in child +processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout +and stderr), which are always inherited. Using :func:`os.spawn*` functions, +all inheritable handles and all inheritable file descriptors are inherited. +Using the :mod:`subprocess` module, all file descriptors except standard +streams are closed, and inheritable handles are only inherited if the +*close_fds* parameter is ``False``. + +.. function:: get_inheritable(fd) + + Get the "inheritable" flag of the specified file descriptor (a boolean). + +.. function:: set_inheritable(fd, inheritable) + + Set the "inheritable" flag of the specified file descriptor. + +.. function:: get_handle_inheritable(handle) + + Get the "inheritable" flag of the specified handle (a boolean). + + Availability: Windows. + +.. function:: set_handle_inheritable(handle, inheritable) + + Set the "inheritable" flag of the specified handle. + + Availability: Windows. + + .. _os-file-dir: Files and Directories @@ -3045,7 +3100,7 @@ information, consult your Unix manpages. .. versionadded:: 3.3 -The following scheduling policies are exposed if they are a supported by the +The following scheduling policies are exposed if they are supported by the operating system. .. data:: SCHED_OTHER @@ -3154,10 +3209,6 @@ operating system. Return the set of CPUs the process with PID *pid* (or the current process if zero) is restricted to. - .. seealso:: - :func:`multiprocessing.cpu_count` returns the number of CPUs in the - system. - .. _os-path: @@ -3195,6 +3246,13 @@ Miscellaneous System Information Availability: Unix. +.. function:: cpu_count() + + Return the number of CPUs in the system. Returns None if undetermined. + + .. versionadded:: 3.4 + + .. function:: getloadavg() Return the number of processes in the system run queue averaged over the last @@ -3292,6 +3350,19 @@ Higher-level operations on pathnames are defined in the :mod:`os.path` module. The file path of the null device. For example: ``'/dev/null'`` for POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`. +.. data:: RTLD_LAZY + RTLD_NOW + RTLD_GLOBAL + RTLD_LOCAL + RTLD_NODELETE + RTLD_NOLOAD + RTLD_DEEPBIND + + Flags for use with the :func:`~sys.setdlopenflags` and + :func:`~sys.getdlopenflags` functions. See the Unix manual page + :manpage:`dlopen(3)` for what the different flags mean. + + .. versionadded:: 3.3 .. _os-miscfunc: |