/*-------------------------------------------------------------------------
 *
 * File-processing utility routines.
 *
 * Assorted utility functions to work on files.
 *
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/common/file_utils.c
 *
 *-------------------------------------------------------------------------
 */

#ifndef FRONTEND
#include "postgres.h"
#else
#include "postgres_fe.h"
#endif

#include <dirent.h>
#include <fcntl.h>
#include <sys/stat.h>
#include <unistd.h>

#include "common/file_utils.h"
#ifdef FRONTEND
#include "common/logging.h"
#endif
#include "common/relpath.h"
#include "port/pg_iovec.h"

#ifdef FRONTEND

/* Define PG_FLUSH_DATA_WORKS if we have an implementation for pg_flush_data */
#if defined(HAVE_SYNC_FILE_RANGE)
#define PG_FLUSH_DATA_WORKS 1
#elif defined(USE_POSIX_FADVISE) && defined(POSIX_FADV_DONTNEED)
#define PG_FLUSH_DATA_WORKS 1
#endif

/*
 * pg_xlog has been renamed to pg_wal in version 10.
 */
#define MINIMUM_VERSION_FOR_PG_WAL 100000

static void walkdir(const char *path,
     int (*action) (const char *fname, bool isdir),
     bool process_symlinks,
     const char *exclude_dir);

#ifdef HAVE_SYNCFS

/*
 * do_syncfs -- Try to syncfs a file system
 *
 * Reports errors trying to open the path.  syncfs() errors are fatal.
 */
static void
do_syncfs(const char *path)
{
 int   fd;

 fd = open(path, O_RDONLY, 0);

 if (fd < 0)
 {
  pg_log_error("could not open file \"%s\": %m", path);
  return;
 }

 if (syncfs(fd) < 0)
 {
  pg_log_error("could not synchronize file system for file \"%s\": %m", path);
  (void) close(fd);
  exit(EXIT_FAILURE);
 }

 (void) close(fd);
}

#endif       /* HAVE_SYNCFS */

/*
 * Synchronize PGDATA and all its contents.
 *
 * We sync regular files and directories wherever they are, but we follow
 * symlinks only for pg_wal (or pg_xlog) and immediately under pg_tblspc.
 * Other symlinks are presumed to point at files we're not responsible for
 * syncing, and might not have privileges to write at all.
 *
 * serverVersion indicates the version of the server to be sync'd.
 *
 * If sync_data_files is false, this function skips syncing "base/" and any
 * other tablespace directories.
 */
