From 7b1aae9a5202dff83eae13a9887a8e70ee5e70fd Mon Sep 17 00:00:00 2001 From: "R. David Murray" Date: Mon, 24 Jan 2011 19:34:58 +0000 Subject: #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. --- Doc/ACKS.txt | 1 + Doc/library/os.rst | 91 +++++++++++++++++++++++++++++++++--------------------- 2 files changed, 57 insertions(+), 35 deletions(-) diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index ca9f973..c3ab264 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -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 diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 321df1e..e6d83c1 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -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,54 +1278,73 @@ 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 + * :attr:`st_rsize` + * :attr:`st_creator` + * :attr:`st_type` + + .. note:: - For backward compatibility, the return value of :func:`stat` is also accessible + The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and + :attr:`st_ctime` members depends on the operating system and the file system. + For example, on Windows systems using the FAT or FAT32 file systems, + :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.) - .. note:: + Example:: - The exact meaning and resolution of the :attr:`st_atime`, :attr:`st_mtime`, and - :attr:`st_ctime` members depends on the operating system and the file system. - For example, on Windows systems using the FAT or FAT32 file systems, - :attr:`st_mtime` has 2-second resolution, and :attr:`st_atime` has only 1-day - resolution. See your operating system documentation for details. + >>> 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. @@ -1331,7 +1352,7 @@ Files and Directories .. 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. -- cgit v0.12