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