add makeSystemError*() helper functions

[folly.git] / folly / FileUtil.h

diff --git a/folly/FileUtil.h b/folly/FileUtil.h
index 0c23cd96a3377d300bb3698185375971b0e4bfa7..0913b23d2385510a86928ee2e347e0b3d767df0f 100644 (file)
--- a/folly/FileUtil.h
+++ b/folly/FileUtil.h
@@ -1,5 +1,5 @@
 /*
- * Copyright 2016 Facebook, Inc.
+ * Copyright 2017 Facebook, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,18 +16,19 @@
 
 #pragma once
 
-#include <folly/Conv.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+
+#include <cassert>
+#include <limits>
+
 #include <folly/Portability.h>
+#include <folly/Range.h>
 #include <folly/ScopeGuard.h>
 #include <folly/portability/Fcntl.h>
 #include <folly/portability/SysUio.h>
 #include <folly/portability/Unistd.h>
 
-#include <cassert>
-#include <limits>
-#include <sys/stat.h>
-#include <sys/types.h>
-
 namespace folly {
 
 /**
@@ -95,6 +96,9 @@ ssize_t preadvFull(int fd, iovec* iov, int count, off_t offset);
  * Note that writevFull and pwritevFull require iov to be non-const, unlike
  * writev and pwritev.  The contents of iov after these functions return
  * is unspecified.
+ *
+ * These functions return -1 on error, or the total number of bytes written
+ * (which is always the same as the number of requested bytes) on success.
  */
 ssize_t writeFull(int fd, const void* buf, size_t n);
 ssize_t pwriteFull(int fd, const void* buf, size_t n, off_t offset);
@@ -127,7 +131,9 @@ bool readFile(
 
   // Obtain file size:
   struct stat buf;
-  if (fstat(fd, &buf) == -1) return false;
+  if (fstat(fd, &buf) == -1) {
+    return false;
+  }
   // Some files (notably under /proc and /sys on Linux) lie about
   // their size, so treat the size advertised by fstat under advise
   // but don't rely on it. In particular, if the size is zero, we
@@ -136,8 +142,7 @@ bool readFile(
   constexpr size_t initialAlloc = 1024 * 4;
   out.resize(
     std::min(
-      buf.st_size > 0 ? folly::to<size_t>(buf.st_size + 1) : initialAlloc,
-      num_bytes));
+      buf.st_size > 0 ? (size_t(buf.st_size) + 1) : initialAlloc, num_bytes));
 
   while (soFar < out.size()) {
     const auto actual = readFull(fd, &out[soFar], out.size() - soFar);
@@ -191,13 +196,19 @@ bool readFile(
  *
  * Returns: true on success or false on failure. In the latter case
  * errno will be set appropriately by the failing system primitive.
+ *
+ * Note that this function may leave the file in a partially written state on
+ * failure.  Use writeFileAtomic() if you want to ensure that the existing file
+ * state will be unchanged on error.
  */
 template <class Container>
-bool writeFile(const Container& data, const char* filename,
-              int flags = O_WRONLY | O_CREAT | O_TRUNC) {
+bool writeFile(const Container& data,
+               const char* filename,
+               int flags = O_WRONLY | O_CREAT | O_TRUNC,
+               mode_t mode = 0666) {
   static_assert(sizeof(data[0]) == 1,
                 "writeFile works with element size equal to 1");
-  int fd = open(filename, flags, 0666);
+  int fd = open(filename, flags, mode);
   if (fd == -1) {
     return false;
   }
@@ -206,4 +217,41 @@ bool writeFile(const Container& data, const char* filename,
   return closeNoInt(fd) == 0 && ok;
 }
 
-}  // namespaces
+/**
+ * Write file contents "atomically".
+ *
+ * This writes the data to a temporary file in the destination directory, and
+ * then renames it to the specified path.  This guarantees that the specified
+ * file will be replaced the the specified contents on success, or will not be
+ * modified on failure.
+ *
+ * Note that on platforms that do not provide atomic filesystem rename
+ * functionality (e.g., Windows) this behavior may not be truly atomic.
+ */
+void writeFileAtomic(
+    StringPiece filename,
+    iovec* iov,
+    int count,
+    mode_t permissions = 0644);
+void writeFileAtomic(
+    StringPiece filename,
+    ByteRange data,
+    mode_t permissions = 0644);
+void writeFileAtomic(
+    StringPiece filename,
+    StringPiece data,
+    mode_t permissions = 0644);
+
+/**
+ * A version of writeFileAtomic() that returns an errno value instead of
+ * throwing on error.
+ *
+ * Returns 0 on success or an errno value on error.
+ */
+int writeFileAtomicNoThrow(
+    StringPiece filename,
+    iovec* iov,
+    int count,
+    mode_t permissions = 0644);
+
+} // namespace folly