[Python-checkins] cpython: #12716: reorganize docs for os module a bit
andrew.kuchling
python-checkins at python.org
Fri Jun 21 17:50:15 CEST 2013
http://hg.python.org/cpython/rev/88edac3bc2fc
changeset: 84240:88edac3bc2fc
user: Andrew Kuchling <amk at amk.ca>
date: Fri Jun 21 11:49:57 2013 -0400
summary:
#12716: reorganize docs for os module a bit
* Move the constants used by os.open() to after the description of os.open(),
instead of putting them in their own section.
* Move RTLD_* constants to "Miscellaneous System Information" section, and
mention the sys functions they're used with.
* Mention dir_fd parameter in os.open() text.
* Typo fix ("are a supported by").
files:
Doc/library/os.rst | 454 ++++++++++++++++----------------
1 files changed, 224 insertions(+), 230 deletions(-)
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -851,11 +851,11 @@
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.
@@ -869,224 +869,6 @@
.. versionadded:: 3.3
The *dir_fd* argument.
-
-.. 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.
-
- Availability: some flavors of Unix.
-
-
-.. function:: pipe()
-
- Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
- and writing, respectively.
-
- Availability: Unix, Windows.
-
-
-.. function:: pipe2(flags)
-
- Create a pipe with *flags* set atomically.
- *flags* can be constructed by ORing together one or more of these values:
- :data:`O_NONBLOCK`, :data:`O_CLOEXEC`.
- Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
- respectively.
-
- Availability: some flavors of Unix.
-
- .. versionadded:: 3.3
-
-
-.. function:: posix_fallocate(fd, offset, len)
-
- Ensures that enough disk space is allocated for the file specified by *fd*
- starting from *offset* and continuing for *len* bytes.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. function:: posix_fadvise(fd, offset, len, advice)
-
- Announces an intention to access data in a specific pattern thus allowing
- the kernel to make optimizations.
- The advice applies to the region of the file specified by *fd* starting at
- *offset* and continuing for *len* bytes.
- *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`,
- :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
- :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. data:: POSIX_FADV_NORMAL
- POSIX_FADV_SEQUENTIAL
- POSIX_FADV_RANDOM
- POSIX_FADV_NOREUSE
- POSIX_FADV_WILLNEED
- POSIX_FADV_DONTNEED
-
- Flags that can be used in *advice* in :func:`posix_fadvise` that specify
- the access pattern that is likely to be used.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. function:: pread(fd, buffersize, offset)
-
- Read from a file descriptor, *fd*, at a position of *offset*. It will read up
- to *buffersize* number of bytes. The file offset remains unchanged.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. function:: pwrite(fd, string, offset)
-
- Write *string* to a file descriptor, *fd*, from *offset*, leaving the file
- offset unchanged.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. function:: read(fd, n)
-
- Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
- bytes read. If the end of the file referred to by *fd* has been reached, an
- empty bytes object is returned.
-
- Availability: Unix, Windows.
-
- .. note::
-
- This function is intended for low-level I/O and must be applied to a file
- descriptor as returned by :func:`os.open` or :func:`pipe`. To read a
- "file object" returned by the built-in function :func:`open` or by
- :func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its
- :meth:`~file.read` or :meth:`~file.readline` methods.
-
-
-.. function:: sendfile(out, in, offset, nbytes)
- sendfile(out, in, offset, nbytes, headers=None, trailers=None, flags=0)
-
- Copy *nbytes* bytes from file descriptor *in* to file descriptor *out*
- starting at *offset*.
- Return the number of bytes sent. When EOF is reached return 0.
-
- The first function notation is supported by all platforms that define
- :func:`sendfile`.
-
- On Linux, if *offset* is given as ``None``, the bytes are read from the
- current position of *in* and the position of *in* is updated.
-
- The second case may be used on Mac OS X and FreeBSD where *headers* and
- *trailers* are arbitrary sequences of buffers that are written before and
- after the data from *in* is written. It returns the same as the first case.
-
- On Mac OS X and FreeBSD, a value of 0 for *nbytes* specifies to send until
- the end of *in* is reached.
-
- All platforms support sockets as *out* file descriptor, and some platforms
- allow other types (e.g. regular file, pipe) as well.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. data:: SF_NODISKIO
- SF_MNOWAIT
- SF_SYNC
-
- Parameters to the :func:`sendfile` function, if the implementation supports
- them.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. function:: readv(fd, buffers)
-
- Read from a file descriptor into a number of writable buffers. *buffers* is
- an arbitrary sequence of writable buffers. Returns the total number of bytes
- read.
-
- Availability: Unix.
-
- .. versionadded:: 3.3
-
-
-.. function:: tcgetpgrp(fd)
-
- Return the process group associated with the terminal given by *fd* (an open
- file descriptor as returned by :func:`os.open`).
-
- Availability: Unix.
-
-
-.. function:: tcsetpgrp(fd, pg)
-
- Set the process group associated with the terminal given by *fd* (an open file
- descriptor as returned by :func:`os.open`) to *pg*.
-
- Availability: Unix.
-
-
-.. function:: ttyname(fd)
-
- Return a string which specifies the terminal device associated with
- file descriptor *fd*. If *fd* is not associated with a terminal device, an
- exception is raised.
-
- Availability: Unix.
-
-
-.. function:: write(fd, str)
-
- Write the bytestring in *str* to file descriptor *fd*. Return the number of
- bytes actually written.
-
- Availability: Unix, Windows.
-
- .. note::
-
- This function is intended for low-level I/O and must be applied to a file
- descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
- object" returned by the built-in function :func:`open` or by :func:`popen` or
- :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
- :meth:`~file.write` method.
-
-
-.. function:: writev(fd, buffers)
-
- Write the contents of *buffers* to file descriptor *fd*, where *buffers*
- is an arbitrary sequence of buffers.
- Returns the total number of bytes written.
-
- Availability: Unix.
-
- .. 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
@@ -1142,15 +924,214 @@
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)`.
+.. 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.
+
+ Availability: some flavors of Unix.
+
+
+.. function:: pipe()
+
+ Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for reading
+ and writing, respectively.
+
+ Availability: Unix, Windows.
+
+
+.. function:: pipe2(flags)
+
+ Create a pipe with *flags* set atomically.
+ *flags* can be constructed by ORing together one or more of these values:
+ :data:`O_NONBLOCK`, :data:`O_CLOEXEC`.
+ Return a pair of file descriptors ``(r, w)`` usable for reading and writing,
+ respectively.
+
+ Availability: some flavors of Unix.
+
+ .. versionadded:: 3.3
+
+
+.. function:: posix_fallocate(fd, offset, len)
+
+ Ensures that enough disk space is allocated for the file specified by *fd*
+ starting from *offset* and continuing for *len* bytes.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. function:: posix_fadvise(fd, offset, len, advice)
+
+ Announces an intention to access data in a specific pattern thus allowing
+ the kernel to make optimizations.
+ The advice applies to the region of the file specified by *fd* starting at
+ *offset* and continuing for *len* bytes.
+ *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`,
+ :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`,
+ :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. data:: POSIX_FADV_NORMAL
+ POSIX_FADV_SEQUENTIAL
+ POSIX_FADV_RANDOM
+ POSIX_FADV_NOREUSE
+ POSIX_FADV_WILLNEED
+ POSIX_FADV_DONTNEED
+
+ Flags that can be used in *advice* in :func:`posix_fadvise` that specify
+ the access pattern that is likely to be used.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. function:: pread(fd, buffersize, offset)
+
+ Read from a file descriptor, *fd*, at a position of *offset*. It will read up
+ to *buffersize* number of bytes. The file offset remains unchanged.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. function:: pwrite(fd, string, offset)
+
+ Write *string* to a file descriptor, *fd*, from *offset*, leaving the file
+ offset unchanged.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. function:: read(fd, n)
+
+ Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
+ bytes read. If the end of the file referred to by *fd* has been reached, an
+ empty bytes object is returned.
+
+ Availability: Unix, Windows.
+
+ .. note::
+
+ This function is intended for low-level I/O and must be applied to a file
+ descriptor as returned by :func:`os.open` or :func:`pipe`. To read a
+ "file object" returned by the built-in function :func:`open` or by
+ :func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its
+ :meth:`~file.read` or :meth:`~file.readline` methods.
+
+
+.. function:: sendfile(out, in, offset, nbytes)
+ sendfile(out, in, offset, nbytes, headers=None, trailers=None, flags=0)
+
+ Copy *nbytes* bytes from file descriptor *in* to file descriptor *out*
+ starting at *offset*.
+ Return the number of bytes sent. When EOF is reached return 0.
+
+ The first function notation is supported by all platforms that define
+ :func:`sendfile`.
+
+ On Linux, if *offset* is given as ``None``, the bytes are read from the
+ current position of *in* and the position of *in* is updated.
+
+ The second case may be used on Mac OS X and FreeBSD where *headers* and
+ *trailers* are arbitrary sequences of buffers that are written before and
+ after the data from *in* is written. It returns the same as the first case.
+
+ On Mac OS X and FreeBSD, a value of 0 for *nbytes* specifies to send until
+ the end of *in* is reached.
+
+ All platforms support sockets as *out* file descriptor, and some platforms
+ allow other types (e.g. regular file, pipe) as well.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. data:: SF_NODISKIO
+ SF_MNOWAIT
+ SF_SYNC
+
+ Parameters to the :func:`sendfile` function, if the implementation supports
+ them.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. function:: readv(fd, buffers)
+
+ Read from a file descriptor into a number of writable buffers. *buffers* is
+ an arbitrary sequence of writable buffers. Returns the total number of bytes
+ read.
+
+ Availability: Unix.
+
+ .. versionadded:: 3.3
+
+
+.. function:: tcgetpgrp(fd)
+
+ Return the process group associated with the terminal given by *fd* (an open
+ file descriptor as returned by :func:`os.open`).
+
+ Availability: Unix.
+
+
+.. function:: tcsetpgrp(fd, pg)
+
+ Set the process group associated with the terminal given by *fd* (an open file
+ descriptor as returned by :func:`os.open`) to *pg*.
+
+ Availability: Unix.
+
+
+.. function:: ttyname(fd)
+
+ Return a string which specifies the terminal device associated with
+ file descriptor *fd*. If *fd* is not associated with a terminal device, an
+ exception is raised.
+
+ Availability: Unix.
+
+
+.. function:: write(fd, str)
+
+ Write the bytestring in *str* to file descriptor *fd*. Return the number of
+ bytes actually written.
+
+ Availability: Unix, Windows.
+
+ .. note::
+
+ This function is intended for low-level I/O and must be applied to a file
+ descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file
+ object" returned by the built-in function :func:`open` or by :func:`popen` or
+ :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
+ :meth:`~file.write` method.
+
+
+.. function:: writev(fd, buffers)
+
+ Write the contents of *buffers* to file descriptor *fd*, where *buffers*
+ is an arbitrary sequence of buffers.
+ Returns the total number of bytes written.
+
+ Availability: Unix.
.. versionadded:: 3.3
@@ -3048,7 +3029,7 @@
.. 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
@@ -3298,6 +3279,19 @@
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:
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list