void
sync_pgdata(const char *pg_data,
   int serverVersion,
   DataDirSyncMethod sync_method,
   bool sync_data_files)
{
 bool  xlog_is_symlink;
 char  pg_wal[MAXPGPATH];
 char  pg_tblspc[MAXPGPATH];

 /* handle renaming of pg_xlog to pg_wal in post-10 clusters */
 snprintf(pg_wal, MAXPGPATH, "%s/%s", pg_data,
    serverVersion < MINIMUM_VERSION_FOR_PG_WAL ? "pg_xlog" : "pg_wal");
 snprintf(pg_tblspc, MAXPGPATH, "%s/%s", pg_data, PG_TBLSPC_DIR);

 /*
  * If pg_wal is a symlink, we'll need to recurse into it separately,
  * because the first walkdir below will ignore it.
 */
 xlog_is_symlink = false;

 {
  struct stat st;

  if (lstat(pg_wal, &st) < 0)
   pg_log_error("could not stat file \"%s\": %m", pg_wal);
  else if (S_ISLNK(st.st_mode))
   xlog_is_symlink = true;
 }

 switch (sync_method)
 {
  case DATA_DIR_SYNC_METHOD_SYNCFS:
   {
#ifndef HAVE_SYNCFS
    pg_log_error("this build does not support sync method \"%s\"",
        "syncfs");
    exit(EXIT_FAILURE);
#else
    DIR     *dir;
    struct dirent *de;

    /*
     * On Linux, we don't have to open every single file one by
     * one.  We can use syncfs() to sync whole filesystems.  We
     * only expect filesystem boundaries to exist where we
     * tolerate symlinks, namely pg_wal and the tablespaces, so we
     * call syncfs() for each of those directories.
 */

    /* Sync the top level pgdata directory. */
    do_syncfs(pg_data);

    /* If any tablespaces are configured, sync each of those. */
    if (sync_data_files)
    {
     dir = opendir(pg_tblspc);
     if (dir == NULL)
      pg_log_error("could not open directory \"%s\": %m",
          pg_tblspc);
     else
     {
      while (errno = 0, (de = readdir(dir)) != NULL)
      {
       char  subpath[MAXPGPATH * 2];

       if (strcmp(de->d_name, ".") == 0 ||
        strcmp(de->d_name, "..") == 0)
        continue;

       snprintf(subpath, sizeof(subpath), "%s/%s",
          pg_tblspc, de->d_name);
       do_syncfs(subpath);
      }

      if (errno)
       pg_log_error("could not read directory \"%s\": %m",
           pg_tblspc);

      (void) closedir(dir);
     }
    }

    /* If pg_wal is a symlink, process that too. */
    if (xlog_is_symlink)
     do_syncfs(pg_wal);
#endif       /* HAVE_SYNCFS */
   }
   break;

  case DATA_DIR_SYNC_METHOD_FSYNC:
   {
    char    *exclude_dir = NULL;

    if (!sync_data_files)
     exclude_dir = psprintf("%s/base", pg_data);

    /*
     * If possible, hint to the kernel that we're soon going to
     * fsync the data directory and its contents.
 */
#ifdef PG_FLUSH_DATA_WORKS
    walkdir(pg_data, pre_sync_fname, false, exclude_dir);
    if (xlog_is_symlink)
     walkdir(pg_wal, pre_sync_fname, false, NULL);
    if (sync_data_files)
     walkdir(pg_tblspc, pre_sync_fname, true, NULL);
#endif

    /*
     * Now we do the fsync()s in the same order.
     *
     * The main call ignores symlinks, so in addition to specially
     * processing pg_wal if it's a symlink, pg_tblspc has to be
     * visited separately with process_symlinks = true.  Note that
     * if there are any plain directories in pg_tblspc, they'll
     * get fsync'd twice. That's not an expected case so we don't
     * worry about optimizing it.
 */
    walkdir(pg_data, fsync_fname, false, exclude_dir);
    if (xlog_is_symlink)
     walkdir(pg_wal, fsync_fname, false, NULL);
    if (sync_data_files)
     walkdir(pg_tblspc, fsync_fname, true, NULL);

    if (exclude_dir)
     pfree(exclude_dir);
   }
   break;
 }
}

/*
 * Synchronize the given directory and all its contents.
 *
 * This is a convenient wrapper on top of walkdir() and do_syncfs().
 */
void
sync_dir_recurse(const char *dir, DataDirSyncMethod sync_method)
{
 switch (sync_method)
 {
  case DATA_DIR_SYNC_METHOD_SYNCFS:
   {
#ifndef HAVE_SYNCFS
    pg_log_error("this build does not support sync method \"%s\"",
        "syncfs");
    exit(EXIT_FAILURE);
#else
    /*
     * On Linux, we don't have to open every single file one by
     * one.  We can use syncfs() to sync the whole filesystem.
 */
    do_syncfs(dir);
#endif       /* HAVE_SYNCFS */
   }
   break;

  case DATA_DIR_SYNC_METHOD_FSYNC:
   {
    /*
     * If possible, hint to the kernel that we're soon going to
     * fsync the data directory and its contents.
 */
#ifdef PG_FLUSH_DATA_WORKS
    walkdir(dir, pre_sync_fname, false, NULL);
#endif

    walkdir(dir, fsync_fname, false, NULL);
   }
   break;
 }
}

/*
 * walkdir: recursively walk a directory, applying the action to each
 * regular file and directory (including the named directory itself).
 *
 * If process_symlinks is true, the action and recursion are also applied
 * to regular files and directories that are pointed to by symlinks in the
 * given directory; otherwise symlinks are ignored.  Symlinks are always
 * ignored in subdirectories, ie we intentionally don't pass down the
 * process_symlinks flag to recursive calls.
 *
 * If exclude_dir is not NULL, it specifies a directory path to skip
 * processing.
 *
 * Errors are reported but not considered fatal.
 *
 * See also walkdir in fd.c, which is a backend version of this logic.
 */
