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 File()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 File(FILE * fh,bool transfer_ownership)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 File(int fd,bool transfer_ownership)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 IsValid()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 SetOptions(uint32_t options)521 SetOptions (uint32_t options) 522 { 523 m_options = options; 524 } 525 protected: 526 527 528 bool DescriptorIsValid()529 DescriptorIsValid () const 530 { 531 return m_descriptor >= 0; 532 } 533 534 bool StreamIsValid()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_ 558