Utility Components

---

Detailed Description

Utility classes and functions.

Modules
	Back-end Utility Components
	Utility classes and functions for use in creating custom (and stock) back-ends.
Defines
#define	PANTHEIOS_STRINGIZE(x)   PANTHEIOS_STRINGIZE_(x)
	Macro for stringizing symbols during preprocessing phase.
#define	PANTHEIOS_DECLSPEC
	Storage class specifier to be applied to all Pantheios API functions.
#define	PANTHEIOS_EXTERN_C   extern "C"
	Resolves to extern when compiling in C, and extern "C" when compiling in C++.
#define	PANTHEIOS_CALLCONV
	Calling convention specifier to be applied to all Pantheios API functions.
#define	PANTHEIOS_CALL(rt)   PANTHEIOS_DECLSPEC PANTHEIOS_EXTERN_C rt PANTHEIOS_CALLCONV
	Used to declare and define Pantheios API functions.
#define	PANTHEIOS_DECLARE_DEPRECATION(symtype, oldfn, newfn)
	Used to mark an inline (C++) function as deprecated.
#define	PANTHEIOS_CALL_DEPRECATED(rt, oldfn, newfn)   PANTHEIOS_CALL(rt)
	Used to declare an API function as deprecated.
Functions
pan_char_t *	strdup_nothrow (pan_char_t const *s) throw ()
	Equivalent to pantheios_util_strdup_nothrow().
void	strfree (pan_char_t *s) throw ()
	Equivalent to pantheios_util_strfree().
size_t	pantheios_getHostName (pan_char_t *buffer, size_t cchBuffer)
	Retrieves the host system identifier.
size_t	getHostName (pan_char_t *buffer, size_t cchBuffer)
	Equivalent to pantheios_getHostName().
template<size_t N, typename A>
size_t	getHostName (stlsoft::auto_buffer< pan_char_t, A, N > &buffer)
	Retrieves the host system identifier.
stlsoft::ss_sint64_t	pantheios_getCurrentProcessId (void)
	Returns an identifier for the process.
stlsoft::ss_sint64_t	getCurrentProcessId ()
	Equivalent to pantheios_getCurrentProcessId().
stlsoft::ss_sint64_t	pantheios_getCurrentThreadId (void)
	Returns an identifier for the calling thread.
stlsoft::ss_sint64_t	getCurrentThreadId ()
	Equivalent to pantheios_getCurrentThreadId().

---

Define Documentation

#define PANTHEIOS_CALL

(

rt

)

PANTHEIOS_DECLSPEC PANTHEIOS_EXTERN_C rt PANTHEIOS_CALLCONV

Used to declare and define Pantheios API functions.

Examples:

cpp/backends/example.cpp.backends.callback/example.cpp.backends.callback.cpp, cpp/backends/example.cpp.backends.file.callback/example.cpp.backends.file.callback.cpp, cpp/custom/example.cpp.custom.wrap_log4cplus/example.cpp.custom.wrap_log4cplus.cpp, cpp/custom/example.cpp.custom.wrap_log4cxx/example.cpp.custom.wrap_log4cxx.cpp, cpp/format/example.cpp.format.highres/example.cpp.format.highres.cpp, cpp/format/example.cpp.format.lowres/example.cpp.format.lowres.cpp, cpp/frontends/example.cpp.frontends.custom/example.cpp.frontends.custom.cpp, and cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp.

#define PANTHEIOS_CALL_DEPRECATED	(	rt,
		oldfn,
		newfn		)	PANTHEIOS_CALL(rt)

Used to declare an API function as deprecated.

See also:

PANTHEIOS_CALL

PANTHEIOS_DECLARE_DEPRECATION

#define PANTHEIOS_CALLCONV

Calling convention specifier to be applied to all Pantheios API functions.

Used in the PANTHEIOS_CALL() macro.

#define PANTHEIOS_DECLARE_DEPRECATION	(	symtype,
		oldfn,
		newfn		)

Used to mark an inline (C++) function as deprecated.

#define PANTHEIOS_DECLSPEC

Storage class specifier to be applied to all Pantheios API functions.

Defaults to no symbol. Can be defined to a symbol appropriate to the operating system and linkage model. e.g. on Windows you might choose to define it to __declspec(dllexport) when building Pantheios and to __declspec(dllimport) in client code using Pantheios.

Used in the PANTHEIOS_CALL() macro.

#define PANTHEIOS_EXTERN_C   extern "C"

Resolves to extern when compiling in C, and extern "C" when compiling in C++.

Used in the PANTHEIOS_CALL() macro.

Examples:

