kc3-lang/gnulib/doc/stat-size.texi

• Show log

  Commit

• Hash : 0771cac8
  Author :
  Date : 2023-09-03T18:14:53
  

  same-inode, stat-size: support pointers too
  
  Add functions and macros so that we can test pointers to struct
  stat as well as plain struct stat.  This lets coreutils deal with
  structs that are only partly initialized, without relying on
  undefined behavior.
  * NEWS: Mention this.
  * doc/posix-headers/sys_stat.texi, doc/stat-size.texi:
  Mention this and modernize.
  * lib/at-func2.c (at_func2):
  * lib/fts.c (same_fd):
  * lib/rename.c (rpl_rename) [RENAME_HARD_LINK_BUG]:
  * lib/same-inode.c: New file.
  * lib/same.c (same_nameat):
  * lib/term-style-control.c (activate_term_style_controller):
  Prefer psame_inode (a, b) to SAME_INODE (*a, *b).
  * lib/hash-triple-simple.c (triple_compare_ino_str):
  * lib/hash-triple.c (triple_compare):
  Prefer PSAME_INODE (a, b) to SAME_INODE (*a, *b).
  psame_inode is not suitable since the args are not struct stat *.
  * lib/same-inode.h: Check that config.h is included first.
  (SAME_INODE_INLINE, PSAME_INODE): New macros.
  (SAME_INODE): Reimplement in terms of PSAME_INODE.
  (psame_inode): New function.
  * lib/stat-size.h (STP_BLKSIZE, STP_NBLOCKS): New macros.
  (ST_BLKSIZE, ST_NBLOCKS): Use them.
  * lib/term-style-control.c (log_signal_handler_called):
  Always define as a function, to pacify -Wunused*.
  * modules/canonicalize-lgpl-tests (Files): Add m4/musl.m4.
  (Depends-on): Call gl_MUSL_LIBC.
  * modules/same-inode (Files): Add same-inode.c.
  (Depends-on): Add extern-inline, stdbool.
  (lib_SOURCES): New macro.
  * tests/test-binary-io.c, tests/test-canonicalize-lgpl.c:
  * tests/test-canonicalize.c, tests/test-cloexec.c:
  * tests/test-dup-safer.c, tests/test-dup2.c, tests/test-error.c:
  * tests/test-fcntl.c, tests/test-fdopendir.c, tests/test-fgetc.c:
  * tests/test-fputc.c, tests/test-fread.c, tests/test-fstat.c:
  * tests/test-fstatat.c, tests/test-ftruncate.c:
  * tests/test-fwrite.c, tests/test-getcwd.c:
  * tests/test-getdtablesize.c, tests/test-isblank.c:
  * tests/test-linkat.c, tests/test-lock.c, tests/test-lstat.h:
  * tests/test-malloc-gnu.c, tests/test-openat.c:
  * tests/test-pthread-thread.c, tests/test-pthread_sigmask1.c:
  * tests/test-pthread_sigmask2.c, tests/test-ptsname.c:
  * tests/test-ptsname_r.c, tests/test-raise.c:
  * tests/test-realloc-gnu.c, tests/test-rwlock1.c:
  * tests/test-sigprocmask.c, tests/test-snprintf.c:
  * tests/test-stat.h, tests/test-term-style-control-hello.c:
  * tests/test-term-style-control-yes.c, tests/test-thread_create.c:
  * tests/test-unlinkat.c, tests/test-vasnprintf.c:
  * tests/test-xalloc-die.c:
  Adjust to these changes, and fix some warnings elicited by
  -Wall -Wextra that I ran into while testing.
  * top/maint.mk (sc_prohibit_stat_st_blocks): Mention STP_NBLOCKS.
  

Download

• doc/stat-size.texi

• @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 STP_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} and @code{STP_NBLOCKS} macros
  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
  @findex STP_BLKSIZE
  The value of @code{ST_NBLOCKSIZE} is often quite small, small enough
  that performing I/O in chunks that size would be inefficient.
  The @code{ST_BLKSIZE} and @code{STP_BLKSIZE} macros
  give 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.
  

Download