/*------------------------------------------------------------------------- * * 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 #include #include #include #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; }