mirror of https://github.com/python/cpython
#10960: fix 'stat' links, link to lstat from stat, general tidy of stat doc.
Original patch by Michal Nowikowski, with some additions and wording fixes by me. I changed the wording from 'Performs a stat system call' to 'Performs the equivalent of a stat system call', since on Windows there are no stat/lstat system calls involved. I also extended Michal's breakout of the attributes into a list to the other paragraphs, and rearranged the order of the paragraphs in the 'stat' docs to make it flow better and put it in what I think is a more logical/useful order.
This commit is contained in:
parent
a80ab10bc2
commit
7b1aae9a52
|
@ -140,6 +140,7 @@ docs@python.org), and we'll be glad to correct the problem.
|
|||
* Ross Moore
|
||||
* Sjoerd Mullender
|
||||
* Dale Nagata
|
||||
* Michal Nowikowski
|
||||
* Ng Pheng Siong
|
||||
* Koray Oner
|
||||
* Tomas Oppelstrup
|
||||
|
|
|
@ -657,7 +657,7 @@ as internal buffering of data.
|
|||
|
||||
.. function:: fstat(fd)
|
||||
|
||||
Return status for file descriptor *fd*, like :func:`stat`.
|
||||
Return status for file descriptor *fd*, like :func:`~os.stat`.
|
||||
|
||||
Availability: Unix, Windows.
|
||||
|
||||
|
@ -1080,8 +1080,10 @@ Files and Directories
|
|||
|
||||
.. function:: lstat(path)
|
||||
|
||||
Like :func:`stat`, but do not follow symbolic links. This is an alias for
|
||||
:func:`stat` on platforms that do not support symbolic links.
|
||||
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. On
|
||||
platforms that do not support symbolic links, this is an alias for
|
||||
:func:`~os.stat`.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
Added support for Windows 6.0 (Vista) symbolic links.
|
||||
|
@ -1276,46 +1278,43 @@ Files and Directories
|
|||
|
||||
.. function:: stat(path)
|
||||
|
||||
Perform a :c:func:`stat` system call on the given path. The return value is an
|
||||
object whose attributes correspond to the members of the :c:type:`stat`
|
||||
structure, namely: :attr:`st_mode` (protection bits), :attr:`st_ino` (inode
|
||||
number), :attr:`st_dev` (device), :attr:`st_nlink` (number of hard links),
|
||||
:attr:`st_uid` (user id of owner), :attr:`st_gid` (group id of owner),
|
||||
:attr:`st_size` (size of file, in bytes), :attr:`st_atime` (time of most recent
|
||||
access), :attr:`st_mtime` (time of most recent content modification),
|
||||
:attr:`st_ctime` (platform dependent; time of most recent metadata change on
|
||||
Unix, or the time of creation on Windows)::
|
||||
Perform the equivalent of a :c:func:`stat` system call on the given path.
|
||||
(This function follows symlinks; to stat a symlink use :func:`lstat`.)
|
||||
|
||||
>>> import os
|
||||
>>> statinfo = os.stat('somefile.txt')
|
||||
>>> statinfo
|
||||
(33188, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732)
|
||||
>>> statinfo.st_size
|
||||
926
|
||||
The return value is an object whose attributes correspond to the members
|
||||
of the :c:type:`stat` structure, namely:
|
||||
|
||||
* :attr:`st_mode` - protection bits,
|
||||
* :attr:`st_ino` - inode number,
|
||||
* :attr:`st_dev` - device,
|
||||
* :attr:`st_nlink` - number of hard links,
|
||||
* :attr:`st_uid` - user id of owner,
|
||||
* :attr:`st_gid` - group id of owner,
|
||||
* :attr:`st_size` - size of file, in bytes,
|
||||
* :attr:`st_atime` - time of most recent access,
|
||||
* :attr:`st_mtime` - time of most recent content modification,
|
||||
* :attr:`st_ctime` - platform dependent; time of most recent metadata change on
|
||||
Unix, or the time of creation on Windows)
|
||||
|
||||
On some Unix systems (such as Linux), the following attributes may also be
|
||||
available: :attr:`st_blocks` (number of blocks allocated for file),
|
||||
:attr:`st_blksize` (filesystem blocksize), :attr:`st_rdev` (type of device if an
|
||||
inode device). :attr:`st_flags` (user defined flags for file).
|
||||
available:
|
||||
|
||||
* :attr:`st_blocks` - number of blocks allocated for file
|
||||
* :attr:`st_blksize` - filesystem blocksize
|
||||
* :attr:`st_rdev` - type of device if an inode device
|
||||
* :attr:`st_flags` - user defined flags for file
|
||||
|
||||
On other Unix systems (such as FreeBSD), the following attributes may be
|
||||
available (but may be only filled out if root tries to use them): :attr:`st_gen`
|
||||
(file generation number), :attr:`st_birthtime` (time of file creation).
|
||||
available (but may be only filled out if root tries to use them):
|
||||
|
||||
* :attr:`st_gen` - file generation number
|
||||
* :attr:`st_birthtime` - time of file creation
|
||||
|
||||
On Mac OS systems, the following attributes may also be available:
|
||||
:attr:`st_rsize`, :attr:`st_creator`, :attr:`st_type`.
|
||||
|
||||
.. index:: module: stat
|
||||
|
||||
For backward compatibility, the return value of :func:`stat` is also accessible
|
||||
as a tuple of at least 10 integers giving the most important (and portable)
|
||||
members of the :c:type:`stat` structure, in the order :attr:`st_mode`,
|
||||
:attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
|
||||
:attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
|
||||
:attr:`st_ctime`. More items may be added at the end by some implementations.
|
||||
The standard module :mod:`stat` defines functions and constants that are useful
|
||||
for extracting information from a :c:type:`stat` structure. (On Windows, some
|
||||
items are filled with dummy values.)
|
||||
* :attr:`st_rsize`
|
||||
* :attr:`st_creator`
|
||||
* :attr:`st_type`
|
||||
|
||||
.. note::
|
||||
|
||||
|
@ -1325,13 +1324,35 @@ Files and Directories
|
|||
:attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day
|
||||
resolution. See your operating system documentation for details.
|
||||
|
||||
For backward compatibility, the return value of :func:`~os.stat` is also accessible
|
||||
as a tuple of at least 10 integers giving the most important (and portable)
|
||||
members of the :c:type:`stat` structure, in the order :attr:`st_mode`,
|
||||
:attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, :attr:`st_uid`,
|
||||
:attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, :attr:`st_mtime`,
|
||||
:attr:`st_ctime`. More items may be added at the end by some implementations.
|
||||
|
||||
.. index:: module: stat
|
||||
|
||||
The standard module :mod:`stat` defines functions and constants that are useful
|
||||
for extracting information from a :c:type:`stat` structure. (On Windows, some
|
||||
items are filled with dummy values.)
|
||||
|
||||
Example::
|
||||
|
||||
>>> import os
|
||||
>>> statinfo = os.stat('somefile.txt')
|
||||
>>> statinfo
|
||||
(33188, 422511, 769, 1, 1032, 100, 926, 1105022698,1105022732, 1105022732)
|
||||
>>> statinfo.st_size
|
||||
926
|
||||
|
||||
Availability: Unix, Windows.
|
||||
|
||||
|
||||
.. function:: stat_float_times([newvalue])
|
||||
|
||||
Determine whether :class:`stat_result` represents time stamps as float objects.
|
||||
If *newvalue* is ``True``, future calls to :func:`stat` return floats, if it is
|
||||
If *newvalue* is ``True``, future calls to :func:`~os.stat` return floats, if it is
|
||||
``False``, future calls return ints. If *newvalue* is omitted, return the
|
||||
current setting.
|
||||
|
||||
|
@ -1428,8 +1449,8 @@ Files and Directories
|
|||
respectively. Whether a directory can be given for *path* depends on whether
|
||||
the operating system implements directories as files (for example, Windows
|
||||
does not). Note that the exact times you set here may not be returned by a
|
||||
subsequent :func:`stat` call, depending on the resolution with which your
|
||||
operating system records access and modification times; see :func:`stat`.
|
||||
subsequent :func:`~os.stat` call, depending on the resolution with which your
|
||||
operating system records access and modification times; see :func:`~os.stat`.
|
||||
|
||||
Availability: Unix, Windows.
|
||||
|
||||
|
|
Loading…
Reference in New Issue