static void
walkdir(const char *path,
  int (*action) (const char *fname, bool isdir),
  bool process_symlinks,
  const char *exclude_dir)
{
 DIR     *dir;
 struct dirent *de;

 if (exclude_dir && strcmp(exclude_dir, path) == 0)
  return;

 dir = opendir(path);
 if (dir == NULL)
 {
  pg_log_error("could not open directory \"%s\": %m", path);
  return;
 }

 while (errno = 0, (de = readdir(dir)) != NULL)
 {
  char  subpath[MAXPGPATH * 2];

  if (strcmp(de->d_name, ".") == 0 ||
   strcmp(de->d_name, "..") == 0)
   continue;

  snprintf(subpath, sizeof(subpath), "%s/%s", path, de->d_name);

  switch (get_dirent_type(subpath, de, process_symlinks, PG_LOG_ERROR))
  {
   case PGFILETYPE_REG:
    (*action) (subpath, false);
    break;
   case PGFILETYPE_DIR:
    walkdir(subpath, action, false, exclude_dir);
    break;
   default:

    /*
     * Errors are already reported directly by get_dirent_type(),
     * and any remaining symlinks and unknown file types are
     * ignored.
 */
    break;
  }
 }

 if (errno)
  pg_log_error("could not read directory \"%s\": %m", path);

 (void) closedir(dir);

 /*
  * It's important to fsync the destination directory itself as individual
  * file fsyncs don't guarantee that the directory entry for the file is
  * synced.  Recent versions of ext4 have made the window much wider but
  * it's been an issue for ext3 and other filesystems in the past.
 */
 (*action) (path, true);
}

/*
 * Hint to the OS that it should get ready to fsync() this file, if supported
 * by the platform.
 *
 * Ignores errors trying to open unreadable files, and reports other errors
 * non-fatally.
 */
int
pre_sync_fname(const char *fname, bool isdir)
{
#ifdef PG_FLUSH_DATA_WORKS
 int   fd;

 fd = open(fname, O_RDONLY | PG_BINARY, 0);

 if (fd < 0)
 {
  if (errno == EACCES || (isdir && errno == EISDIR))
   return 0;
  pg_log_error("could not open file \"%s\": %m", fname);
  return -1;
 }

 /*
  * We do what pg_flush_data() would do in the backend: prefer to use
  * sync_file_range, but fall back to posix_fadvise.  We ignore errors
  * because this is only a hint.
 */
#if defined(HAVE_SYNC_FILE_RANGE)
 (void) sync_file_range(fd, 0, 0, SYNC_FILE_RANGE_WRITE);
#elif defined(USE_POSIX_FADVISE) && defined(POSIX_FADV_DONTNEED)
 (void) posix_fadvise(fd, 0, 0, POSIX_FADV_DONTNEED);
#else
#error PG_FLUSH_DATA_WORKS should not have been defined
#endif

 (void) close(fd);
#endif       /* PG_FLUSH_DATA_WORKS */
 return 0;
}

/*
 * fsync_fname -- Try to fsync a file or directory
 *
 * Ignores errors trying to open unreadable files, or trying to fsync
 * directories on systems where that isn't allowed/required.  All other errors
 * are fatal.
 */
int
fsync_fname(const char *fname, bool isdir)
{
 int   fd;
 int   flags;
 int   returncode;

 /*
  * Some OSs require directories to be opened read-only whereas other
  * systems don't allow us to fsync files opened read-only; so we need both
  * cases here.  Using O_RDWR will cause us to fail to fsync files that are
  * not writable by our userid, but we assume that's OK.
 */
 flags = PG_BINARY;
 if (!isdir)
  flags |= O_RDWR;
 else
  flags |= O_RDONLY;

 /*
  * Open the file, silently ignoring errors about unreadable files (or
  * unsupported operations, e.g. opening a directory under Windows), and
  * logging others.
 */
 fd = open(fname, flags, 0);
 if (fd < 0)
 {
  if (errno == EACCES || (isdir && errno == EISDIR))
   return 0;
  pg_log_error("could not open file \"%s\": %m", fname);
  return -1;
 }

 returncode = fsync(fd);

 /*
  * Some OSes don't allow us to fsync directories at all, so we can ignore
  * those errors. Anything else needs to be reported.
 */
 if (returncode != 0 && !(isdir && (errno == EBADF || errno == EINVAL)))
 {
  pg_log_error("could not fsync file \"%s\": %m", fname);
  (void) close(fd);
  exit(EXIT_FAILURE);
 }

 (void) close(fd);
 return 0;
}