cpp/backends/example.cpp.backends.callback/example.cpp.backends.callback.cpp, cpp/backends/example.cpp.backends.file.callback/example.cpp.backends.file.callback.cpp, cpp/backends/example.cpp.backends.file.lrsplit/example.cpp.backends.file.lrsplit.cpp, cpp/backends/example.cpp.backends.file/example.cpp.backends.file.cpp, cpp/contract/example.cpp.contract.PANTHEIOS_ASSERT/example.cpp.contract.PANTHEIOS_ASSERT.cpp, cpp/contract/example.cpp.contract.PANTHEIOS_MESSAGE_ASSERT/example.cpp.contract.PANTHEIOS_MESSAGE_ASSERT.cpp, cpp/format/example.cpp.format.highres/example.cpp.format.highres.cpp, cpp/format/example.cpp.format.lowres/example.cpp.format.lowres.cpp, cpp/format/example.cpp.format.pad/example.cpp.format.pad.cpp, cpp/inserters/example.cpp.inserter.args/example.cpp.inserter.args.cpp, cpp/inserters/example.cpp.inserter.b/example.cpp.inserter.b.cpp, cpp/inserters/example.cpp.inserter.b64/example.cpp.inserter.b64.cpp, cpp/inserters/example.cpp.inserter.blob/example.cpp.inserter.blob.cpp, cpp/inserters/example.cpp.inserter.character/example.cpp.inserter.character.cpp, cpp/inserters/example.cpp.inserter.hex_ptr/example.cpp.inserter.hex_ptr.cpp, cpp/inserters/example.cpp.inserter.hostid/example.cpp.inserter.hostid.cpp, cpp/inserters/example.cpp.inserter.i/example.cpp.inserter.i.cpp, cpp/inserters/example.cpp.inserter.integer/example.cpp.inserter.integer.cpp, cpp/inserters/example.cpp.inserter.m2w/example.cpp.inserter.m2w.cpp, cpp/inserters/example.cpp.inserter.p/example.cpp.inserter.p.cpp, cpp/inserters/example.cpp.inserter.pointer/example.cpp.inserter.pointer.cpp, cpp/inserters/example.cpp.inserter.processid/example.cpp.inserter.processid.cpp, cpp/inserters/example.cpp.inserter.real/example.cpp.inserter.real.cpp, cpp/inserters/example.cpp.inserter.threadid/example.cpp.inserter.threadid.cpp, cpp/inserters/example.cpp.inserter.w2m/example.cpp.inserter.w2m.cpp, cpp/inserters/example.cpp.inserter.xi/example.cpp.inserter.xi.cpp, cpp/inserters/example.cpp.inserter.xp/example.cpp.inserter.xp.cpp, cpp/linking/example.cpp.linking.implicit_link_1/example.cpp.linking.implicit_link_1.cpp, cpp/misc/example.cpp.misc.custom_type_1/example.cpp.misc.custom_type_1.cpp, cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp, cpp/misc/example.cpp.misc.hetero1/example.cpp.misc.hetero1.cpp, cpp/misc/example.cpp.misc.strings/example.cpp.misc.strings.cpp, cpp/tracing/example.cpp.tracing.standard/example.cpp.tracing.standard.cpp, and cpp/tracing/example.cpp.tracing.with_function/example.cpp.tracing.with_function.cpp.

#define PANTHEIOS_STRINGIZE

(

x

)

PANTHEIOS_STRINGIZE_(x)

Macro for stringizing symbols during preprocessing phase.

Parameters:

x

The preprocessor symbol whose value will be turned into a string

---

Function Documentation

stlsoft:: ss_sint64_t pantheios::util::getCurrentProcessId

(

)

[inline]

Equivalent to pantheios_getCurrentProcessId().

stlsoft:: ss_sint64_t pantheios::util::getCurrentThreadId

(

)

[inline]

Equivalent to pantheios_getCurrentThreadId().

size_t pantheios::getHostName

(

stlsoft::auto_buffer< pan_char_t, A, N > &

buffer

)

[inline]

Retrieves the host system identifier.

Parameters:

buffer

A mutable (non-const) reference to an instance of a specialisation of stlsoft::auto_buffer in which the elicited host-name will be written, including terminating nul-character

size_t pantheios::getHostName	(	pan_char_t *	buffer,
		size_t	cchBuffer
	)			[inline]

Equivalent to pantheios_getHostName().

stlsoft:: ss_sint64_t pantheios::pantheios_getCurrentProcessId

(

void

)

Returns an identifier for the process.

stlsoft:: ss_sint64_t pantheios::pantheios_getCurrentThreadId

(

void

)

Returns an identifier for the calling thread.

Remarks:

The returned value will be unique on a per-thread basis within a given process. It is not guaranteed to be the same value as that known to/obtained from the operating system.

size_t pantheios::pantheios_getHostName	(	pan_char_t *	buffer,
		size_t	cchBuffer
	)

Retrieves the host system identifier.

Parameters:

	buffer	Pointer to a character buffer to receive a copy of the host name. May not be NULL unless cchBuffer is 0
	cchBuffer	Number of characters available in buffer. Must include the space for a terminating nul.

Returns:

The number of characters copied into the destination buffer, or an error indication code.

Return values:

	0	The host name was unavailable. (For those builds for which exceptions are not supported, this will include out-of-memory conditions.)
	cchBuffer	There was insufficient space to copy the host name into the buffer. The host name is not copied into the buffer.

Remarks:

This function abstracts the underlying system call(s) of the supported operating systems. The somewhat awkward semantics - indicating exhaustion by returning the requested size rather than the required size - is a result of the limitation of the UNIX gethostname() function. Since the function is intended to be mostly used, via the C++ wrapper, from the pantheios::hostId inserter class, the inconvenience is deemed acceptable.

pan_char_t* pantheios::util::strdup_nothrow

(

pan_char_t const *

s

)

throw () [inline]

Equivalent to pantheios_util_strdup_nothrow().

Examples:

cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp.

void pantheios::util::strfree

(

pan_char_t *

s

)

throw () [inline]

Equivalent to pantheios_util_strfree().

Examples:

cpp/misc/example.cpp.misc.extended_severity_information/example.cpp.misc.extended_severity_information.cpp.

pantheios Library documentation © Matthew Wilson & Synesis Software, 2006-2011