Repository files navigation

log4cplus is a simple to use C++23 logging API providing thread--safe,flexible, and arbitrarily granular control over log management andconfiguration. It is modeled after the Java log4j API.

The latest up-to-date information for this project can be found on theGitHub project page or thelog4cplus wiki. Please submit bugs,patches, feature requests, and so on onGitHub.

The aim of this project is to develop a log4j-like logging framework foruse primarily in C++. One of the major design goals is to avoidhuge dependencies (like Boost) in the core functionality and to usestandard C++ facilities instead. Where possible, the project takesinspiration from other logging libraries, besides log4j (e.g.,from log4net, log4cxx, log4cpp).

log4cplus version 3.0 and beyond require C++23.log4cplus has beenported to and tested on the following platforms:

• Linux/AMD64 with GCC version 13.2.0 (Ubuntu 13.2.0-23ubuntu4)
• Linux/AMD64 with Clang version 18.1.3 (18.1.3-1ubuntu1)
• Windows/AMD64 with GCC version 4.8.2 (x86_64-posix-seh-rev3, Built byMinGW-W64 project) using CMake build system
• Windows/AMD64 with GCC version 4.9.2 (tdm64-1) using CMake build system
• Windows 7 with MS Visual Studio 2015
• OpenBSD 5.6/AMD64 with GCC version 4.9.0
• FreeBSD 10.1/i386 with Clang version 3.4.1 (tags/RELEASE_34/dot1-final 208032)
• NetBSD 6.1.5/AMD64 with GCC version 4.9.1
• DragonflyBSD 4.0.1/AMD64 with GCC version 4.9.3 20141126 (prerelease)(FreeBSD Ports Collection)
• OpenIndiana Hipster 2016.10 with GCC version 4.9.4

Testing on the above-listed platforms was done at some point in timewith some version of the source. Continuous testing is performed onlyon the Linux platform offered by the [Travis CI][11] service.

The oldest Windows version that is supported by 2.x releases is Windows Vista.

The following platforms were supported by the 1.x series oflog4cplus. Theyeither do not have a reasonably C++23-capable compiler or have not yet beenchecked withlog4cplus 3.x:

• Minix 3.3.0/i386 with Clang version 3.4 (branches/release_34) with--disable-threads
• Linux/AMD64 with Intel Parallel Studio XE 2015, ICPC version 15.0.1
• OpenSolaris with-library=stlport4
• Solaris with-library=stlport4 and with-library=Cstd.
• Solaris 5.10/Sparc
• MacOS X 10.8
• MacOS X 11.4.2
• HP-UX (hppa2.0w-hp-hpux11.11)
• Haiku R1 Alpha 4.1
• AIX 5.3 with IBM XL C/C++ for AIX

Generic Autotools installation instructions are in theINSTALL file. Thefollowing arelog4cplus-specific instructions.

log4cplus uses Git sub-modules. Always use--recurse-submodules option whendoinggit clone.

This option is disabled by default. This option mainly affects GCCbuilds but it also has some limited effect on non-GCC builds. Itturns on debugging information generation, undefinesNDEBUG symboland adds-fstack-check (GCC).

This option is enabled by default. It adds platform / compilerdependent warning options to compiler command line.

This option is enabled by default. It enables SO version decorationon resulting library file, e.g., the.2.0.0 inliblog4cplus-1.2.so.2.0.0.

This option is enabled by default. It enables release versiondecoration on the resulting library file, e.g., the-1.2 inliblog4cplus-1.2.so.2.0.0.

This option is enabled by default. It enables use of compiler andplatform specific option for symbols visibility. See also theVisibility page on GCC Wiki.

This option is disabled by default. This option adds profilinginformation generation compiler option-pg to GCC and Sun CC /Solaris Studio builds.

This option is enabled by default. It turns on detection of necessarycompiler and linker flags that enable POSIX threading support.

While this detection usually works well, some platforms still needhelp with configuration by supplying additional flags to theconfigure script. One of the known deficiencies is Solaris Studio onLinux. See one of the later notes for details.

This option is enabled by default. It enables compilation of test executables.

This option is disabled by default. It enables compilation of unit tests alongwith their units. These unit tests can then be executed through theunit_tests test executable that is built during compilation.

