libcwd::Location Class Reference

A source file location. More...

#include <libcwd/debug.h>

Public Member Functions
	Location (void const *addr)
	Construct a location for address addr.
	~Location ()
	Destructor.
	Location ()
	The default constructor.
	Location (Location const &location)
	Copy constructor.
Location &	operator= (Location const &location)
	Assignment operator.
void	lock_ownership ()
	Keep ownership of the stored path in this object.
void	pc_location (void const *pc)
	Initialize the current object with the location that corresponds with pc.
void	clear ()
	Clear the current object (set the location to 'unknown').
bool	is_known () const
	Returns false if no source-file:line-number information is known for this location (or when it is uninitialized or clear()-ed).
std::string	file () const
	The source file name (without path).
unsigned int	line () const
	Return the line number; only valid if is_known() returns true.
char const *	mangled_function_name () const
	Returns the mangled function name or unknown_function_c when no function could be found.
size_t	filename_length () const
	The size of the file name.
size_t	filepath_length () const
	The size of the full path name.
ObjectFileName const *	object_file () const
	Corresponding object file.
void	print_filepath_on (std::ostream &os) const
	Write the full path to an ostream.
void	print_filename_on (std::ostream &os) const
	Write the file name to an ostream.

Protected Attributes
ObjectFileName const *	object_file_name_
char const *	function_name_
	Pointer to static string containing the mangled function name of this location.
lockable_auto_ptr< char, true >	filepath_
	The full source file name of this location. Allocated in `pc_location' using new [].
unsigned int	line_
	The line number of this location.
bool	known_
	Set when filepath_ (and filename_) point to valid data and line_ contains a valid line number.

Detailed Description

The normal usage of this class is to print source-name:line-number information as follows:

Dout(dc::notice, "Called from " <<
    Location((char*)__builtin_return_address(0) + libcwd::builtin_return_address_offset) );

Constructor & Destructor Documentation

Location() [1/2]

libcwd::Location::Location ( )

inline

Constructs an unknown location object. Use pc_location to initialize the object.

References function_name_, known_, and object_file_name_.

Location() [2/2]

libcwd::Location::Location

(

Location const &

location

)

Constructs a location that is equivalent to the location passed as argument. Copies share the stored source-file path. By default, ownership of that path moves to the copy; call lock_ownership on the prototype first when the prototype must remain responsible for releasing the path storage.

References filename_, filepath_, function_name_, initialization_delayed_, known_, line_, Location(), and object_file_name_.

Member Function Documentation

clear()

void libcwd::Location::clear

(

)

Reset this location object (frees memory).

References filepath_, function_name_, known_, and object_file_name_.

Referenced by operator=(), pc_location(), and ~Location().

file()

std::string libcwd::Location::file ( ) const

inline

We don't allow to retrieve a pointer to the allocated character string because that is dangerous as the memory that it is pointing to could be deleted.

References filename_, and known_.

lock_ownership()

void libcwd::Location::lock_ownership ( )

inline

Prevents a subsequent copy or assignment from taking over responsibility for releasing the source-file path owned by this location. Use this when a location is used as a prototype for shorter-lived copies.

References filepath_, and known_.

mangled_function_name()

char const * libcwd::Location::mangled_function_name ( ) const

inline

Two other strings that can be returned are "<uninitialized Location>" and "<cleared Location>", the idea is to never print that: you should know it when a location object is in these states.

References function_name_.

object_file()

ObjectFileName const * libcwd::Location::object_file ( ) const

inline

Returns a pointer to an object representing the shared library or the executable that this location belongs to; only valid if is_known() returns true.

References object_file_name_.

operator=()

Location & libcwd::Location::operator=

(

Location const &

location

)

Assigns the value of the location passed to the current object. Copies share the stored source-file path. By default, ownership of that path moves to the target object; call lock_ownership on the source first when the source must remain responsible for releasing the path storage.

References clear(), filename_, filepath_, function_name_, initialization_delayed_, known_, line_, Location(), and object_file_name_.

pc_location()

void libcwd::Location::pc_location ( void const * pc )

inline

Point this location to a different program counter address.

References clear(), and pc_location().

Referenced by Location(), and pc_location().

Member Data Documentation

initialization_delayed_

void const* libcwd::Location::initialization_delayed_

If object_file_name_ == NULL and function_name_ points to pre_libcwd_initialization_c_, then this is the address that pc_location was called with.

Referenced by Location(), and operator=().

object_file_name_

ObjectFileName const* libcwd::Location::object_file_name_

protected

A pointer to an object representing the library or executable that this location belongs to or NULL when not initialized.

Referenced by clear(), Location(), Location(), object_file(), and operator=().

unknown_pc_

void const* libcwd::Location::unknown_pc_

If object_file_name_ == NULL and function_name_ points to unknown_function_c, then this is the address that pc_location was called with.

---

The documentation for this class was generated from the following files:

• libcwd/Location.h
• src/location.cxx
• libcwd/Location.inl.h