[issue12350] Improve stat_result.st_blocks and st_blksize documentation
New submission from Lars Wirzenius <liw@liw.fi>: Attached patch adds a few words to the os.stat documentation for the st_blocks and st_blksize fields to clarify them. ---------- assignee: docs@python components: Documentation files: stat_result.patch keywords: patch messages: 138467 nosy: docs@python, liw priority: normal severity: normal status: open title: Improve stat_result.st_blocks and st_blksize documentation versions: Python 2.7 Added file: http://bugs.python.org/file22382/stat_result.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: Looks good for linux. Do you have a posix reference that confirms this interpretation? ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
Lars Wirzenius <liw@liw.fi> added the comment: http://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/stat.h.html says "A file system-specific preferred I/O block size for this object. In some file system types, this may vary from file to file.", which says essentially the same as the Linux stat(2) manpage from which I copied the extra words. The same page claims that st_blocks may use other units than 512 byte blocks, but that seems to be quite rare. GNU coreutils sources claim HP-UX and AIX PS/2 have non-512 blocks. Perhaps it would be better to indicate how to find out the block size? (Since st_blksize is not it, but that's an easy assumption to make.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: Ah, bingo. That was what was tickling at my memory but I couldn't remember what the exact issue was I was recalling. I forget what I was doing where that mattered, but as I vaguely remember it there is no portable way to find out what blocksize st_blocks is in. Or at least not one that is currently exposed from Python. I could be remembering wrong, though. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: Ah, found it: Issue 10016. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
Changes by R. David Murray <rdmurray@bitdance.com>: ---------- versions: +Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
Lars Wirzenius <liw@liw.fi> added the comment: Right. So I guess at least the following should be changed (I'll make an actual patch once there's consensus): * st_blocks should say that the size of block is often 512 bytes, but that's not guaranteed, and there's no way to know for sure * st_blksize should say it is size of efficient I/O, and is unrelated to st_blocks Should there be something more? Ideally, there should be a way to find out the size of blocks for st_blocks, but I don't know how to figure that out (though probably code from GNU's du could be borrowed). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: I think that wording is as good as we can do for now. Providing a way to determine the size of st_blocks blocks should be a separate issue (a feature request). That enhancement can include an update to these docs, but since it is an enhancement it will only go into the development version. But your wording fix should go into all maintained versions. I think your suggested rewording is reasonable. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
Martin Panter added the comment: What happened to this patch? The current documentation is very misleading because the descriptions of the two block fields appear to complement each other. ---------- nosy: +vadmium _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
Roundup Robot added the comment: New changeset ef5aa8d7e932 by Georg Brandl in branch '3.3': Closes #12350: clarify blocks/block size members of stat result. http://hg.python.org/cpython/rev/ef5aa8d7e932 ---------- nosy: +python-dev resolution: -> fixed stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
Roundup Robot added the comment: New changeset c32657e278f6 by Georg Brandl in branch '2.7': Closes #12350: clarify blocks/block size members of stat result. http://hg.python.org/cpython/rev/c32657e278f6 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue12350> _______________________________________
participants (4)
-
Lars Wirzenius
-
Martin Panter
-
R. David Murray
-
Roundup Robot