FileSpec.h revision 82cfaed47126a17b4fa21e42e05546e7a041b9e3
1//===-- FileSpec.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_FileSpec_h_ 11#define liblldb_FileSpec_h_ 12#if defined(__cplusplus) 13 14#include "lldb/lldb-private.h" 15#include "lldb/Core/ConstString.h" 16#include "lldb/Core/STLUtils.h" 17#include "lldb/Host/TimeValue.h" 18 19namespace lldb_private { 20 21//---------------------------------------------------------------------- 22/// @class FileSpec FileSpec.h "lldb/Host/FileSpec.h" 23/// @brief A file utility class. 24/// 25/// A file specification class that divides paths up into a directory 26/// and basename. These string values of the paths are put into uniqued 27/// string pools for fast comparisons and efficient memory usage. 28/// 29/// Another reason the paths are split into the directory and basename 30/// is to allow efficient debugger searching. Often in a debugger the 31/// user types in the basename of the file, for example setting a 32/// breakpoint by file and line, or specifying a module (shared library) 33/// to limit the scope in which to execute a command. The user rarely 34/// types in a full path. When the paths are already split up, it makes 35/// it easy for us to compare only the basenames of a lot of file 36/// specifications without having to split up the file path each time 37/// to get to the basename. 38//---------------------------------------------------------------------- 39class FileSpec 40{ 41public: 42 typedef enum FileType 43 { 44 eFileTypeInvalid = -1, 45 eFileTypeUnknown = 0, 46 eFileTypeDirectory, 47 eFileTypePipe, 48 eFileTypeRegular, 49 eFileTypeSocket, 50 eFileTypeSymbolicLink, 51 eFileTypeOther 52 } FileType; 53 54 FileSpec(); 55 56 //------------------------------------------------------------------ 57 /// Constructor with path. 58 /// 59 /// Takes a path to a file which can be just a filename, or a full 60 /// path. If \a path is not NULL or empty, this function will call 61 /// FileSpec::SetFile (const char *path, bool resolve). 62 /// 63 /// @param[in] path 64 /// The full or partial path to a file. 65 /// 66 /// @param[in] resolve_path 67 /// If \b true, then we resolve the path with realpath, 68 /// if \b false we trust the path is in canonical form already. 69 /// 70 /// @see FileSpec::SetFile (const char *path, bool resolve) 71 //------------------------------------------------------------------ 72 explicit FileSpec (const char *path, bool resolve_path); 73 74 //------------------------------------------------------------------ 75 /// Copy constructor 76 /// 77 /// Makes a copy of the uniqued directory and filename strings from 78 /// \a rhs. 79 /// 80 /// @param[in] rhs 81 /// A const FileSpec object reference to copy. 82 //------------------------------------------------------------------ 83 FileSpec (const FileSpec& rhs); 84 85 //------------------------------------------------------------------ 86 /// Copy constructor 87 /// 88 /// Makes a copy of the uniqued directory and filename strings from 89 /// \a rhs if it is not NULL. 90 /// 91 /// @param[in] rhs 92 /// A const FileSpec object pointer to copy if non-NULL. 93 //------------------------------------------------------------------ 94 FileSpec (const FileSpec* rhs); 95 96 //------------------------------------------------------------------ 97 /// Destructor. 98 /// 99 /// The destructor is virtual in case this class is subclassed. 100 //------------------------------------------------------------------ 101 virtual 102 ~FileSpec (); 103 104 //------------------------------------------------------------------ 105 /// Assignment operator. 106 /// 107 /// Makes a copy of the uniqued directory and filename strings from 108 /// \a rhs. 109 /// 110 /// @param[in] rhs 111 /// A const FileSpec object reference to assign to this object. 112 /// 113 /// @return 114 /// A const reference to this object. 115 //------------------------------------------------------------------ 116 const FileSpec& 117 operator= (const FileSpec& rhs); 118 119 //------------------------------------------------------------------ 120 /// Equal to operator 121 /// 122 /// Tests if this object is equal to \a rhs. 123 /// 124 /// @param[in] rhs 125 /// A const FileSpec object reference to compare this object 126 /// to. 127 /// 128 /// @return 129 /// \b true if this object is equal to \a rhs, \b false 130 /// otherwise. 131 //------------------------------------------------------------------ 132 bool 133 operator== (const FileSpec& rhs) const; 134 135 //------------------------------------------------------------------ 136 /// Not equal to operator 137 /// 138 /// Tests if this object is not equal to \a rhs. 139 /// 140 /// @param[in] rhs 141 /// A const FileSpec object reference to compare this object 142 /// to. 143 /// 144 /// @return 145 /// \b true if this object is equal to \a rhs, \b false 146 /// otherwise. 147 //------------------------------------------------------------------ 148 bool 149 operator!= (const FileSpec& rhs) const; 150 151 //------------------------------------------------------------------ 152 /// Less than to operator 153 /// 154 /// Tests if this object is less than \a rhs. 155 /// 156 /// @param[in] rhs 157 /// A const FileSpec object reference to compare this object 158 /// to. 159 /// 160 /// @return 161 /// \b true if this object is less than \a rhs, \b false 162 /// otherwise. 163 //------------------------------------------------------------------ 164 bool 165 operator< (const FileSpec& rhs) const; 166 167 //------------------------------------------------------------------ 168 /// Convert to pointer operator. 169 /// 170 /// This allows code to check a FileSpec object to see if it 171 /// contains anything valid using code such as: 172 /// 173 /// @code 174 /// FileSpec file_spec(...); 175 /// if (file_spec) 176 /// { ... 177 /// @endcode 178 /// 179 /// @return 180 /// A pointer to this object if either the directory or filename 181 /// is valid, NULL otherwise. 182 //------------------------------------------------------------------ 183 operator 184 void* () const; 185 186 //------------------------------------------------------------------ 187 /// Logical NOT operator. 188 /// 189 /// This allows code to check a FileSpec object to see if it is 190 /// invalid using code such as: 191 /// 192 /// @code 193 /// FileSpec file_spec(...); 194 /// if (!file_spec) 195 /// { ... 196 /// @endcode 197 /// 198 /// @return 199 /// Returns \b true if the object has an empty directory and 200 /// filename, \b false otherwise. 201 //------------------------------------------------------------------ 202 bool 203 operator! () const; 204 205 //------------------------------------------------------------------ 206 /// Clears the object state. 207 /// 208 /// Clear this object by releasing both the directory and filename 209 /// string values and reverting them to empty strings. 210 //------------------------------------------------------------------ 211 void 212 Clear (); 213 214 //------------------------------------------------------------------ 215 /// Compare two FileSpec objects. 216 /// 217 /// If \a full is true, then both the directory and the filename 218 /// must match. If \a full is false, then the directory names for 219 /// \a lhs and \a rhs are only compared if they are both not empty. 220 /// This allows a FileSpec object to only contain a filename 221 /// and it can match FileSpec objects that have matching 222 /// filenames with different paths. 223 /// 224 /// @param[in] lhs 225 /// A const reference to the Left Hand Side object to compare. 226 /// 227 /// @param[in] rhs 228 /// A const reference to the Right Hand Side object to compare. 229 /// 230 /// @param[in] full 231 /// If true, then both the directory and filenames will have to 232 /// match for a compare to return zero (equal to). If false 233 /// and either directory from \a lhs or \a rhs is empty, then 234 /// only the filename will be compared, else a full comparison 235 /// is done. 236 /// 237 /// @return 238 /// @li -1 if \a lhs is less than \a rhs 239 /// @li 0 if \a lhs is equal to \a rhs 240 /// @li 1 if \a lhs is greater than \a rhs 241 //------------------------------------------------------------------ 242 static int 243 Compare (const FileSpec& lhs, const FileSpec& rhs, bool full); 244 245 static bool 246 Equal (const FileSpec& a, const FileSpec& b, bool full); 247 248 //------------------------------------------------------------------ 249 /// Dump this object to a Stream. 250 /// 251 /// Dump the object to the supplied stream \a s. If the object 252 /// contains a valid directory name, it will be displayed followed 253 /// by a directory delimiter, and the filename. 254 /// 255 /// @param[in] s 256 /// The stream to which to dump the object descripton. 257 //------------------------------------------------------------------ 258 void 259 Dump (Stream *s) const; 260 261 //------------------------------------------------------------------ 262 /// Existence test. 263 /// 264 /// @return 265 /// \b true if the file exists on disk, \b false otherwise. 266 //------------------------------------------------------------------ 267 bool 268 Exists () const; 269 270 271 //------------------------------------------------------------------ 272 /// Expanded existence test. 273 /// 274 /// Call into the Host to see if it can help find the file (e.g. by 275 /// searching paths set in the environment, etc.). 276 /// 277 /// If found, sets the value of m_directory to the directory where 278 /// the file was found. 279 /// 280 /// @return 281 /// \b true if was able to find the file using expanded search 282 /// methods, \b false otherwise. 283 //------------------------------------------------------------------ 284 bool 285 ResolveExecutableLocation (); 286 287 //------------------------------------------------------------------ 288 /// Canonicalize this file path (basically running the static 289 /// FileSpec::Resolve method on it). Useful if you asked us not to 290 /// resolve the file path when you set the file. 291 //------------------------------------------------------------------ 292 bool 293 ResolvePath (); 294 295 uint64_t 296 GetByteSize() const; 297 298 //------------------------------------------------------------------ 299 /// Directory string get accessor. 300 /// 301 /// @return 302 /// A reference to the directory string object. 303 //------------------------------------------------------------------ 304 ConstString & 305 GetDirectory (); 306 307 //------------------------------------------------------------------ 308 /// Directory string const get accessor. 309 /// 310 /// @return 311 /// A const reference to the directory string object. 312 //------------------------------------------------------------------ 313 const ConstString & 314 GetDirectory () const; 315 316 //------------------------------------------------------------------ 317 /// Filename string get accessor. 318 /// 319 /// @return 320 /// A reference to the filename string object. 321 //------------------------------------------------------------------ 322 ConstString & 323 GetFilename (); 324 325 //------------------------------------------------------------------ 326 /// Filename string const get accessor. 327 /// 328 /// @return 329 /// A const reference to the filename string object. 330 //------------------------------------------------------------------ 331 const ConstString & 332 GetFilename () const; 333 334 TimeValue 335 GetModificationTime () const; 336 337 //------------------------------------------------------------------ 338 /// Extract the full path to the file. 339 /// 340 /// Extract the directory and path into a fixed buffer. This is 341 /// needed as the directory and path are stored in separate string 342 /// values. 343 /// 344 /// @param[out] path 345 /// The buffer in which to place the extracted full path. 346 /// 347 /// @param[in] max_path_length 348 /// The maximum length or \a path. 349 /// 350 /// @return 351 /// Returns the number of characters that would be needed to 352 /// properly copy the full path into \a path. If the returned 353 /// number is less than \a max_path_length, then the path is 354 /// properly copied and terminated. If the return value is 355 /// >= \a max_path_length, then the path was truncated (but is 356 /// still NULL terminated). 357 //------------------------------------------------------------------ 358 size_t 359 GetPath (char *path, size_t max_path_length) const; 360 361 FileType 362 GetFileType () const; 363 364 //------------------------------------------------------------------ 365 /// Get the memory cost of this object. 366 /// 367 /// Return the size in bytes that this object takes in memory. This 368 /// returns the size in bytes of this object, not any shared string 369 /// values it may refer to. 370 /// 371 /// @return 372 /// The number of bytes that this object occupies in memory. 373 /// 374 /// @see ConstString::StaticMemorySize () 375 //------------------------------------------------------------------ 376 size_t 377 MemorySize () const; 378 379 //------------------------------------------------------------------ 380 /// Memory map part of, or the entire contents of, a file. 381 /// 382 /// Returns a shared pointer to a data buffer that contains all or 383 /// part of the contents of a file. The data is memory mapped and 384 /// will lazily page in data from the file as memory is accessed. 385 /// The data that is mappped will start \a offset bytes into the 386 /// file, and \a length bytes will be mapped. If \a length is 387 /// greater than the number of bytes available in the file starting 388 /// at \a offset, the number of bytes will be appropriately 389 /// truncated. The final number of bytes that get mapped can be 390 /// verified using the DataBuffer::GetByteSize() function on the return 391 /// shared data pointer object contents. 392 /// 393 /// @param[in] offset 394 /// The offset in bytes from the beginning of the file where 395 /// memory mapping should begin. 396 /// 397 /// @param[in] length 398 /// The size in bytes that should be mapped starting \a offset 399 /// bytes into the file. If \a length is \c SIZE_MAX, map 400 /// as many bytes as possible. 401 /// 402 /// @return 403 /// A shared pointer to the memeory mapped data. This shared 404 /// pointer can contain a NULL DataBuffer pointer, so the contained 405 /// pointer must be checked prior to using it. 406 //------------------------------------------------------------------ 407 lldb::DataBufferSP 408 MemoryMapFileContents (off_t offset = 0, size_t length = SIZE_MAX) const; 409 410 //------------------------------------------------------------------ 411 /// Read part of, or the entire contents of, a file into a heap based data buffer. 412 /// 413 /// Returns a shared pointer to a data buffer that contains all or 414 /// part of the contents of a file. The data copies into a heap based 415 /// buffer that lives in the DataBuffer shared pointer object returned. 416 /// The data that is cached will start \a offset bytes into the 417 /// file, and \a length bytes will be mapped. If \a length is 418 /// greater than the number of bytes available in the file starting 419 /// at \a offset, the number of bytes will be appropriately 420 /// truncated. The final number of bytes that get mapped can be 421 /// verified using the DataBuffer::GetByteSize() function. 422 /// 423 /// @param[in] offset 424 /// The offset in bytes from the beginning of the file where 425 /// memory mapping should begin. 426 /// 427 /// @param[in] length 428 /// The size in bytes that should be mapped starting \a offset 429 /// bytes into the file. If \a length is \c SIZE_MAX, map 430 /// as many bytes as possible. 431 /// 432 /// @return 433 /// A shared pointer to the memeory mapped data. This shared 434 /// pointer can contain a NULL DataBuffer pointer, so the contained 435 /// pointer must be checked prior to using it. 436 //------------------------------------------------------------------ 437 lldb::DataBufferSP 438 ReadFileContents (off_t offset = 0, size_t length = SIZE_MAX) const; 439 440 size_t 441 ReadFileContents (off_t file_offset, void *dst, size_t dst_len) const; 442 443 //------------------------------------------------------------------ 444 /// Change the file specificed with a new path. 445 /// 446 /// Update the contents of this object with a new path. The path will 447 /// be split up into a directory and filename and stored as uniqued 448 /// string values for quick comparison and efficient memory usage. 449 /// 450 /// @param[in] path 451 /// A full, partial, or relative path to a file. 452 /// 453 /// @param[in] resolve_path 454 /// If \b true, then we will try to resolve links the path using 455 /// the static FileSpec::Resolve. 456 //------------------------------------------------------------------ 457 void 458 SetFile (const char *path, bool resolve_path); 459 460 bool 461 IsResolved () const 462 { 463 return m_is_resolved; 464 } 465 466 //------------------------------------------------------------------ 467 /// Set if the file path has been resolved or not. 468 /// 469 /// If you know a file path is already resolved and avoided passing 470 /// a \b true parameter for any functions that take a "bool 471 /// resolve_path" parameter, you can set the value manually using 472 /// this call to make sure we don't try and resolve it later, or try 473 /// and resolve a path that has already been resolved. 474 /// 475 /// @param[in] is_resolved 476 /// A boolean value that will replace the current value that 477 /// indicates if the paths in this object have been resolved. 478 //------------------------------------------------------------------ 479 void 480 SetIsResolved (bool is_resolved) 481 { 482 m_is_resolved = is_resolved; 483 } 484 //------------------------------------------------------------------ 485 /// Read the file into an array of strings, one per line. 486 /// 487 /// Opens and reads the file in this object into an array of strings, 488 /// one string per line of the file. Returns a boolean indicating 489 /// success or failure. 490 /// 491 /// @param[out] lines 492 /// The string array into which to read the file. 493 /// 494 /// @result 495 /// Returns the number of lines that were read from the file. 496 //------------------------------------------------------------------ 497 size_t 498 ReadFileLines (STLStringArray &lines); 499 500 //------------------------------------------------------------------ 501 /// Resolves user name and links in \a src_path, and writes the output 502 /// to \a dst_path. Note if the path pointed to by \a src_path does not 503 /// exist, the contents of \a src_path will be copied to \a dst_path 504 /// unchanged. 505 /// 506 /// @param[in] src_path 507 /// Input path to be resolved. 508 /// 509 /// @param[in] dst_path 510 /// Buffer to store the resolved path. 511 /// 512 /// @param[in] dst_len 513 /// Size of the buffer pointed to by dst_path. 514 /// 515 /// @result 516 /// The number of characters required to write the resolved path. If the 517 /// resolved path doesn't fit in dst_len, dst_len-1 characters will 518 /// be written to \a dst_path, but the actual required length will still be returned. 519 //------------------------------------------------------------------ 520 static size_t 521 Resolve (const char *src_path, char *dst_path, size_t dst_len); 522 523 //------------------------------------------------------------------ 524 /// Resolves the user name at the beginning of \a src_path, and writes the output 525 /// to \a dst_path. Note, \a src_path can contain other path components after the 526 /// user name, they will be copied over, and if the path doesn't start with "~" it 527 /// will also be copied over to \a dst_path. 528 /// 529 /// @param[in] src_path 530 /// Input path to be resolved. 531 /// 532 /// @param[in] dst_path 533 /// Buffer to store the resolved path. 534 /// 535 /// @param[in] dst_len 536 /// Size of the buffer pointed to by dst_path. 537 /// 538 /// @result 539 /// The number of characters required to write the resolved path, or 0 if 540 /// the user name could not be found. If the 541 /// resolved path doesn't fit in dst_len, dst_len-1 characters will 542 /// be written to \a dst_path, but the actual required length will still be returned. 543 //------------------------------------------------------------------ 544 static size_t 545 ResolveUsername (const char *src_path, char *dst_path, size_t dst_len); 546 547 enum EnumerateDirectoryResult 548 { 549 eEnumerateDirectoryResultNext, // Enumerate next entry in the current directory 550 eEnumerateDirectoryResultEnter, // Recurse into the current entry if it is a directory or symlink, or next if not 551 eEnumerateDirectoryResultExit, // Exit from the current directory at the current level. 552 eEnumerateDirectoryResultQuit // Stop directory enumerations at any level 553 }; 554 555 typedef EnumerateDirectoryResult (*EnumerateDirectoryCallbackType) (void *baton, 556 FileType file_type, 557 const FileSpec &spec 558); 559 560 static EnumerateDirectoryResult 561 EnumerateDirectory (const char *dir_path, 562 bool find_directories, 563 bool find_files, 564 bool find_other, 565 EnumerateDirectoryCallbackType callback, 566 void *callback_baton); 567 568protected: 569 //------------------------------------------------------------------ 570 // Member variables 571 //------------------------------------------------------------------ 572 ConstString m_directory; ///< The uniqued directory path 573 ConstString m_filename; ///< The uniqued filename path 574 mutable bool m_is_resolved; ///< True if this path has been resolved. 575}; 576 577//---------------------------------------------------------------------- 578/// Dump a FileSpec object to a stream 579//---------------------------------------------------------------------- 580Stream& operator << (Stream& s, const FileSpec& f); 581 582} // namespace lldb_private 583 584#endif // #if defined(__cplusplus) 585#endif // liblldb_FileSpec_h_ 586