src/include/storage/fd.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * fd.h
   4  *        Virtual file descriptor definitions.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/storage/fd.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14
  15 /*
  16  * calls:
  17  *
  18  *      File {Close, Read, ReadV, Write, WriteV, Size, Sync}
  19  *      {Path Name Open, Allocate, Free} File
  20  *
  21  * These are NOT JUST RENAMINGS OF THE UNIX ROUTINES.
  22  * Use them for all file activity...
  23  *
  24  *      File fd;
  25  *      fd = PathNameOpenFile("foo", O_RDONLY);
  26  *
  27  *      AllocateFile();
  28  *      FreeFile();
  29  *
  30  * Use AllocateFile, not fopen, if you need a stdio file (FILE*); then
  31  * use FreeFile, not fclose, to close it.  AVOID using stdio for files
  32  * that you intend to hold open for any length of time, since there is
  33  * no way for them to share kernel file descriptors with other files.
  34  *
  35  * Likewise, use AllocateDir/FreeDir, not opendir/closedir, to allocate
  36  * open directories (DIR*), and OpenTransientFile/CloseTransientFile for an
  37  * unbuffered file descriptor.
  38  *
  39  * If you really can't use any of the above, at least call AcquireExternalFD
  40  * or ReserveExternalFD to report any file descriptors that are held for any
  41  * length of time.  Failure to do so risks unnecessary EMFILE errors.
  42  */
  43 #ifndef FD_H
  44 #define FD_H
  45
  46 #include "port/pg_iovec.h"
  47
  48 #include <dirent.h>
  49 #include <fcntl.h>
  50
  51 typedef int File;
  52
  53
  54 #define IO_DIRECT_DATA                  0x01
  55 #define IO_DIRECT_WAL                   0x02
  56 #define IO_DIRECT_WAL_INIT              0x04
  57
  58
  59 /* GUC parameter */
  60 extern PGDLLIMPORT int max_files_per_process;
  61 extern PGDLLIMPORT bool data_sync_retry;
  62 extern PGDLLIMPORT int recovery_init_sync_method;
  63 extern PGDLLIMPORT int io_direct_flags;
  64
  65 /*
  66  * This is private to fd.c, but exported for save/restore_backend_variables()
  67  */
  68 extern PGDLLIMPORT int max_safe_fds;
  69
  70 /*
  71  * On Windows, we have to interpret EACCES as possibly meaning the same as
  72  * ENOENT, because if a file is unlinked-but-not-yet-gone on that platform,
  73  * that's what you get.  Ugh.  This code is designed so that we don't
  74  * actually believe these cases are okay without further evidence (namely,
  75  * a pending fsync request getting canceled ... see ProcessSyncRequests).
  76  */
  77 #ifndef WIN32
  78 #define FILE_POSSIBLY_DELETED(err)      ((err) == ENOENT)
  79 #else
  80 #define FILE_POSSIBLY_DELETED(err)      ((err) == ENOENT || (err) == EACCES)
  81 #endif
  82
  83 /*
  84  * O_DIRECT is not standard, but almost every Unix has it.  We translate it
  85  * to the appropriate Windows flag in src/port/open.c.  We simulate it with
  86  * fcntl(F_NOCACHE) on macOS inside fd.c's open() wrapper.  We use the name
  87  * PG_O_DIRECT rather than defining O_DIRECT in that case (probably not a good
  88  * idea on a Unix).  We can only use it if the compiler will correctly align
  89  * PGIOAlignedBlock for us, though.
  90  */
  91 #if defined(O_DIRECT) && defined(pg_attribute_aligned)
  92 #define         PG_O_DIRECT O_DIRECT
  93 #elif defined(F_NOCACHE)
  94 #define         PG_O_DIRECT 0x80000000
  95 #define         PG_O_DIRECT_USE_F_NOCACHE
  96 #else
  97 #define         PG_O_DIRECT 0
  98 #endif
  99
 100 /*
 101  * prototypes for functions in fd.c
 102  */
 103
 104 /* Operations on virtual Files --- equivalent to Unix kernel file ops */
 105 extern File PathNameOpenFile(const char *fileName, int fileFlags);
 106 extern File PathNameOpenFilePerm(const char *fileName, int fileFlags, mode_t fileMode);
 107 extern File OpenTemporaryFile(bool interXact);
 108 extern void FileClose(File file);
 109 extern int      FilePrefetch(File file, off_t offset, off_t amount, uint32 wait_event_info);
 110 extern ssize_t FileReadV(File file, const struct iovec *iov, int iovcnt, off_t offset, uint32 wait_event_info);
 111 extern ssize_t FileWriteV(File file, const struct iovec *iov, int iovcnt, off_t offset, uint32 wait_event_info);
 112 extern int      FileSync(File file, uint32 wait_event_info);
 113 extern int      FileZero(File file, off_t offset, off_t amount, uint32 wait_event_info);
 114 extern int      FileFallocate(File file, off_t offset, off_t amount, uint32 wait_event_info);
 115
 116 extern off_t FileSize(File file);
 117 extern int      FileTruncate(File file, off_t offset, uint32 wait_event_info);
 118 extern void FileWriteback(File file, off_t offset, off_t nbytes, uint32 wait_event_info);
 119 extern char *FilePathName(File file);
 120 extern int      FileGetRawDesc(File file);
 121 extern int      FileGetRawFlags(File file);
 122 extern mode_t FileGetRawMode(File file);
 123
 124 /* Operations used for sharing named temporary files */
 125 extern File PathNameCreateTemporaryFile(const char *path, bool error_on_failure);
 126 extern File PathNameOpenTemporaryFile(const char *path, int mode);
 127 extern bool PathNameDeleteTemporaryFile(const char *path, bool error_on_failure);
 128 extern void PathNameCreateTemporaryDir(const char *basedir, const char *directory);
 129 extern void PathNameDeleteTemporaryDir(const char *dirname);
 130 extern void TempTablespacePath(char *path, Oid tablespace);
 131
 132 /* Operations that allow use of regular stdio --- USE WITH CAUTION */
 133 extern FILE *AllocateFile(const char *name, const char *mode);
 134 extern int      FreeFile(FILE *file);
 135
 136 /* Operations that allow use of pipe streams (popen/pclose) */
 137 extern FILE *OpenPipeStream(const char *command, const char *mode);
 138 extern int      ClosePipeStream(FILE *file);
 139
 140 /* Operations to allow use of the <dirent.h> library routines */
 141 extern DIR *AllocateDir(const char *dirname);
 142 extern struct dirent *ReadDir(DIR *dir, const char *dirname);
 143 extern struct dirent *ReadDirExtended(DIR *dir, const char *dirname,
 144                                                                           int elevel);
 145 extern int      FreeDir(DIR *dir);
 146
 147 /* Operations to allow use of a plain kernel FD, with automatic cleanup */
 148 extern int      OpenTransientFile(const char *fileName, int fileFlags);
 149 extern int      OpenTransientFilePerm(const char *fileName, int fileFlags, mode_t fileMode);
 150 extern int      CloseTransientFile(int fd);
 151
 152 /* If you've really really gotta have a plain kernel FD, use this */
 153 extern int      BasicOpenFile(const char *fileName, int fileFlags);
 154 extern int      BasicOpenFilePerm(const char *fileName, int fileFlags, mode_t fileMode);
 155
 156 /* Use these for other cases, and also for long-lived BasicOpenFile FDs */
 157 extern bool AcquireExternalFD(void);
 158 extern void ReserveExternalFD(void);
 159 extern void ReleaseExternalFD(void);
 160
 161 /* Make a directory with default permissions */
 162 extern int      MakePGDirectory(const char *directoryName);
 163
 164 /* Miscellaneous support routines */
 165 extern void InitFileAccess(void);
 166 extern void InitTemporaryFileAccess(void);
 167 extern void set_max_safe_fds(void);
 168 extern void closeAllVfds(void);
 169 extern void SetTempTablespaces(Oid *tableSpaces, int numSpaces);
 170 extern bool TempTablespacesAreSet(void);
 171 extern int      GetTempTablespaces(Oid *tableSpaces, int numSpaces);
 172 extern Oid      GetNextTempTableSpace(void);
 173 extern void AtEOXact_Files(bool isCommit);
 174 extern void AtEOSubXact_Files(bool isCommit, SubTransactionId mySubid,
 175                                                           SubTransactionId parentSubid);
 176 extern void RemovePgTempFiles(void);
 177 extern void RemovePgTempFilesInDir(const char *tmpdirname, bool missing_ok,
 178                                                                    bool unlink_all);
 179 extern bool looks_like_temp_rel_name(const char *name);
 180
 181 extern int      pg_fsync(int fd);
 182 extern int      pg_fsync_no_writethrough(int fd);
 183 extern int      pg_fsync_writethrough(int fd);
 184 extern int      pg_fdatasync(int fd);
 185 extern bool pg_file_exists(const char *name);
 186 extern void pg_flush_data(int fd, off_t offset, off_t nbytes);
 187 extern int      pg_truncate(const char *path, off_t length);
 188 extern void fsync_fname(const char *fname, bool isdir);
 189 extern int      fsync_fname_ext(const char *fname, bool isdir, bool ignore_perm, int elevel);
 190 extern int      durable_rename(const char *oldfile, const char *newfile, int elevel);
 191 extern int      durable_unlink(const char *fname, int elevel);
 192 extern void SyncDataDirectory(void);
 193 extern int      data_sync_elevel(int elevel);
 194
 195 static inline ssize_t
 196 FileRead(File file, void *buffer, size_t amount, off_t offset,
 197                  uint32 wait_event_info)
 198 {
 199         struct iovec iov = {
 200                 .iov_base = buffer,
 201                 .iov_len = amount
 202         };
 203
 204         return FileReadV(file, &iov, 1, offset, wait_event_info);
 205 }
 206
 207 static inline ssize_t
 208 FileWrite(File file, const void *buffer, size_t amount, off_t offset,
 209                   uint32 wait_event_info)
 210 {
 211         struct iovec iov = {
 212                 .iov_base = unconstify(void *, buffer),
 213                 .iov_len = amount
 214         };
 215
 216         return FileWriteV(file, &iov, 1, offset, wait_event_info);
 217 }
 218
 219 #endif                                                  /* FD_H */