libcwd::location_ct Class Reference

A source file location. More...

#include <libcwd/debug.h>

Public Member Functions
	location_ct (void const *addr)
	Construct a location for address addr.
	~location_ct ()
	Destructor.
	location_ct ()
	The default constructor. More...
	location_ct (location_ct const &location)
	Copy constructor. More...
location_ct &	operator= (location_ct const &location)
	Assignment operator. More...
void	lock_ownership ()
	Lock ownership of internal allocations. More...
void	pc_location (void const *pc)
	Initialize the current object with the location that corresponds with pc. More...
void	clear ()
	Clear the current object (set the location to 'unknown'). More...
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). More...
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. More...
size_t	filename_length () const
	The size of the file name.
size_t	filepath_length () const
	The size of the full path name.
object_file_ct const *	object_file () const
	Corresponding object file. More...
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
lockable_auto_ptr< char, true >	M_filepath
	The full source file name of this location.  Allocated in `M_pc_location' using new [].
unsigned int	M_line
	The line number of this location.
char const *	M_func
	Pointer to static string containing the mangled function name of this location.
object_file_ct const *	M_object_file
	A pointer to an object representing the library or executable that this location belongs to or NULL when not initialized.
bool	M_known
	Set when M_filepath (and M_filename) point to valid data and M_line contains a valid line number.

Detailed Description

A source file location.

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

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

Constructor & Destructor Documentation

location_ct() [1/2]

libcwd::location_ct::location_ct ( )

inline

The default constructor.

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

location_ct() [2/2]

libcwd::location_ct::location_ct

(

location_ct const &

location

)

Copy constructor.

Constructs a location that is equivalent to the location passed as argument. The new object will be the owner of the memory allocations of this location unless the member function lock_ownership was called for the prototype before copying it. It is the responsibility of the coder to make sure that the allocation owner is the object that is last deleted (if at all).

Member Function Documentation

clear()

void libcwd::location_ct::clear

(

)

Clear the current object (set the location to 'unknown').

Reset this location object (frees memory).

Referenced by pc_location(), and ~location_ct().

file()

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

inline

The source file name (without path).

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.

lock_ownership()

void libcwd::location_ct::lock_ownership ( )

inline

Lock ownership of internal allocations.

Makes this object responsible for deleting internal allocations, the user is responsible to making sure that the owner is deleted last.

mangled_function_name()

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

inline

Returns the mangled function name or unknown_function_c when no function could be found.

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

References M_func.

object_file()

object_file_ct const* libcwd::location_ct::object_file ( ) const

inline

Corresponding object file.

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.

operator=()

location_ct & libcwd::location_ct::operator=

(

location_ct const &

location

)

Assignment operator.

Assigns the value of the location passed to the current object. The new object will be the owner of the memory allocations of this location unless the member function lock_ownership was called for the prototype before copying it. It is the responsibility of the coder to make sure that the allocation owner is the object that is last deleted (if at all).

References M_filename, M_filepath, M_func, M_initialization_delayed, M_known, M_line, and M_object_file.

pc_location()

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

inline

Initialize the current object with the location that corresponds with pc.

Point this location to a different program counter address.

References clear().