/*
 * fsync_parent_path -- fsync the parent path of a file or directory
 *
 * This is aimed at making file operations persistent on disk in case of
 * an OS crash or power failure.
 */
int
fsync_parent_path(const char *fname)
{
 char  parentpath[MAXPGPATH];

 strlcpy(parentpath, fname, MAXPGPATH);
 get_parent_directory(parentpath);

 /*
  * get_parent_directory() returns an empty string if the input argument is
  * just a file name (see comments in path.c), so handle that as being the
  * current directory.
 */
 if (strlen(parentpath) == 0)
  strlcpy(parentpath, ".", MAXPGPATH);

 if (fsync_fname(parentpath, true) != 0)
  return -1;

 return 0;
}

/*
 * durable_rename -- rename(2) wrapper, issuing fsyncs required for durability
 *
 * Wrapper around rename, similar to the backend version.
 */
int
durable_rename(const char *oldfile, const char *newfile)
{
 int   fd;

 /*
  * First fsync the old and target path (if it exists), to ensure that they
  * are properly persistent on disk. Syncing the target file is not
  * strictly necessary, but it makes it easier to reason about crashes;
  * because it's then guaranteed that either source or target file exists
  * after a crash.
 */
 if (fsync_fname(oldfile, false) != 0)
  return -1;

 fd = open(newfile, PG_BINARY | O_RDWR, 0);
 if (fd < 0)
 {
  if (errno != ENOENT)
  {
   pg_log_error("could not open file \"%s\": %m", newfile);
   return -1;
  }
 }
 else
 {
  if (fsync(fd) != 0)
  {
   pg_log_error("could not fsync file \"%s\": %m", newfile);
   close(fd);
   exit(EXIT_FAILURE);
  }
  close(fd);
 }

 /* Time to do the real deal... */
 if (rename(oldfile, newfile) != 0)
 {
  pg_log_error("could not rename file \"%s\" to \"%s\": %m",
      oldfile, newfile);
  return -1;
 }

 /*
  * To guarantee renaming the file is persistent, fsync the file with its
  * new name, and its containing directory.
 */
 if (fsync_fname(newfile, false) != 0)
  return -1;

 if (fsync_parent_path(newfile) != 0)
  return -1;

 return 0;
}

#endif       /* FRONTEND */

/*
 * Return the type of a directory entry.
 *
 * In frontend code, elevel should be a level from logging.h; in backend code
 * it should be a level from elog.h.
 */
PGFileType
get_dirent_type(const char *path,
    const struct dirent *de,
    bool look_through_symlinks,
    int elevel)
{
 PGFileType result;

 /*
  * Some systems tell us the type directly in the dirent struct, but that's
  * a BSD and Linux extension not required by POSIX.  Even when the
  * interface is present, sometimes the type is unknown, depending on the
  * filesystem.
 */
#if defined(DT_REG) && defined(DT_DIR) && defined(DT_LNK)
 if (de->d_type == DT_REG)
  result = PGFILETYPE_REG;
 else if (de->d_type == DT_DIR)
  result = PGFILETYPE_DIR;
 else if (de->d_type == DT_LNK && !look_through_symlinks)
  result = PGFILETYPE_LNK;
 else
  result = PGFILETYPE_UNKNOWN;
#else
 result = PGFILETYPE_UNKNOWN;
#endif

 if (result == PGFILETYPE_UNKNOWN)
 {
  struct stat fst;
  int   sret;


  if (look_through_symlinks)
   sret = stat(path, &fst);
  else
   sret = lstat(path, &fst);

  if (sret < 0)
  {
   result = PGFILETYPE_ERROR;
#ifdef FRONTEND
   pg_log_generic(elevel, PG_LOG_PRIMARY, "could not stat file \"%s\": %m", path);
#else
   ereport(elevel,
     (errcode_for_file_access(),
      errmsg("could not stat file \"%s\": %m", path)));
#endif
  }
  else if (S_ISREG(fst.st_mode))
   result = PGFILETYPE_REG;
  else if (S_ISDIR(fst.st_mode))
   result = PGFILETYPE_DIR;
  else if (S_ISLNK(fst.st_mode))
   result = PGFILETYPE_LNK;
 }

 return result;
}