This option is enabled by default. It enables implicit initialization oflog4cplus. When it is turned off,log4cplus has to be explicitlyinitialized by calling eitherlog4cplus::initialize() or by instantiatinglog4cplus::Initializer.

This option is disabled by default. It enables LTO (Link-Time Optimization)builds.

This option is enabled by default. When enabled, additional binaries will bebuilt, marked withU suffix in file name and compiled with-DUNICODE=1flag. In effect, these binaries assume thatlog4cplus::tchar iswchar_t.

This is one of three locale andwchar_t↔char conversion relatedoptions. It is disabled by default.

It is known to work well with GCC on Linux. Other platforms generallyhave lesser locale support in their implementations of the C++standard library. It is known not to work well on any BSDs.

See also docs/unicode.txt.

This is the second of thewchar_t↔char conversion-related options. It isdisabled by default.

It is known to work well on most Unix--like platforms, includingrecent Cygwin.

This is the third of thewchar_t↔char conversion-related options. It isdisabled by default.

The conversion using iconv() function always uses"UTF-8" and"WCHAR_T" as source/target encoding. It is known to work well onplatforms with GNU iconv. Different implementations oficonv()might not support"WCHAR_T" encoding selector.

Either the system-providediconv() or the library-providedlibiconv() isdetected and accepted. Both SUSv3 and GNUiconv() functionsignatures are accepted.

This option is disabled by default. It enables compilation of aseparate shared library (liblog4cplusqt4debugappender) that implementsQt4DebugAppender. It requires Qt4 and pkg-config to be installed.

This option is disabled by default. It enables compilation of a separateshared library (liblog4cplusqt5debugappender) that implementsQt5DebugAppender. It requires Qt5 and pkg-config to be available.

On Unix--like platforms,log4cplus can be compiled using either theAutotools-based build system or the CMake build system. TheAutotools-based build system is considered to be primary forUnix--like platforms.

On Windows, the primary build system is Visual Studio 2015 solutionand projects (msvc14/log4cplus.sln).

MinGW is supported by the Autotools-based build system. The CMake build systemis supported as well, and it should be used to compilelog4cplus witholder versions of Visual Studio or with less common compiler suites(e.g., Embarcadero, Code::Blocks, etc.).

Cygwin 2.5.x has a problem¹ linking binaries that use language-levelthread-local storage and share thread-local variables across translationunits. To avoid the issue, language-level thread-local storage is not used onCygwin and traditional POSIX thread-local storage is used instead.

