* doc/gnulib.texi: Include stat-macros.texi.
* doc/stat-macros.texi: Documentation for this module.
---
ChangeLog | 6 ++++++
doc/gnulib.texi | 4 ++++
doc/stat-macros.texi | 31 +++++++++++++++++++++++++++++++
3 files changed, 41 insertions(+), 0 deletions(-)
create mode 100644 doc/stat-macros.texi
diff --git a/ChangeLog b/ChangeLog
index c7ddc06..3f74eea 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2011-06-07 James Youngman <j...@gnu.org>
+
+ stat-macros: document the stat-macros module.
+ * doc/gnulib.texi: Include stat-macros.texi.
+ * doc/stat-macros.texi: Documentation for this module.
+
2011-06-06 James Youngman <j...@gnu.org>
stat-macros: Enhance to provide block-related information.
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 1e1ad40..416d48c 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -6512,6 +6512,7 @@ This list of functions is sorted according to the header
that declares them.
* warnings::
* manywarnings::
* Running self-tests under valgrind::
+* stat-macros::
@end menu
@node alloca
@@ -6608,6 +6609,9 @@ ASCII characters.
@include valgrind-tests.texi
+@include stat-macros.texi
+
+
@node Regular expressions
@chapter Regular expressions
diff --git a/doc/stat-macros.texi b/doc/stat-macros.texi
new file mode 100644
index 0000000..b925032
--- /dev/null
+++ b/doc/stat-macros.texi
@@ -0,0 +1,31 @@
+@node stat-macros
+@section stat-macros
+
+The @code{stat-macros} module provides a small number of macros
+intended for interpreting the information in an instance of
+@code{struct stat}.
+
+@c not a function, but index it anyhow.
+@findex CHMOD_MODE_BITS
+This macro is a bitmask indicating which bits in the @code{st_mode}
+member of @code{struct stat} can be affected by @code{chmod}.
+
+@c We deliberately don't document DEV_BSIZE (it looks to James
+@c Youngman as if the ST_NBLOCKSIZE macro should be used instead).
+
+@findex ST_NBLOCKS
+@findex ST_NBLOCKSIZE
+@cindex block size
+On POSIX systems, the @code{st_blocks} member of @code{struct stat}
+contains the number of disk blocks occupied by a file. The
+@code{ST_NBLOCKS} macro is used to estimate this quantity on systems
+which don't actually have @code{st_blocks}. Each of these blocks
+contains @code{ST_NBLOCKSIZE} bytes.
+
+@findex ST_BLKSIZE
+The value of @code{ST_NBLOCKSIZE} is often quite small, small enough
+that performing I/O in chunks that size would be inefficient.
+@code{ST_BLKSIZE} is the I/O block size recommended for I/O to this
+file. This is not guaranteed to give optimum performance, but it
+should be reasonably efficient.
+
--
1.7.2.5
