>From 82be6dc301c8260c41b91f19199997a5e26b1e9a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?=
Date: Mon, 10 Jun 2019 15:18:49 +0100
Subject: [PATCH] stat: always accept --cached, and fix docs
* src/stat.c: Always accept --cached so that this informational
option is portable across systems. Adjust --help so that
man page is better aligned.
* doc/coreutils.texi: Add documention for --cached.
* man/stat.x (SEE ALSO): mention statx().
---
doc/coreutils.texi | 21 +++++++++++++++++++++
man/stat.x | 2 +-
src/stat.c | 39 +++++++++++++++++----------------------
3 files changed, 39 insertions(+), 23 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index f543787..0b71bed 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -12366,6 +12366,27 @@ Report information about the file systems where the given files are located
instead of information about the files themselves.
This option implies the @option{-L} option.
+@item --cached=@var{mode}
+@opindex --cached=@var{mode}
+@cindex attribute caching
+Control how attributes are read from the file system;
+if supported by the system. This allows one to
+control the trade-off between freshness and efficiency
+of attribute access, especially useful with remote file systems.
+@var{mode} can be:
+
+@table @samp
+@item always
+Always read the already cached attributes if available.
+
+@item never
+Always sychronize with the latest file system attributes.
+
+@item default
+Leave the caching behavior to the underlying file system.
+
+@end table
+
@item -c
@itemx --format=@var{format}
@opindex -c
diff --git a/man/stat.x b/man/stat.x
index dc3781e..b9f8c68 100644
--- a/man/stat.x
+++ b/man/stat.x
@@ -3,4 +3,4 @@ stat \- display file or file system status
[DESCRIPTION]
.\" Add any additional description here
[SEE ALSO]
-stat(2), statfs(2)
+stat(2), statfs(2), statx(2)
diff --git a/src/stat.c b/src/stat.c
index 492daf3..3bb84f3 100644
--- a/src/stat.c
+++ b/src/stat.c
@@ -28,6 +28,12 @@
# define USE_STATVFS 0
#endif
+#if HAVE_STATX && defined STATX_INO
+# define USE_STATX 1
+#else
+# define USE_STATX 0
+#endif
+
#include
#include
#include
@@ -201,7 +207,6 @@ enum cached_mode
cached_always
};
-#if HAVE_STATX && defined STATX_INO
static char const *const cached_args[] =
{
"default", "never", "always", NULL
@@ -211,7 +216,6 @@ static enum cached_mode const cached_modes[] =
{
cached_default, cached_never, cached_always
};
-#endif
static struct option const long_options[] =
{
@@ -220,9 +224,7 @@ static struct option const long_options[] =
{"format", required_argument, NULL, 'c'},
{"printf", required_argument, NULL, PRINTF_OPTION},
{"terse", no_argument, NULL, 't'},
-#if HAVE_STATX && defined STATX_INO
{"cached", required_argument, NULL, 0},
-#endif
{GETOPT_HELP_OPTION_DECL},
{GETOPT_VERSION_OPTION_DECL},
{NULL, 0, NULL, 0}
@@ -1236,13 +1238,13 @@ struct print_args {
struct timespec btime;
};
-#if HAVE_STATX && defined STATX_INO
/* Ask statx to avoid syncing? */
static bool dont_sync;
/* Ask statx to force sync? */
static bool force_sync;
+#if USE_STATX
/* Much of the format printing requires a struct stat or timespec */
static struct timespec
statx_timestamp_to_timespec (struct statx_timestamp tsx)
@@ -1394,7 +1396,7 @@ do_stat (char const *filename, char const *format, char const *format2)
return ! fail;
}
-#else /* HAVE_STATX && defined STATX_INO */
+#else /* USE_STATX */
static struct timespec
get_birthtime (int fd, char const *filename, struct stat const *st)
@@ -1465,7 +1467,7 @@ do_stat (char const *filename, char const *format,
bool fail = print_it (format, fd, filename, print_stat, &pa);
return ! fail;
}
-#endif /* HAVE_STATX && defined STATX_INO */
+#endif /* USE_STATX */
/* Print stat info. Return zero upon success, nonzero upon failure. */
@@ -1564,7 +1566,7 @@ print_stat (char *pformat, size_t prefix_len, unsigned int m,
break;
case 'w':
{
-#if ! defined HAVE_STATX || ! defined STATX_INO
+#if ! USE_STATX
btime = get_birthtime (fd, filename, statbuf);
#endif
if (btime.tv_nsec < 0)
@@ -1575,7 +1577,7 @@ print_stat (char *pformat, size_t prefix_len, unsigned int m,
break;
case 'W':
{
-#if ! defined HAVE_STATX || ! defined STATX_INO
+#if ! USE_STATX
btime = get_birthtime (fd, filename, statbuf);
#endif
out_epoch_sec (pformat, prefix_len, neg_to_zero (btime));
@@ -1717,12 +1719,10 @@ Display file or file system status.\n\
-L, --dereference follow links\n\
-f, --file-system display file system status instead of file status\n\
"), stdout);
-#if HAVE_STATX && defined STATX_INO
fputs (_("\
- --cached=MODE specify whether and how to use cached values;\n\
- (typically useful for network file systems)\n\
+ --cached=MODE specify how to use cached attributes;\n\
+ useful on remote file systems. See MODE below\n\
"), stdout);
-#endif
fputs (_("\
-c --format=FORMAT use the specified FORMAT instead of the default;\n\
output a newline after each use of FORMAT\n\
@@ -1734,15 +1734,12 @@ Display file or file system status.\n\
fputs (HELP_OPTION_DESCRIPTION, stdout);
fputs (VERSION_OPTION_DESCRIPTION, stdout);
-#if HAVE_STATX && defined STATX_INO
fputs (_("\n\
-The valid MODE arguments to --cached are:\n\
-\n\
- always: always use cached values\n\
- never: never use cached values\n\
- default: leave it up to the underlying file system\n\
+The --cached MODE argument can be; always, never, or default.\n\
+`always` will use cached attributes if available, while\n\
+`never` will try to synchronize with the latest attributes, and\n\
+`default` will leave it up to the underlying file system.\n\
"), stdout);
-#endif
fputs (_("\n\
The valid format sequences for files (without --file-system):\n\
@@ -1877,7 +1874,6 @@ main (int argc, char *argv[])
terse = true;
break;
-#if HAVE_STATX && defined STATX_INO
case 0:
switch (XARGMATCH ("--cached", optarg, cached_args, cached_modes))
{
@@ -1894,7 +1890,6 @@ main (int argc, char *argv[])
dont_sync = false;
}
break;
-#endif
case_GETOPT_HELP_CHAR;
--
2.9.3