Mercurial > hg > octave-lojdl > gnulib-hg
diff doc/stat-size.texi @ 14902:16c748720b01
New module 'stat-size'.
* modules/stat-size: New module. Provides macros for accessing
file size information in instances of struct stat. Depends on the
fileblocks module because it calls st_blocks.
* lib/stat-size.h: New file, adapted from coreutils' system.h.
* doc/gnulib.texi: Include stat-size.texi.
* doc/stat-size.texi: Documentation for this module.
* m4/stat-size.m4: New file; defines gl_STAT_SIZE.
* m4/fileblocks.m4: Mention that stat-size depends on the call to
AC_STRUCT_ST_BLOCKS.
| author | James Youngman <jay@gnu.org> |
|---|---|
| date | Sat, 11 Jun 2011 01:15:39 +0100 |
| parents | |
| children |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/doc/stat-size.texi @@ -0,0 +1,25 @@ +@node stat-size +@section stat-size + +The @code{stat-size} module provides a small number of macros +intended for interpreting the file size information in an instance of +@code{struct stat}. + +@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.