(original) (raw)

Index: Doc/library/os.rst =================================================================== --- Doc/library/os.rst (revision 88145) +++ Doc/library/os.rst (working copy) @@ -657,7 +657,7 @@ .. 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,8 @@ .. 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. + Like :func:`~os.stat`, but do not follow symbolic links. This is an alias for + :func:`~os.stat` on platforms that do not support symbolic links. .. versionchanged:: 3.2 Added support for Windows 6.0 (Vista) symbolic links. @@ -1276,16 +1276,26 @@ .. 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 a :c:func:`stat` system call on the given path. The function follows + symlinks, so to stat a symlink :func:`lstat` should be used. + 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) + + Example:: + >>> import os >>> statinfo = os.stat('somefile.txt') >>> statinfo @@ -1309,7 +1319,7 @@ .. index:: module: stat - For backward compatibility, the return value of :func:`stat` is also accessible + 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`, @@ -1333,7 +1343,7 @@ .. 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. @@ -1430,8 +1440,8 @@ 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.