#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:
R. David Murray 2011-01-24 19:34:58 +00:00
parent a80ab10bc2
commit 7b1aae9a52
2 changed files with 60 additions and 38 deletions

View File

@ -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

View File

@ -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.