folly/File.h

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