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