pvxs/documentation/util.rst

Misc

Logging

PVXS internally logs warning/status messages using errlog.h from EPICS Base. User applications may control which messages are printed, and may add output. :

#include <pvxs/log.h>
namespace pvxs { ... }

Control of log message output is available through named loggers. All internal logger names begin with the prefix "pvxs.".

In addition to a name, each logger has an associated integer logging level. A message will be logged if the level of the message is less than or equal to the level of the associated logger.

To enable all logging at full detail. :

export PVXS_LOG="*=DEBUG"

pvxs::Level

Controlling Logging

By default, all loggers have level Err. It is recommended that user applications prefer configuration through the environment variable $PVXS_LOG by calling pvxs::logger_config_env.

pvxs::logger_config_env()

If this is undesireable, logger levels may be (reset) manually.

pvxs::logger_level_set(const char *, Level)

pvxs::logger_level_clear()

Logging from User applications

To emit log messages from user code, a new logger should be defined with DEFINE_LOGGER which will be usable within the current translation unit. It is allowable for multiple loggers to have the same name.

Logger names beginning with "pvxs.*" is reserved for internal usage, and must not be present in user code.

DEFINE_LOGGER

log_crit_printf

log_err_printf

log_warn_printf

log_info_printf

log_debug_printf

log_printf

pvxs::logger

Identification

Compile time access to PVXS library version information. :

#include <pvxs/util.h>
namespace pvxs { ... }

PVXS_VERSION

VERSION_INT

eg. to conditionally compile based on library version. :

#if PVXS_VERSION < VERSION_INT(1,2,3,4)
// enable some compatibility code
#endif

pvxs::version_int

pvxs::version_str

Unit-test helpers

Extensions to epicsUnitTest.h :

#include <pvxs/unittest.h>
namespace pvxs { ... }

testTrue

testFalse

testEq

testNotEq

testShow

The testEq() macro and friends expand to a function which returns a pvxs::testCase instance which may be used as a std::ostream to append text describing a test. eg. :

testEq(1, 1)<<"We really hope this is true.";
if(testNotEq(1, 2)<<"shouldn't be true") {
    // further conditional tests if 1!=2
}

pvxs::testThrows

pvxs::testCase

Utilities

Misc. utility code. :

#include <pvxs/util.h>
namespace pvxs { ... }

pvxs::escape(const std::string&)

pvxs::escape(const char *)

pvxs::escape(const char *, size_t)

pvxs::cleanup_for_valgrind

pvxs::SigInt