Main Page   Reference Manual   Namespace List   Compound List   Namespace Members   Compound Members   File Members  

Public Member Functions | Protected Attributes | List of all members
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 (void)
 The default constructor. More...
 
 location_ct (location_ct const &location)
 Copy constructor. More...
 
location_ctoperator= (location_ct const &location)
 Assignment operator. More...
 
void lock_ownership (void)
 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 (void)
 Clear the current object (set the location to 'unknown'). More...
 
bool is_known (void) 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 (void) const
 The source file name (without path). More...
 
unsigned int line (void) const
 Return the line number; only valid if is_known() returns true.
 
char const * mangled_function_name (void) const
 Returns the mangled function name or unknown_function_c when no function could be found. More...
 
size_t filename_length (void) const
 The size of the file name.
 
size_t filepath_length (void) const
 The size of the full path name.
 
object_file_ct const * object_file (void) 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

libcwd::location_ct::location_ct ( void  )
inline

The default constructor.

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

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).

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

Member Function Documentation

void libcwd::location_ct::clear ( void  )

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

Reset this location object (frees memory).

References M_filepath, and M_object_file.

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

std::string libcwd::location_ct::file ( void  ) 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.

References M_filename, and M_known.

void libcwd::location_ct::lock_ownership ( void  )
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.

References M_filepath, and M_known.

char const * libcwd::location_ct::mangled_function_name ( void  ) 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_ct const* libcwd::location_ct::object_file ( void  ) 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.

References M_object_file.

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 clear(), M_filename, M_filepath, M_func, M_initialization_delayed, M_known, M_line, and M_object_file.

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().

Copyright © 2001 - 2004 Carlo Wood.  All rights reserved.