folly/File.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 <fcntl.h>
  20 #include <sys/stat.h>
  21 #include <sys/types.h>
  22
  23 #include <string>
  24 #include <system_error>
  25
  26 #include <folly/ExceptionWrapper.h>
  27 #include <folly/Expected.h>
  28 #include <folly/Portability.h>
  29 #include <folly/Range.h>
  30 #include <folly/portability/Unistd.h>
  31
  32 namespace folly {
  33
  34 /**
  35  * A File represents an open file.
  36  */
  37 class File {
  38  public:
  39   /**
  40    * Creates an empty File object, for late initialization.
  41    */
  42   File() noexcept;
  43
  44   /**
  45    * Create a File object from an existing file descriptor.
  46    * Takes ownership of the file descriptor if ownsFd is true.
  47    */
  48   explicit File(int fd, bool ownsFd = false) noexcept;
  49
  50   /**
  51    * Open and create a file object.  Throws on error.
  52    * Owns the file descriptor implicitly.
  53    */
  54   explicit File(const char* name, int flags = O_RDONLY, mode_t mode = 0666);
  55   explicit File(
  56       const std::string& name, int flags = O_RDONLY, mode_t mode = 0666);
  57   explicit File(StringPiece name, int flags = O_RDONLY, mode_t mode = 0666);
  58
  59   /**
  60    * All the constructors that are not noexcept can throw std::system_error.
  61    * This is a helper method to use folly::Expected to chain a file open event
  62    * to something else you want to do with the open fd.
  63    */
  64   template <typename... Args>
  65   static Expected<File, exception_wrapper> makeFile(Args&&... args) noexcept {
  66     try {
  67       return File(std::forward<Args>(args)...);
  68     } catch (const std::system_error& se) {
  69       return makeUnexpected(exception_wrapper(std::current_exception(), se));
  70     }
  71   }
  72
  73   ~File();
  74
  75   /**
  76    * Create and return a temporary, owned file (uses tmpfile()).
  77    */
  78   static File temporary();
  79
  80   /**
  81    * Return the file descriptor, or -1 if the file was closed.
  82    */
  83   int fd() const { return fd_; }
  84
  85   /**
  86    * Returns 'true' iff the file was successfully opened.
  87    */
  88   explicit operator bool() const {
  89     return fd_ != -1;
  90   }
  91
  92   /**
  93    * Duplicate file descriptor and return File that owns it.
  94    */
  95   File dup() const;
  96
  97   /**
  98    * If we own the file descriptor, close the file and throw on error.
  99    * Otherwise, do nothing.
 100    */
 101   void close();
 102
 103   /**
 104    * Closes the file (if owned).  Returns true on success, false (and sets
 105    * errno) on error.
 106    */
 107   bool closeNoThrow();
 108
 109   /**
 110    * Returns and releases the file descriptor; no longer owned by this File.
 111    * Returns -1 if the File object didn't wrap a file.
 112    */
 113   int release() noexcept;
 114
 115   /**
 116    * Swap this File with another.
 117    */
 118   void swap(File& other);
 119
 120   // movable
 121   File(File&&) noexcept;
 122   File& operator=(File&&);
 123
 124   // FLOCK (INTERPROCESS) LOCKS
 125   //
 126   // NOTE THAT THESE LOCKS ARE flock() LOCKS.  That is, they may only be used
 127   // for inter-process synchronization -- an attempt to acquire a second lock
 128   // on the same file descriptor from the same process may succeed.  Attempting
 129   // to acquire a second lock on a different file descriptor for the same file
 130   // should fail, but some systems might implement flock() using fcntl() locks,
 131   // in which case it will succeed.
 132   void lock();
 133   bool try_lock();
 134   void unlock();
 135
 136   void lock_shared();
 137   bool try_lock_shared();
 138   void unlock_shared();
 139
 140  private:
 141   void doLock(int op);
 142   bool doTryLock(int op);
 143
 144   // unique
 145   File(const File&) = delete;
 146   File& operator=(const File&) = delete;
 147
 148   int fd_;
 149   bool ownsFd_;
 150 };
 151
 152 void swap(File& a, File& b);
 153
 154 } // namespace folly