xapian-core/common/io_utils.h

   1 /** @file io_utils.h
   2  * @brief Wrappers for low-level POSIX I/O routines.
   3  */
   4 /* Copyright (C) 2006,2007,2008,2009,2011,2014,2015,2016,2018 Olly Betts
   5  * Copyright (C) 2010 Richard Boulton
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  20  */
  21
  22 #ifndef XAPIAN_INCLUDED_IO_UTILS_H
  23 #define XAPIAN_INCLUDED_IO_UTILS_H
  24
  25 #include <sys/types.h>
  26 #include "safefcntl.h"
  27 #include "safeunistd.h"
  28 #include <string>
  29
  30 /** Open a block-based file for reading.
  31  *
  32  *  @param fname  The path of the file to open.
  33  */
  34 inline int io_open_block_rd(const char * fname) {
  35     return ::open(fname, O_RDONLY | O_BINARY | O_CLOEXEC);
  36 }
  37
  38 /** Open a block-based file for reading.
  39  *
  40  *  @param fname  The path of the file to open.
  41  */
  42 inline int io_open_block_rd(const std::string & fname)
  43 {
  44     return io_open_block_rd(fname.c_str());
  45 }
  46
  47 /** Open a block-based file for writing.
  48  *
  49  *  @param fname  The path of the file to open.
  50  *  @param anew   If true, open the file anew (create or truncate it).
  51  */
  52 int io_open_block_wr(const char * fname, bool anew);
  53
  54 /** Open a block-based file for writing.
  55  *
  56  *  @param fname  The path of the file to open.
  57  *  @param anew  If true, open the file anew (create or truncate it).
  58  */
  59 inline int io_open_block_wr(const std::string & fname, bool anew)
  60 {
  61     return io_open_block_wr(fname.c_str(), anew);
  62 }
  63
  64 /** Ensure all data previously written to file descriptor fd has been written to
  65  *  disk.
  66  *
  67  *  Returns false if this could not be done.
  68  */
  69 inline bool io_sync(int fd)
  70 {
  71 #if defined HAVE_FDATASYNC
  72     // If we have it, prefer fdatasync() over fsync() as the former avoids
  73     // updating the access time so is probably a little more efficient.
  74     return fdatasync(fd) == 0;
  75 #elif defined HAVE_FSYNC
  76     return fsync(fd) == 0;
  77 #elif defined __WIN32__
  78     return _commit(fd) == 0;
  79 #else
  80 # error Cannot implement io_sync() without fdatasync(), fsync(), or _commit()
  81 #endif
  82 }
  83
  84 inline bool io_full_sync(int fd)
  85 {
  86 #ifdef F_FULLFSYNC
  87     /* Only supported on Mac OS X (at the time of writing at least).
  88      *
  89      * This call ensures that data has actually been written to disk, not just
  90      * to the drive's write cache, so it provides better protection from power
  91      * failures, etc.  It does take longer though.
  92      *
  93      * According to the sqlite sources, this shouldn't fail on a local FS so
  94      * a failure means that the file system doesn't support this operation and
  95      * therefore it's best to fallback to fdatasync()/fsync().
  96      */
  97     if (fcntl(fd, F_FULLFSYNC, 0) == 0)
  98         return true;
  99 #endif
 100     return io_sync(fd);
 101 }
 102
 103 /** Read n bytes (or until EOF) into block pointed to by p from file descriptor
 104  *  fd.
 105  *
 106  *  If a read error occurs, throws DatabaseError.
 107  *
 108  *  If @a min is specified and EOF is reached after less than @a min bytes,
 109  *  throws DatabaseCorruptError.
 110  *
 111  *  Returns the number of bytes actually read.
 112  */
 113 size_t io_read(int fd, char * p, size_t n, size_t min = 0);
 114
 115 /** Write n bytes from block pointed to by p to file descriptor fd. */
 116 void io_write(int fd, const char * p, size_t n);
 117
 118 inline void io_write(int fd, const unsigned char * p, size_t n) {
 119     io_write(fd, reinterpret_cast<const char *>(p), n);
 120 }
 121
 122 /** Read n bytes (or until EOF) into block pointed to by p from file descriptor
 123  *  fd starting at position o.
 124  *
 125  *  If a read error occurs, throws DatabaseError.
 126  *
 127  *  If @a min is specified and EOF is reached after less than @a min bytes,
 128  *  throws DatabaseCorruptError.
 129  *
 130  *  The current file position may or may not be updated.
 131  *
 132  *  Returns the number of bytes actually read.
 133  */
 134 size_t io_pread(int fd, char * p, size_t n, off_t o, size_t min = 0);
 135
 136 /** Write n bytes from block pointed to by p to file descriptor fd starting at
 137  *  position o.
 138  *
 139  *  If a read error occurs, throws DatabaseError.
 140  *
 141  *  The current file position may or may not be updated.
 142  */
 143 void io_pwrite(int fd, const char * p, size_t n, off_t o);
 144
 145 /** Readahead block b size n bytes from file descriptor fd.
 146  *
 147  *  Returns false if we can't readahead on this fd.
 148  */
 149 #ifdef HAVE_POSIX_FADVISE
 150 bool io_readahead_block(int fd, size_t n, off_t b, off_t o = 0);
 151 #else
 152 inline bool io_readahead_block(int, size_t, off_t, off_t = 0) { return false; }
 153 #endif
 154
 155 /// Read block b size n bytes into buffer p from file descriptor fd, offset o.
 156 void io_read_block(int fd, char * p, size_t n, off_t b, off_t o = 0);
 157
 158 /// Write block b size n bytes from buffer p to file descriptor fd, offset o.
 159 void io_write_block(int fd, const char * p, size_t n, off_t b, off_t o = 0);
 160
 161 inline void io_write_block(int fd, const unsigned char * p, size_t n, off_t b) {
 162     io_write_block(fd, reinterpret_cast<const char *>(p), n, b);
 163 }
 164
 165 /** Delete a file.
 166  *
 167  *  @param      filename        The file to delete.
 168  *
 169  *  @exception  Xapian::DatabaseError is thrown if @a filename existed but
 170  *              couldn't be unlinked.
 171  *  @return     true if @a filename was successfully removed; false if it
 172  *              didn't exist.  If the file is on NFS, false may be returned
 173  *              even if the file was removed (if the server fails after
 174  *              removing the file but before telling the client, and the
 175  *              client then retries).
 176  */
 177 bool io_unlink(const std::string & filename);
 178
 179 /** Rename a temporary file to its final position.
 180  *
 181  *  Attempts to deal with NFS infelicities.  If the rename fails, the temporary
 182  *  file is removed.
 183  *
 184  *  @return     true if the rename succeeded; false if it failed (and errno will
 185  *              be set appropriately).
 186  */
 187 bool io_tmp_rename(const std::string & tmp_file, const std::string & real_file);
 188
 189 #endif // XAPIAN_INCLUDED_IO_UTILS_H