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