log4cplus can use functions like_vsnprintf_s() (Microsoft'ssecure version ofvsnprintf()). MinGW toolchains (by default) linkto the systemMSVCRT.DLL. Unfortunately, older systems, like WindowsXP, ship withMSVCRT.DLL that lacks these functions. It is possibleto compilelog4cplus with MinGW toolchains butwithout usingMicrosoft's secure functions by defining__MSVCRT_VERSION__ to a valueless than0x900 and vice versa.

$ ../configure CPPFLAGS="-D__MSVCRT_VERSION__=0x700"

log4cplus uses C++11 thread and synchronization facilities. Thesynchronization facilities are implemented in Visual Studio C++ standardlibrary in a way that utilizes global variables. Therefore it is impossible(due to "static initialization order fiasco") to use them outsidemain(). This issue manifests as a deadlock on exit during destruction oflog4cplus' thread pool.

To overcome this limitation,

• always uselog4cplus::Initializer initializer; as the first thing inmain();

• never try to log from static/global objects constructors;

• never try to log from static/global object destructors.

Defining thelog4cplus::Initializer instance as the first thing inmain()ensures thatlog4cplus is initialized. More importantly, it ensures thatlog4cplus shuts down before the execution leaves themain()function.log4cplus will try to automatically initialize at process startupand/or on DLL load, and will not tear down until alllog4cplus:Initializerinstances are destroyed.

On Windows, the standard C++ file streams open files in a way that theunderlying Win32 fileHANDLE is not opened with theFILE_SHARE_DELETEflag. This flag, besides shared delete, allows renaming files that havehandles open to them. This issue manifests as error code 13 when the fileneeds to be rolled over while it is still open by another process.

This is alsobug #167 onSourceForge.

log4cplus uses thread--local storage (TLS) for NDC, MDC and tooptimize use of some temporary objects. On Windows there are two waysto get TLS:

1. usingTlsAlloc(), etc., functions
2. using__declspec(thread)

While method (2) generates faster code, it hassome limitations prior to Windows Vista. Iflog4cplus.dll is loaded at run time usingLoadLibrary() (or as adependency of such loaded library), then accessing__declspec(thread) variables can cause general protection fault(GPF) errors. This is because Windows prior to Windows Vista do notextend the TLS for libraries loaded at run time usingLoadLibrary().To allow using the best available method,log4cplus enables themethod (2) by checking_WIN32_WINNT >= 0x0600 condition, whencompilinglog4cplus targeted to Windows Vista or later.

If you are linking your application with the DLL variant oflog4cplus, defineLOG4CPLUS_BUILD_DLL preprocessor symbol. This changes definition ofLOG4CPLUS_EXPORT symbol to__declspec(dllimport).

log4cplus uses thread--local storage (TLS, see "Windows and TLS" fordetails). On the Android platform, whenlog4cplus is being compiled usingtheandroid/android.toolchain.cmake, you might get errors featuring the__emutls symbol:

global-init.cxx:268:46: error: log4cplus::internal::__emutls_t._ZN9log4cplus8internal3ptdE causes a section type conflict with log4cplus::internal::ptd

To work around this issue, invoke CMake with-DANDROID_FUNCTION_LEVEL_LINKING:BOOL=OFF option.

log4cplus is not safe to be used from asynchronous signals'handlers. This is a property of most threaded programmes in general.If you are going to uselog4cplus in threaded application and if youwant to uselog4cplus from signal handlers then your only option isto block signals in all threads but one that will handle all signals.On POSIX platforms, this is possible using thesigwait() call.log4cplus enables this approach by blocking all signals in anythreads created through its threads helpers.

IBM's XL C/C++ compiler executable hasmany variants. To compilelog4cplus with threading support specify one of the compilervariants that support threading using theCXX variable onconfigure script command line. E.g.:

$ ../configure --enable-threads CXX=xlC_r

There appears to be a reentrancy problem with AIX 5.3 and xlC 8 whichcan result into a deadlock condition in some circumstances. It isunknown whether the problem manifests with other versions of eitherthe OS or the compiler, too. The problem was initially reported in abug report#103.

The core of the problem is that IBM's/xlC's standard C++ IOStreamsimplementation uses global non recursive lock to protect some of itsstate. The application in the bug report was trying to do loggingusinglog4cplus from insideoverflow() member function of a classderived fromstd::streambuf class.log4cplus itself usesstd::ostringstream. This resulted into an attempt to recursivelylock the global non recursive lock and a deadlock.

Some older version of this operating system might have problemslinkinglog4cplus due tomissing__tls_get_addr in theirunpatched state.

Solaris Studio compilers' default standard C++ library is verynon-standard. It seems that it is not conforming enough in, e.g., SunC++ 5.12 Linux_i386 2011/11/16 (missingstd::time_t, etc.), but itworks well enough on Solaris with Sun C++ 5.8 2005/10/13. Thuslog4cplus adds-library=stlport4 to theCXXFLAGS environmentvariable, unless a switch matching-library=(stlport4|stdcxx4|Cstd)is already present there. If you want to override the defaultsupplied bylog4cplus, just set it intoCXXFLAGS onconfigurescript command line.

Solaris Studio supports the__func__ symbol which can be used bylog4cplus to record function name in logged events. To enable thisfeature, add-features=extensions switch toCXXFLAGS forconfigure script. Subsequently, you will have to add this switch toyour application's build flags as well.

The Autotools and ourconfigure.ac combination do not handle the SolarisStudio compiler on Linux well enough and need a little help with theconfiguration of POSIX threads:

$ COMMON_FLAGS="-L/lib/x86_64-linux-gnu/\-L/usr/lib/x86_64-linux-gnu/ -mt=yes -O"$ ../configure --enable-threads=yes \CC=/opt/solarisstudio12.3/bin/cc \CXX=/opt/solarisstudio12.3/bin/CC \CFLAGS="$COMMON_FLAGS" \CXXFLAGS="$COMMON_FLAGS" \LDFLAGS="-lpthread"

It is necessary to turn on C++98 mode ofaCC by providing the-AAflag:

$ ../configure --enable-threads=yes CXXFLAGS="-AA"

There is a problem on IA64 HP-UX withaCC (HP C/aC++ B3910BA.06.20). The problem manifests asunsatisfied symbols during linking ofloggingserver:

ld: Unsatisfied symbol "virtual table of loggingserver::ClientThread" in file loggingserver.o

The problem appears to be a deficiency inaCC and its support of__declspec(dllexport). To work around this issue, add--disable-symbols-visibility-options toconfigure script commandline:

$ ../configure --disable-symbols-visibility-options \--enable-threads=yes CXXFLAGS="-AA"

Haiku is supported with GCC 4+. The default GCC version in Haiku isset to version 2 (based on GCC 2.95.x). To change the default GCCversion to 4, please run thesetgcc gcc4 command. This is toavoid linking errors like this:

main.cpp:(.text.startup+0x54a): undefined reference to `_Unwind_Resume'

Running the command switches thecurrent GCC version to version 4.This change is permanent and global. See also the Haiku ticket#8368.

In order to uselog4cplus in Qt4 programs it is necessary to set thefollowing option:Treat WChar_t As Built-in Type: No (/Zc:wchar_t-)

Set this option for thelog4cplus project and theQt4DebugAppenderproject in MS Visual Studio. Remember to use the Unicode versions oflog4cplus libraries with Qt. It is also necessary to make a cleardistinction between debug and release builds of the Qt project andlog4cplus. Do not use thelog4cplus release library with the debugversion of a Qt program and vice versa.

To register the Qt4DebugAppender library at runtime, call thisfunction:log4cplus::Qt4DebugAppender::registerAppender()

Add these lines to the qmake project file to uselog4cplus andQt4DebugAppender:

INCLUDEPATH += C:\log4cplus\includewin32 {    CONFIG(debug, debug|release) {        LIBS += -LC:\log4cplus\msvc14\Win32\bin.Debug_Unicode -llog4cplusUD        LIBS += -LC:\log4cplus\msvc14\Win32\bin.Debug_Unicode -llog4cplus-Qt4DebugAppender    } else {        LIBS += -LC:\log4cplus\msvc14\Win32\bin.Release_Unicode -llog4cplusU        LIBS += -LC:\log4cplus\msvc14\Win32\bin.Release_Unicode -llog4cplus-Qt4DebugAppender    }}

You might encounter the following error during compilation with--with-qt option:

qglobal.h:943: error: ISO C++ does not support 'long long'

This is caused by-pedantic option thatlog4cplus adds toCXXFLAGS when compiling with GCC. To work around this issue, add-Wno-long-long GCC option toCXXFLAGS.

OpenBSD 5.2 and earlier have a bug inwcsftime() function inhandling of%% and%N where N is not a supported formatter. Thisis fixed in OpenBSD 5.3 and later. This shows as failingtimeformat_test whenlog4cplus is compiled with-DUNICODE inCXXFLAGS.

iOS support is based on CMake build. Use the scripts iniOS directory. TheiOS.cmake toolchain file was originally taken fromios-cmake project.

To build the library for iOS, being in current folder, perform the stepsbelow. For ARMv7 architecture:

$ ./scripts/cmake_ios_armv7.sh$ cmake --build ./build_armv7 --config "Release"$ cmake --build ./build_armv7 --config "Debug"

For i386 architecture:

$ ./scripts/cmake_ios_i386.sh$ cmake --build ./build_i386 --config "Release"$ cmake --build ./build_i386 --config "Debug"

Some versions of the iOS and/or its SDK have problems with thread-local storage(TLS) and getting through CMake's environment detection phase. To work aroundthese issues, make these changes:

Edit theiOS.cmake file and add these two lines.

set (CMAKE_CXX_COMPILER_WORKS TRUE)set (CMAKE_C_COMPILER_WORKS TRUE)

Add these lines, customizing them accordingly:

set(MACOSX_BUNDLE_GUI_IDENTIFIER com.example)set(CMAKE_MACOSX_BUNDLE YES)set(CMAKE_XCODE_ATTRIBUTE_CODE_SIGN_IDENTITY "iPhone Developer")set(IPHONEOS_ARCHS arm64)

If you have issues with TLS, also comment out these lines:

set(LOG4CPLUS_HAVE_TLS_SUPPORT 1)set(LOG4CPLUS_THREAD_LOCAL_VAR "__thread")

Beware, the%s specifier does not work the same way on Unix--likeplatforms as it does on Windows with Visual Studio. With Visual Studiothe%s specifier changes its meaning by printing awchar_t stringwhen used withwprintf() and achar string when used withprintf(). On the other hand, Unix-like platforms keep the meaning ofprintingchar strings when used with bothwprintf() andprintf(). It is necessary to use the%ls (C99) specifier or the%S(SUSv2) specifier to printwchar_t strings on Unix-like platforms.

The common ground for both platforms appears to be using%ls and awchar_t string to print strings with an unmodified format string onboth Unix-like platforms and Windows. The conversion ofwchar_t backtochar then depends on the C locale.

log4cplus does not support too old or broken C++ compilers. Sincelog4cplusversion 3.0.0, it means it does not support any platform or compiler withoutdecent C++23 support.

• Visual Studio prior to 2015
• GCC prior to 4.8

For successful resolution of reported bugs, it is necessary to provide enough information:

• log4cplus

  • What is the exact release version or Git branch and revision?
  • What is the build system that you are buildinglog4cplus with(Autotools, Visual Studio solution and its version, CMake).
  • Autotools -- Provideconfigure script parameters and environmentvariables, attach generatedconfig.log anddefines.hxx files.
  • CMake -- Provide build configuration (Release,Debug,RelWithDebInfo) and non--defaultCMAKE_* variables values.
  • Visual Studio -- Provide project configuration (Release,Release_Unicode,Debug,Debug_Unicode) and Visual Studio version.
  • Provide target OS and CPU. In case of MinGW, provide its exact compilerdistribution -- TDM? Nuwen? Other?

• log4cplus client application

  • Are you using shared librarylog4cplus or as static librarylog4cplus?
  • Islog4cplus linked into an executable or into a shared library (DLL orSO)?
  • Iflog4cplus is linked into a shared library, is this libraryloaded dynamically or not?
  • What library file you are linking your application with --log4cplus.lib,log4cplusUSD.lib,liblog4cplus.dll.a, etc., onWindows?
  • Is your application is using Unicode/wchar_t or not?
  • Provide any error messages.
  • Provide stack trace.
  • Providelog4cplus properties/configuration files.
  • Provide a self--contained test case, if possible.

This library is licensed under the Apache Public License 2.0 and thetwo-clause BSD license. Please read the includedLICENSE file fordetails.

log4cplus (bug tracker, files, wiki) is hosted on GitHub. See also theContributionstopic on the wiki.

Anybody can contribute to log4cplus development.If you are contributing a source code change, use a reasonableform: a merge request of a Git branch.

Please use common sense. Follow the style of the surrounding code. You canuse the following Emacs style, which is based on Microsoft's style, as aguideline:

;; Custom MS like indentation style.(c-add-style"microsoft"'("stroustrup"               (c-offsets-alist                (innamespace.-)                (inline-open.0)                (inher-cont. c-lineup-multi-inher)                (arglist-cont-nonempty.+)                (template-args-cont.+))))

log4cplus supports multiple build systems (GNU Autoconf/Automake/Libtool akaAutotools, CMake and Visual Studio solution and project files).

Autotools is considered the primary build system on Unix--likeplatforms. However, CMake should still be usable on Unix--like platforms aswell.

On Windows, it depends on the compiler and toolchain that you want to use. Whenusing Visual Studio, use Visual Studio solution and project files. However,the CMake build system should still work and produce useful results. When usingsome form of MinGW64 toolchain, the CMake build system is considered primaryand the Autotools-based build system is unsupported. Use theMinGW Makefilesoption and build withmingw-make (or similar). TheMSYS Makefiles option isuntested and unsupported.

TheMakefile.am files for this build system are hand-written. Some of them,however, are generated fromMakefile.am.tpl andMakefile.am.def byGNU Autogen. This is to make adding new files to the source easier.

To regenerateMakefile.am files,configure script,testsuite script orany other part of the Autotools build system, use thescripts/doautoreconf.shscript from the source root directory. It will invoke all the necessary tools inthe correct order.

log4cplus closely follows Autoconf's, Automake's and Libtool's developmentand its master branch files are always generated using the latest availableversion of the tools.