/*
 * Compute what remains to be done after a possibly partial vectored read or
 * write.  The part of 'source' beginning after 'transferred' bytes is copied
 * to 'destination', and its length is returned.  'source' and 'destination'
 * may point to the same array, for in-place adjustment.  A return value of
 * zero indicates completion (for callers without a cheaper way to know that).
 */
int
compute_remaining_iovec(struct iovec *destination,
      const struct iovec *source,
      int iovcnt,
      size_t transferred)
{
 Assert(iovcnt > 0);

 /* Skip wholly transferred iovecs. */
 while (source->iov_len <= transferred)
 {
  transferred -= source->iov_len;
  source++;
  iovcnt--;

  /* All iovecs transferred? */
  if (iovcnt == 0)
  {
   /*
    * We don't expect the kernel to transfer more than we asked it
    * to, or something is out of sync.
 */
   Assert(transferred == 0);
   return 0;
  }
 }

 /* Copy the remaining iovecs to the front of the array. */
 if (source != destination)
  memmove(destination, source, sizeof(*source) * iovcnt);

 /* Adjust leading iovec, which may have been partially transferred. */
 Assert(destination->iov_len > transferred);
 destination->iov_base = (char *) destination->iov_base + transferred;
 destination->iov_len -= transferred;

 return iovcnt;
}

/*
 * pg_pwritev_with_retry
 *
 * Convenience wrapper for pg_pwritev() that retries on partial write.  If an
 * error is returned, it is unspecified how much has been written.
 */
ssize_t
pg_pwritev_with_retry(int fd, const struct iovec *iov, int iovcnt, off_t offset)
{
 struct iovec iov_copy[PG_IOV_MAX];
 ssize_t  sum = 0;
 ssize_t  part;

 /* We'd better have space to make a copy, in case we need to retry. */
 if (iovcnt > PG_IOV_MAX)
 {
  errno = EINVAL;
  return -1;
 }

 do
 {
  /* Write as much as we can. */
  part = pg_pwritev(fd, iov, iovcnt, offset);
  if (part < 0)
   return -1;

#ifdef SIMULATE_SHORT_WRITE
  part = Min(part, 4096);
#endif

  /* Count our progress. */
  sum += part;
  offset += part;

  /*
   * See what is left.  On the first loop we used the caller's array,
   * but in later loops we'll use our local copy that we are allowed to
   * mutate.
 */
  iovcnt = compute_remaining_iovec(iov_copy, iov, iovcnt, part);
  iov = iov_copy;
 } while (iovcnt > 0);

 return sum;
}

/*
 * pg_pwrite_zeros
 *
 * Writes zeros to file worth "size" bytes at "offset" (from the start of the
 * file), using vectored I/O.
 *
 * Returns the total amount of data written.  On failure, a negative value
 * is returned with errno set.
 */
ssize_t
pg_pwrite_zeros(int fd, size_t size, off_t offset)
{
 static const PGIOAlignedBlock zbuffer = {0}; /* worth BLCKSZ */
 void    *zerobuf_addr = unconstify(PGIOAlignedBlock *, &zbuffer)->data;
 struct iovec iov[PG_IOV_MAX];
 size_t  remaining_size = size;
 ssize_t  total_written = 0;

 /* Loop, writing as many blocks as we can for each system call. */
 while (remaining_size > 0)
 {
  int   iovcnt = 0;
  ssize_t  written;

  for (; iovcnt < PG_IOV_MAX && remaining_size > 0; iovcnt++)
  {
   size_t  this_iov_size;

   iov[iovcnt].iov_base = zerobuf_addr;

   if (remaining_size < BLCKSZ)
    this_iov_size = remaining_size;
   else
    this_iov_size = BLCKSZ;

   iov[iovcnt].iov_len = this_iov_size;
   remaining_size -= this_iov_size;
  }

  written = pg_pwritev_with_retry(fd, iov, iovcnt, offset);

  if (written < 0)
   return written;

  offset += written;
  total_written += written;
 }

 Assert(total_written == size);

 return total_written;
}