folly/FileUtil.h

   1 /*
   2  * Copyright 2017 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #pragma once
  18
  19 #include <sys/stat.h>
  20 #include <sys/types.h>
  21
  22 #include <cassert>
  23 #include <limits>
  24
  25 #include <folly/Portability.h>
  26 #include <folly/Range.h>
  27 #include <folly/ScopeGuard.h>
  28 #include <folly/portability/Fcntl.h>
  29 #include <folly/portability/SysUio.h>
  30 #include <folly/portability/Unistd.h>
  31
  32 namespace folly {
  33
  34 /**
  35  * Convenience wrappers around some commonly used system calls.  The *NoInt
  36  * wrappers retry on EINTR.  The *Full wrappers retry on EINTR and also loop
  37  * until all data is written.  Note that *Full wrappers weaken the thread
  38  * semantics of underlying system calls.
  39  */
  40 int openNoInt(const char* name, int flags, mode_t mode = 0666);
  41 int closeNoInt(int fd);
  42 int dupNoInt(int fd);
  43 int dup2NoInt(int oldfd, int newfd);
  44 int fsyncNoInt(int fd);
  45 int fdatasyncNoInt(int fd);
  46 int ftruncateNoInt(int fd, off_t len);
  47 int truncateNoInt(const char* path, off_t len);
  48 int flockNoInt(int fd, int operation);
  49 int shutdownNoInt(int fd, int how);
  50
  51 ssize_t readNoInt(int fd, void* buf, size_t n);
  52 ssize_t preadNoInt(int fd, void* buf, size_t n, off_t offset);
  53 ssize_t readvNoInt(int fd, const iovec* iov, int count);
  54
  55 ssize_t writeNoInt(int fd, const void* buf, size_t n);
  56 ssize_t pwriteNoInt(int fd, const void* buf, size_t n, off_t offset);
  57 ssize_t writevNoInt(int fd, const iovec* iov, int count);
  58
  59 /**
  60  * Wrapper around read() (and pread()) that, in addition to retrying on
  61  * EINTR, will loop until all data is read.
  62  *
  63  * This wrapper is only useful for blocking file descriptors (for non-blocking
  64  * file descriptors, you have to be prepared to deal with incomplete reads
  65  * anyway), and only exists because POSIX allows read() to return an incomplete
  66  * read if interrupted by a signal (instead of returning -1 and setting errno
  67  * to EINTR).
  68  *
  69  * Note that this wrapper weakens the thread safety of read(): the file pointer
  70  * is shared between threads, but the system call is atomic.  If multiple
  71  * threads are reading from a file at the same time, you don't know where your
  72  * data came from in the file, but you do know that the returned bytes were
  73  * contiguous.  You can no longer make this assumption if using readFull().
  74  * You should probably use pread() when reading from the same file descriptor
  75  * from multiple threads simultaneously, anyway.
  76  *
  77  * Note that readvFull and preadvFull require iov to be non-const, unlike
  78  * readv and preadv.  The contents of iov after these functions return
  79  * is unspecified.
  80  */
  81 ssize_t readFull(int fd, void* buf, size_t n);
  82 ssize_t preadFull(int fd, void* buf, size_t n, off_t offset);
  83 ssize_t readvFull(int fd, iovec* iov, int count);
  84 ssize_t preadvFull(int fd, iovec* iov, int count, off_t offset);
  85
  86 /**
  87  * Similar to readFull and preadFull above, wrappers around write() and
  88  * pwrite() that loop until all data is written.
  89  *
  90  * Generally, the write() / pwrite() system call may always write fewer bytes
  91  * than requested, just like read().  In certain cases (such as when writing to
  92  * a pipe), POSIX provides stronger guarantees, but not in the general case.
  93  * For example, Linux (even on a 64-bit platform) won't write more than 2GB in
  94  * one write() system call.
  95  *
  96  * Note that writevFull and pwritevFull require iov to be non-const, unlike
  97  * writev and pwritev.  The contents of iov after these functions return
  98  * is unspecified.
  99  *
 100  * These functions return -1 on error, or the total number of bytes written
 101  * (which is always the same as the number of requested bytes) on success.
 102  */
 103 ssize_t writeFull(int fd, const void* buf, size_t n);
 104 ssize_t pwriteFull(int fd, const void* buf, size_t n, off_t offset);
 105 ssize_t writevFull(int fd, iovec* iov, int count);
 106 ssize_t pwritevFull(int fd, iovec* iov, int count, off_t offset);
 107
 108 /**
 109  * Read entire file (if num_bytes is defaulted) or no more than
 110  * num_bytes (otherwise) into container *out. The container is assumed
 111  * to be contiguous, with element size equal to 1, and offer size(),
 112  * reserve(), and random access (e.g. std::vector<char>, std::string,
 113  * fbstring).
 114  *
 115  * Returns: true on success or false on failure. In the latter case
 116  * errno will be set appropriately by the failing system primitive.
 117  */
 118 template <class Container>
 119 bool readFile(
 120     int fd,
 121     Container& out,
 122     size_t num_bytes = std::numeric_limits<size_t>::max()) {
 123   static_assert(sizeof(out[0]) == 1,
 124                 "readFile: only containers with byte-sized elements accepted");
 125
 126   size_t soFar = 0; // amount of bytes successfully read
 127   SCOPE_EXIT {
 128     DCHECK(out.size() >= soFar); // resize better doesn't throw
 129     out.resize(soFar);
 130   };
 131
 132   // Obtain file size:
 133   struct stat buf;
 134   if (fstat(fd, &buf) == -1) {
 135     return false;
 136   }
 137   // Some files (notably under /proc and /sys on Linux) lie about
 138   // their size, so treat the size advertised by fstat under advise
 139   // but don't rely on it. In particular, if the size is zero, we
 140   // should attempt to read stuff. If not zero, we'll attempt to read
 141   // one extra byte.
 142   constexpr size_t initialAlloc = 1024 * 4;
 143   out.resize(
 144     std::min(
 145       buf.st_size > 0 ? (size_t(buf.st_size) + 1) : initialAlloc, num_bytes));
 146
 147   while (soFar < out.size()) {
 148     const auto actual = readFull(fd, &out[soFar], out.size() - soFar);
 149     if (actual == -1) {
 150       return false;
 151     }
 152     soFar += actual;
 153     if (soFar < out.size()) {
 154       // File exhausted
 155       break;
 156     }
 157     // Ew, allocate more memory. Use exponential growth to avoid
 158     // quadratic behavior. Cap size to num_bytes.
 159     out.resize(std::min(out.size() * 3 / 2, num_bytes));
 160   }
 161
 162   return true;
 163 }
 164
 165 /**
 166  * Same as above, but takes in a file name instead of fd
 167  */
 168 template <class Container>
 169 bool readFile(
 170     const char* file_name,
 171     Container& out,
 172     size_t num_bytes = std::numeric_limits<size_t>::max()) {
 173   DCHECK(file_name);
 174
 175   const auto fd = openNoInt(file_name, O_RDONLY);
 176   if (fd == -1) {
 177     return false;
 178   }
 179
 180   SCOPE_EXIT {
 181     // Ignore errors when closing the file
 182     closeNoInt(fd);
 183   };
 184
 185   return readFile(fd, out, num_bytes);
 186 }
 187
 188 /**
 189  * Writes container to file. The container is assumed to be
 190  * contiguous, with element size equal to 1, and offering STL-like
 191  * methods empty(), size(), and indexed access
 192  * (e.g. std::vector<char>, std::string, fbstring, StringPiece).
 193  *
 194  * "flags" dictates the open flags to use. Default is to create file
 195  * if it doesn't exist and truncate it.
 196  *
 197  * Returns: true on success or false on failure. In the latter case
 198  * errno will be set appropriately by the failing system primitive.
 199  *
 200  * Note that this function may leave the file in a partially written state on
 201  * failure.  Use writeFileAtomic() if you want to ensure that the existing file
 202  * state will be unchanged on error.
 203  */
 204 template <class Container>
 205 bool writeFile(const Container& data,
 206                const char* filename,
 207                int flags = O_WRONLY | O_CREAT | O_TRUNC,
 208                mode_t mode = 0666) {
 209   static_assert(sizeof(data[0]) == 1,
 210                 "writeFile works with element size equal to 1");
 211   int fd = open(filename, flags, mode);
 212   if (fd == -1) {
 213     return false;
 214   }
 215   bool ok = data.empty() ||
 216     writeFull(fd, &data[0], data.size()) == static_cast<ssize_t>(data.size());
 217   return closeNoInt(fd) == 0 && ok;
 218 }
 219
 220 /**
 221  * Write file contents "atomically".
 222  *
 223  * This writes the data to a temporary file in the destination directory, and
 224  * then renames it to the specified path.  This guarantees that the specified
 225  * file will be replaced the the specified contents on success, or will not be
 226  * modified on failure.
 227  *
 228  * Note that on platforms that do not provide atomic filesystem rename
 229  * functionality (e.g., Windows) this behavior may not be truly atomic.
 230  */
 231 void writeFileAtomic(
 232     StringPiece filename,
 233     iovec* iov,
 234     int count,
 235     mode_t permissions = 0644);
 236 void writeFileAtomic(
 237     StringPiece filename,
 238     ByteRange data,
 239     mode_t permissions = 0644);
 240 void writeFileAtomic(
 241     StringPiece filename,
 242     StringPiece data,
 243     mode_t permissions = 0644);
 244
 245 /**
 246  * A version of writeFileAtomic() that returns an errno value instead of
 247  * throwing on error.
 248  *
 249  * Returns 0 on success or an errno value on error.
 250  */
 251 int writeFileAtomicNoThrow(
 252     StringPiece filename,
 253     iovec* iov,
 254     int count,
 255     mode_t permissions = 0644);
 256
 257 } // namespace folly