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