folly/File.h

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