include/lldb/Host/File.h

   1 //===-- File.h --------------------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_File_h_
  11 #define liblldb_File_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 #include <stdarg.h>
  16 #include <stdio.h>
  17 #include <sys/types.h>
  18
  19 // Other libraries and framework includes
  20 // Project includes
  21 #include "lldb/Host/IOObject.h"
  22 #include "lldb/Host/PosixApi.h"
  23 #include "lldb/lldb-private.h"
  24
  25 namespace lldb_private {
  26
  27 //----------------------------------------------------------------------
  28 /// @class File File.h "lldb/Host/File.h"
  29 /// @brief A file class.
  30 ///
  31 /// A file class that divides abstracts the LLDB core from host file
  32 /// functionality.
  33 //----------------------------------------------------------------------
  34 class File : public IOObject {
  35 public:
  36   static int kInvalidDescriptor;
  37   static FILE *kInvalidStream;
  38
  39   enum OpenOptions {
  40     eOpenOptionRead = (1u << 0),  // Open file for reading
  41     eOpenOptionWrite = (1u << 1), // Open file for writing
  42     eOpenOptionAppend =
  43         (1u << 2), // Don't truncate file when opening, append to end of file
  44     eOpenOptionTruncate = (1u << 3),    // Truncate file when opening
  45     eOpenOptionNonBlocking = (1u << 4), // File reads
  46     eOpenOptionCanCreate = (1u << 5),   // Create file if doesn't already exist
  47     eOpenOptionCanCreateNewOnly =
  48         (1u << 6), // Can create file only if it doesn't already exist
  49     eOpenOptionDontFollowSymlinks = (1u << 7),
  50     eOpenOptionCloseOnExec =
  51         (1u << 8) // Close the file when executing a new process
  52   };
  53
  54   static mode_t ConvertOpenOptionsForPOSIXOpen(uint32_t open_options);
  55
  56   File()
  57       : IOObject(eFDTypeFile, false), m_descriptor(kInvalidDescriptor),
  58         m_stream(kInvalidStream), m_options(0), m_own_stream(false),
  59         m_is_interactive(eLazyBoolCalculate),
  60         m_is_real_terminal(eLazyBoolCalculate) {}
  61
  62   File(FILE *fh, bool transfer_ownership)
  63       : IOObject(eFDTypeFile, false), m_descriptor(kInvalidDescriptor),
  64         m_stream(fh), m_options(0), m_own_stream(transfer_ownership),
  65         m_is_interactive(eLazyBoolCalculate),
  66         m_is_real_terminal(eLazyBoolCalculate) {}
  67
  68   //------------------------------------------------------------------
  69   /// Constructor with path.
  70   ///
  71   /// Takes a path to a file which can be just a filename, or a full
  72   /// path. If \a path is not nullptr or empty, this function will call
  73   /// File::Open (const char *path, uint32_t options, uint32_t permissions).
  74   ///
  75   /// @param[in] path
  76   ///     The full or partial path to a file.
  77   ///
  78   /// @param[in] options
  79   ///     Options to use when opening (see File::OpenOptions)
  80   ///
  81   /// @param[in] permissions
  82   ///     Options to use when opening (see File::Permissions)
  83   ///
  84   /// @see File::Open (const char *path, uint32_t options, uint32_t permissions)
  85   //------------------------------------------------------------------
  86   File(const char *path, uint32_t options,
  87        uint32_t permissions = lldb::eFilePermissionsFileDefault);
  88
  89   //------------------------------------------------------------------
  90   /// Constructor with FileSpec.
  91   ///
  92   /// Takes a FileSpec pointing to a file which can be just a filename, or a
  93   /// full
  94   /// path. If \a path is not nullptr or empty, this function will call
  95   /// File::Open (const char *path, uint32_t options, uint32_t permissions).
  96   ///
  97   /// @param[in] filespec
  98   ///     The FileSpec for this file.
  99   ///
 100   /// @param[in] options
 101   ///     Options to use when opening (see File::OpenOptions)
 102   ///
 103   /// @param[in] permissions
 104   ///     Options to use when opening (see File::Permissions)
 105   ///
 106   /// @see File::Open (const char *path, uint32_t options, uint32_t permissions)
 107   //------------------------------------------------------------------
 108   File(const FileSpec &filespec, uint32_t options,
 109        uint32_t permissions = lldb::eFilePermissionsFileDefault);
 110
 111   File(int fd, bool transfer_ownership)
 112       : IOObject(eFDTypeFile, transfer_ownership), m_descriptor(fd),
 113         m_stream(kInvalidStream), m_options(0), m_own_stream(false),
 114         m_is_interactive(eLazyBoolCalculate),
 115         m_is_real_terminal(eLazyBoolCalculate) {}
 116
 117   //------------------------------------------------------------------
 118   /// Destructor.
 119   ///
 120   /// The destructor is virtual in case this class is subclassed.
 121   //------------------------------------------------------------------
 122   ~File() override;
 123
 124   bool IsValid() const override {
 125     return DescriptorIsValid() || StreamIsValid();
 126   }
 127
 128   //------------------------------------------------------------------
 129   /// Convert to pointer operator.
 130   ///
 131   /// This allows code to check a File object to see if it
 132   /// contains anything valid using code such as:
 133   ///
 134   /// @code
 135   /// File file(...);
 136   /// if (file)
 137   /// { ...
 138   /// @endcode
 139   ///
 140   /// @return
 141   ///     A pointer to this object if either the directory or filename
 142   ///     is valid, nullptr otherwise.
 143   //------------------------------------------------------------------
 144   operator bool() const { return DescriptorIsValid() || StreamIsValid(); }
 145
 146   //------------------------------------------------------------------
 147   /// Logical NOT operator.
 148   ///
 149   /// This allows code to check a File object to see if it is
 150   /// invalid using code such as:
 151   ///
 152   /// @code
 153   /// File file(...);
 154   /// if (!file)
 155   /// { ...
 156   /// @endcode
 157   ///
 158   /// @return
 159   ///     Returns \b true if the object has an empty directory and
 160   ///     filename, \b false otherwise.
 161   //------------------------------------------------------------------
 162   bool operator!() const { return !DescriptorIsValid() && !StreamIsValid(); }
 163
 164   //------------------------------------------------------------------
 165   /// Get the file spec for this file.
 166   ///
 167   /// @return
 168   ///     A reference to the file specification object.
 169   //------------------------------------------------------------------
 170   Error GetFileSpec(FileSpec &file_spec) const;
 171
 172   //------------------------------------------------------------------
 173   /// Open a file for read/writing with the specified options.
 174   ///
 175   /// Takes a path to a file which can be just a filename, or a full
 176   /// path.
 177   ///
 178   /// @param[in] path
 179   ///     The full or partial path to a file.
 180   ///
 181   /// @param[in] options
 182   ///     Options to use when opening (see File::OpenOptions)
 183   ///
 184   /// @param[in] permissions
 185   ///     Options to use when opening (see File::Permissions)
 186   //------------------------------------------------------------------
 187   Error Open(const char *path, uint32_t options,
 188              uint32_t permissions = lldb::eFilePermissionsFileDefault);
 189
 190   Error Close() override;
 191
 192   void Clear();
 193
 194   int GetDescriptor() const;
 195
 196   WaitableHandle GetWaitableHandle() override;
 197
 198   void SetDescriptor(int fd, bool transfer_ownership);
 199
 200   FILE *GetStream();
 201
 202   void SetStream(FILE *fh, bool transfer_ownership);
 203
 204   //------------------------------------------------------------------
 205   /// Read bytes from a file from the current file position.
 206   ///
 207   /// NOTE: This function is NOT thread safe. Use the read function
 208   /// that takes an "off_t &offset" to ensure correct operation in
 209   /// multi-threaded environments.
 210   ///
 211   /// @param[in] buf
 212   ///     A buffer where to put the bytes that are read.
 213   ///
 214   /// @param[in,out] num_bytes
 215   ///     The number of bytes to read form the current file position
 216   ///     which gets modified with the number of bytes that were read.
 217   ///
 218   /// @return
 219   ///     An error object that indicates success or the reason for
 220   ///     failure.
 221   //------------------------------------------------------------------
 222   Error Read(void *buf, size_t &num_bytes) override;
 223
 224   //------------------------------------------------------------------
 225   /// Write bytes to a file at the current file position.
 226   ///
 227   /// NOTE: This function is NOT thread safe. Use the write function
 228   /// that takes an "off_t &offset" to ensure correct operation in
 229   /// multi-threaded environments.
 230   ///
 231   /// @param[in] buf
 232   ///     A buffer where to put the bytes that are read.
 233   ///
 234   /// @param[in,out] num_bytes
 235   ///     The number of bytes to write to the current file position
 236   ///     which gets modified with the number of bytes that were
 237   ///     written.
 238   ///
 239   /// @return
 240   ///     An error object that indicates success or the reason for
 241   ///     failure.
 242   //------------------------------------------------------------------
 243   Error Write(const void *buf, size_t &num_bytes) override;
 244
 245   //------------------------------------------------------------------
 246   /// Seek to an offset relative to the beginning of the file.
 247   ///
 248   /// NOTE: This function is NOT thread safe, other threads that
 249   /// access this object might also change the current file position.
 250   /// For thread safe reads and writes see the following functions:
 251   /// @see File::Read (void *, size_t, off_t &)
 252   /// @see File::Write (const void *, size_t, off_t &)
 253   ///
 254   /// @param[in] offset
 255   ///     The offset to seek to within the file relative to the
 256   ///     beginning of the file.
 257   ///
 258   /// @param[in] error_ptr
 259   ///     A pointer to a lldb_private::Error object that will be
 260   ///     filled in if non-nullptr.
 261   ///
 262   /// @return
 263   ///     The resulting seek offset, or -1 on error.
 264   //------------------------------------------------------------------
 265   off_t SeekFromStart(off_t offset, Error *error_ptr = nullptr);
 266
 267   //------------------------------------------------------------------
 268   /// Seek to an offset relative to the current file position.
 269   ///
 270   /// NOTE: This function is NOT thread safe, other threads that
 271   /// access this object might also change the current file position.
 272   /// For thread safe reads and writes see the following functions:
 273   /// @see File::Read (void *, size_t, off_t &)
 274   /// @see File::Write (const void *, size_t, off_t &)
 275   ///
 276   /// @param[in] offset
 277   ///     The offset to seek to within the file relative to the
 278   ///     current file position.
 279   ///
 280   /// @param[in] error_ptr
 281   ///     A pointer to a lldb_private::Error object that will be
 282   ///     filled in if non-nullptr.
 283   ///
 284   /// @return
 285   ///     The resulting seek offset, or -1 on error.
 286   //------------------------------------------------------------------
 287   off_t SeekFromCurrent(off_t offset, Error *error_ptr = nullptr);
 288
 289   //------------------------------------------------------------------
 290   /// Seek to an offset relative to the end of the file.
 291   ///
 292   /// NOTE: This function is NOT thread safe, other threads that
 293   /// access this object might also change the current file position.
 294   /// For thread safe reads and writes see the following functions:
 295   /// @see File::Read (void *, size_t, off_t &)
 296   /// @see File::Write (const void *, size_t, off_t &)
 297   ///
 298   /// @param[in,out] offset
 299   ///     The offset to seek to within the file relative to the
 300   ///     end of the file which gets filled in with the resulting
 301   ///     absolute file offset.
 302   ///
 303   /// @param[in] error_ptr
 304   ///     A pointer to a lldb_private::Error object that will be
 305   ///     filled in if non-nullptr.
 306   ///
 307   /// @return
 308   ///     The resulting seek offset, or -1 on error.
 309   //------------------------------------------------------------------
 310   off_t SeekFromEnd(off_t offset, Error *error_ptr = nullptr);
 311
 312   //------------------------------------------------------------------
 313   /// Read bytes from a file from the specified file offset.
 314   ///
 315   /// NOTE: This function is thread safe in that clients manager their
 316   /// own file position markers and reads on other threads won't mess
 317   /// up the current read.
 318   ///
 319   /// @param[in] dst
 320   ///     A buffer where to put the bytes that are read.
 321   ///
 322   /// @param[in,out] num_bytes
 323   ///     The number of bytes to read form the current file position
 324   ///     which gets modified with the number of bytes that were read.
 325   ///
 326   /// @param[in,out] offset
 327   ///     The offset within the file from which to read \a num_bytes
 328   ///     bytes. This offset gets incremented by the number of bytes
 329   ///     that were read.
 330   ///
 331   /// @return
 332   ///     An error object that indicates success or the reason for
 333   ///     failure.
 334   //------------------------------------------------------------------
 335   Error Read(void *dst, size_t &num_bytes, off_t &offset);
 336
 337   //------------------------------------------------------------------
 338   /// Read bytes from a file from the specified file offset.
 339   ///
 340   /// NOTE: This function is thread safe in that clients manager their
 341   /// own file position markers and reads on other threads won't mess
 342   /// up the current read.
 343   ///
 344   /// @param[in,out] num_bytes
 345   ///     The number of bytes to read form the current file position
 346   ///     which gets modified with the number of bytes that were read.
 347   ///
 348   /// @param[in,out] offset
 349   ///     The offset within the file from which to read \a num_bytes
 350   ///     bytes. This offset gets incremented by the number of bytes
 351   ///     that were read.
 352   ///
 353   /// @param[in] null_terminate
 354   ///     Ensure that the data that is read is terminated with a NULL
 355   ///     character so that the data can be used as a C string.
 356   ///
 357   /// @param[out] data_buffer_sp
 358   ///     A data buffer to create and fill in that will contain any
 359   ///     data that is read from the file. This buffer will be reset
 360   ///     if an error occurs.
 361   ///
 362   /// @return
 363   ///     An error object that indicates success or the reason for
 364   ///     failure.
 365   //------------------------------------------------------------------
 366   Error Read(size_t &num_bytes, off_t &offset, bool null_terminate,
 367              lldb::DataBufferSP &data_buffer_sp);
 368
 369   //------------------------------------------------------------------
 370   /// Write bytes to a file at the specified file offset.
 371   ///
 372   /// NOTE: This function is thread safe in that clients manager their
 373   /// own file position markers, though clients will need to implement
 374   /// their own locking externally to avoid multiple people writing
 375   /// to the file at the same time.
 376   ///
 377   /// @param[in] src
 378   ///     A buffer containing the bytes to write.
 379   ///
 380   /// @param[in,out] num_bytes
 381   ///     The number of bytes to write to the file at offset \a offset.
 382   ///     \a num_bytes gets modified with the number of bytes that
 383   ///     were read.
 384   ///
 385   /// @param[in,out] offset
 386   ///     The offset within the file at which to write \a num_bytes
 387   ///     bytes. This offset gets incremented by the number of bytes
 388   ///     that were written.
 389   ///
 390   /// @return
 391   ///     An error object that indicates success or the reason for
 392   ///     failure.
 393   //------------------------------------------------------------------
 394   Error Write(const void *src, size_t &num_bytes, off_t &offset);
 395
 396   //------------------------------------------------------------------
 397   /// Flush the current stream
 398   ///
 399   /// @return
 400   ///     An error object that indicates success or the reason for
 401   ///     failure.
 402   //------------------------------------------------------------------
 403   Error Flush();
 404
 405   //------------------------------------------------------------------
 406   /// Sync to disk.
 407   ///
 408   /// @return
 409   ///     An error object that indicates success or the reason for
 410   ///     failure.
 411   //------------------------------------------------------------------
 412   Error Sync();
 413
 414   //------------------------------------------------------------------
 415   /// Get the permissions for a this file.
 416   ///
 417   /// @return
 418   ///     Bits logical OR'ed together from the permission bits defined
 419   ///     in lldb_private::File::Permissions.
 420   //------------------------------------------------------------------
 421   uint32_t GetPermissions(Error &error) const;
 422
 423   static uint32_t GetPermissions(const FileSpec &file_spec, Error &error);
 424
 425   //------------------------------------------------------------------
 426   /// Return true if this file is interactive.
 427   ///
 428   /// @return
 429   ///     True if this file is a terminal (tty or pty), false
 430   ///     otherwise.
 431   //------------------------------------------------------------------
 432   bool GetIsInteractive();
 433
 434   //------------------------------------------------------------------
 435   /// Return true if this file from a real terminal.
 436   ///
 437   /// Just knowing a file is a interactive isn't enough, we also need
 438   /// to know if the terminal has a width and height so we can do
 439   /// cursor movement and other terminal manipulations by sending
 440   /// escape sequences.
 441   ///
 442   /// @return
 443   ///     True if this file is a terminal (tty, not a pty) that has
 444   ///     a non-zero width and height, false otherwise.
 445   //------------------------------------------------------------------
 446   bool GetIsRealTerminal();
 447
 448   bool GetIsTerminalWithColors();
 449
 450   //------------------------------------------------------------------
 451   /// Output printf formatted output to the stream.
 452   ///
 453   /// Print some formatted output to the stream.
 454   ///
 455   /// @param[in] format
 456   ///     A printf style format string.
 457   ///
 458   /// @param[in] ...
 459   ///     Variable arguments that are needed for the printf style
 460   ///     format string \a format.
 461   //------------------------------------------------------------------
 462   size_t Printf(const char *format, ...) __attribute__((format(printf, 2, 3)));
 463
 464   size_t PrintfVarArg(const char *format, va_list args);
 465
 466   void SetOptions(uint32_t options) { m_options = options; }
 467
 468 protected:
 469   bool DescriptorIsValid() const { return m_descriptor >= 0; }
 470
 471   bool StreamIsValid() const { return m_stream != kInvalidStream; }
 472
 473   void CalculateInteractiveAndTerminal();
 474
 475   //------------------------------------------------------------------
 476   // Member variables
 477   //------------------------------------------------------------------
 478   int m_descriptor;
 479   FILE *m_stream;
 480   uint32_t m_options;
 481   bool m_own_stream;
 482   LazyBool m_is_interactive;
 483   LazyBool m_is_real_terminal;
 484   LazyBool m_supports_colors;
 485
 486 private:
 487   DISALLOW_COPY_AND_ASSIGN(File);
 488 };
 489
 490 } // namespace lldb_private
 491
 492 #endif // liblldb_File_h_