include/file_change_detection.h

   1 /* Detecting file changes using modification times.
   2    Copyright (C) 2017-2023 Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <https://www.gnu.org/licenses/>.  */
  18
  19 #ifndef _FILE_CHANGE_DETECTION_H
  20 #define _FILE_CHANGE_DETECTION_H
  21
  22 #include <stdbool.h>
  23 #include <stdio.h>
  24 #include <sys/stat.h>
  25 #include <sys/types.h>
  26
  27 /* Items for identifying a particular file version.  Excerpt from
  28    struct stat64.  */
  29 struct file_change_detection
  30 {
  31   /* Special values: 0 if file does not exist.  -1 to force mismatch
  32      with the next comparison.  */
  33   off64_t size;
  34
  35   ino64_t ino;
  36   struct __timespec64 mtime;
  37   struct __timespec64 ctime;
  38 };
  39
  40 /* Returns true if *LEFT and *RIGHT describe the same version of the
  41    same file.  */
  42 bool __file_is_unchanged (const struct file_change_detection *left,
  43                           const struct file_change_detection *right);
  44
  45 /* Extract file change information to *FILE from the stat buffer
  46    *ST.  */
  47 void __file_change_detection_for_stat (struct file_change_detection *file,
  48                                        const struct __stat64_t64 *st);
  49
  50 /* Writes file change information for PATH to *FILE.  Returns true on
  51    success.  For benign errors, *FILE is cleared, and true is
  52    returned.  For errors indicating resource outages and the like,
  53    false is returned.  */
  54 bool __file_change_detection_for_path (struct file_change_detection *file,
  55                                        const char *path);
  56
  57 /* Writes file change information for the stream FP to *FILE.  Returns
  58    true on success, false on failure.  If FP is NULL, treat the file
  59    as non-existing.  */
  60 bool __file_change_detection_for_fp (struct file_change_detection *file,
  61                                      FILE *fp);
  62
  63 #ifndef _ISOMAC
  64 libc_hidden_proto (__file_is_unchanged)
  65 libc_hidden_proto (__file_change_detection_for_stat)
  66 libc_hidden_proto (__file_change_detection_for_path)
  67 libc_hidden_proto (__file_change_detection_for_fp)
  68 #endif
  69
  70 #endif /* _FILE_CHANGE_DETECTION_H */