From 3d9cdc4450ccebb227babfae9deb3494d2c2afa6 Mon Sep 17 00:00:00 2001 From: Joel Date: Sun, 26 May 2024 13:23:29 -0400 Subject: [PATCH] packaging and doc fixes (#420) Updates and corrects packaging and documentation configurations. These include fixes for cpack generation, the addition of the INSTALL_HEADERS and INSTALL_HTML build options, and fixing all errors. --- CMakeLists.txt | 204 ++++--- ChangeLog.md | 4 +- INSTALL.md | 31 +- README.md | 19 +- docs/examples/socket/socket_example.c | 8 +- include/private/cache.h | 4 +- include/stumpless.h | 108 +++- include/stumpless/config/wel_supported.h | 34 +- include/stumpless/element.h | 6 +- include/stumpless/entry.h | 2 + include/stumpless/error.h | 5 +- include/stumpless/facility.h | 2 +- include/stumpless/generator.h | 13 +- include/stumpless/level/alert.h | 567 ----------------- include/stumpless/level/crit.h | 575 ------------------ include/stumpless/level/debug.h | 569 ----------------- include/stumpless/level/emerg.h | 564 ----------------- include/stumpless/level/err.h | 569 ----------------- include/stumpless/level/info.h | 564 ----------------- .../stumpless/level/{notice.h => level.h.in} | 312 +++++----- include/stumpless/level/mask.h | 6 +- include/stumpless/level/trace.h | 292 +++++---- include/stumpless/level/warning.h | 569 ----------------- include/stumpless/log.h | 6 +- include/stumpless/severity.h | 7 +- include/stumpless/target.h | 34 +- include/stumpless/target/wel.h | 5 +- src/config/have_getaddrinfo.c | 3 +- src/config/have_winsock2.c | 1 + src/entry.c | 2 +- src/target.c | 10 +- test/function/target.cpp | 2 + tools/check_headers/c_standard_library.yml | 4 + tools/check_headers/stumpless_private.yml | 3 + tools/cmake/chain.cmake | 22 +- tools/cmake/cpack.cmake | 29 +- tools/cmake/cpp.cmake | 25 +- tools/cmake/doxygen.cmake | 41 ++ tools/cmake/install_headers.cmake | 54 ++ tools/cmake/install_html.cmake | 5 + tools/cmake/install_manpages.cmake | 8 +- tools/cmake/journald.cmake | 26 +- tools/cmake/l10n.cmake | 15 +- tools/cmake/network.cmake | 14 +- tools/cmake/socket.cmake | 14 +- tools/cmake/sqlite3.cmake | 4 +- tools/cmake/wel.cmake | 22 +- tools/doxygen/CppDoxyfile.in | 8 - tools/doxygen/Doxyfile.in | 15 +- .../{stumpless.pc.in => libstumpless.pc.in} | 4 +- ...pless.ebuild.in => libstumpless.ebuild.in} | 24 +- tools/wrapture/element.yml | 2 + 52 files changed, 883 insertions(+), 4553 deletions(-) delete mode 100644 include/stumpless/level/alert.h delete mode 100644 include/stumpless/level/crit.h delete mode 100644 include/stumpless/level/debug.h delete mode 100644 include/stumpless/level/emerg.h delete mode 100644 include/stumpless/level/err.h delete mode 100644 include/stumpless/level/info.h rename include/stumpless/level/{notice.h => level.h.in} (69%) delete mode 100644 include/stumpless/level/warning.h create mode 100644 tools/cmake/doxygen.cmake create mode 100644 tools/cmake/install_headers.cmake create mode 100644 tools/cmake/install_html.cmake rename tools/pkg-config/{stumpless.pc.in => libstumpless.pc.in} (63%) rename tools/portage/{stumpless.ebuild.in => libstumpless.ebuild.in} (62%) diff --git a/CMakeLists.txt b/CMakeLists.txt index eae691e4a..7a7d9ac51 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -4,7 +4,9 @@ if(POLICY CMP0135) cmake_policy(SET CMP0135 NEW) endif() -project(stumpless VERSION 2.2.0) +project(stumpless + VERSION 2.2.0 +) set(CMAKE_PROJECT_HOMEPAGE_URL "https://goatshriek.github.io/stumpless/") option(BUILD_SHARED_LIBS "Build using shared libraries" ON) @@ -29,6 +31,8 @@ option(ENABLE_SQLITE3_TARGETS "support sqlite3 targets" ON) option(ENABLE_WINDOWS_EVENT_LOG_TARGETS "support windows event log targets" ON) option(INSTALL_EXAMPLES "install examples" ON) +option(INSTALL_HEADERS "install header files" ON) +option(INSTALL_HTML "install html documentation" ON) option(INSTALL_MANPAGES "install generated manpages" ON) option(COVERAGE "Include coverage information" OFF) @@ -259,25 +263,31 @@ set(WRAPTURE_SPECS # documentation and doxygen steup +set(PROJECT_DOCS_DIR "${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}") set(DOXYGEN_MANPAGES - ${PROJECT_BINARY_DIR}/docs/man/man3/stumpless.h.3 - ${PROJECT_BINARY_DIR}/docs/man/man3/config.h.3 + "${PROJECT_DOCS_DIR}/man/man3/stumpless.h.3" + "${PROJECT_DOCS_DIR}/man/man3/config.h.3" ) -set(PROJECT_DOCS_DIR ${PROJECT_BINARY_DIR}/docs) if(DOXYGEN_FOUND) + set(INCLUDE_HTML_IN_INSTALL ${INSTALL_HTML}) set(INCLUDE_MANPAGES_IN_INSTALL ${INSTALL_MANPAGES}) else() + if(INSTALL_HTML) + message("doxygen is required to generate and install html documentation") + endif() + if(INSTALL_MANPAGES) message("doxygen is required to generate and install manpages") endif() + set(INCLUDE_HTML_IN_INSTALL FALSE) set(INCLUDE_MANPAGES_IN_INSTALL FALSE) endif() -if(${INCLUDE_MANPAGES_IN_INSTALL}) +if(${INCLUDE_HTML_IN_INSTALL} OR ${INCLUDE_MANPAGES_IN_INSTALL}) # we need to do this before any other install commands that depend on the - # manpages generated by doxygen, so that they are generated before use + # html or manpages generated by doxygen, so that they are generated before use install(CODE "execute_process(COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target docs)" ) @@ -591,7 +601,6 @@ endif() # library definition add_library(stumpless ${STUMPLESS_SOURCES}) set_target_properties(stumpless PROPERTIES VERSION ${PROJECT_VERSION}) -set_target_properties(stumpless PROPERTIES PUBLIC_HEADER include/stumpless.h) target_link_libraries(stumpless PRIVATE ${STUMPLESS_LINK_LIBRARIES}) @@ -668,8 +677,95 @@ set(FUZZ_CORPORA_DIR ${PROJECT_SOURCE_DIR}/test/corpora) configure_file(${PROJECT_SOURCE_DIR}/include/stumpless/config.h.in ${PROJECT_BINARY_DIR}/include/stumpless/config.h) configure_file(${PROJECT_SOURCE_DIR}/include/private/config.h.in ${PROJECT_BINARY_DIR}/include/private/config.h) configure_file(${PROJECT_SOURCE_DIR}/include/test/config.hpp.in ${PROJECT_BINARY_DIR}/include/test/config.hpp) -configure_file(${PROJECT_SOURCE_DIR}/tools/portage/stumpless.ebuild.in - ${PROJECT_BINARY_DIR}/tools/portage/stumpless-${PROJECT_VERSION}.ebuild +configure_file(${PROJECT_SOURCE_DIR}/tools/portage/libstumpless.ebuild.in + ${PROJECT_BINARY_DIR}/tools/portage/libstumpless-${PROJECT_VERSION}.ebuild + @ONLY +) +configure_file(${PROJECT_SOURCE_DIR}/tools/portage/libstumpless.ebuild.in + ${PROJECT_BINARY_DIR}/tools/portage/libstumpless-9999.ebuild + @ONLY +) + + +# generating level header files +set(LEVEL_NAME_UPCASE "ALERT") +set(LEVEL_NAME_DOWNCASE "alert") +set(LEVEL_SHORTNAME "a") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" + @ONLY +) + +set(LEVEL_NAME_UPCASE "CRIT") +set(LEVEL_NAME_DOWNCASE "crit") +set(LEVEL_SHORTNAME "c") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" + @ONLY +) + +set(LEVEL_NAME_UPCASE "DEBUG") +set(LEVEL_NAME_DOWNCASE "debug") +set(LEVEL_SHORTNAME "d") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" + @ONLY +) + +set(LEVEL_NAME_UPCASE "EMERG") +set(LEVEL_NAME_DOWNCASE "emerg") +set(LEVEL_SHORTNAME "em") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" + @ONLY +) + +set(LEVEL_NAME_UPCASE "ERR") +set(LEVEL_NAME_DOWNCASE "err") +set(LEVEL_SHORTNAME "er") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" + @ONLY +) + +set(LEVEL_NAME_UPCASE "INFO") +set(LEVEL_NAME_DOWNCASE "info") +set(LEVEL_SHORTNAME "i") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" + @ONLY +) + +set(LEVEL_NAME_UPCASE "NOTICE") +set(LEVEL_NAME_DOWNCASE "notice") +set(LEVEL_SHORTNAME "n") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" + @ONLY +) + +set(LEVEL_NAME_UPCASE "WARNING") +set(LEVEL_NAME_DOWNCASE "warning") +set(LEVEL_SHORTNAME "w") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" + @ONLY +) + +set(LEVEL_NAME_UPCASE "TRACE") +set(LEVEL_NAME_DOWNCASE "trace") +set(LEVEL_SHORTNAME "t") +configure_file( + "${PROJECT_SOURCE_DIR}/include/stumpless/level/level.h.in" + "${PROJECT_BINARY_DIR}/include/stumpless/level/${LEVEL_NAME_DOWNCASE}.h" @ONLY ) @@ -682,69 +778,40 @@ install(TARGETS stumpless ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR} ) -install(FILES - ${PROJECT_BINARY_DIR}/include/stumpless/config.h - ${PROJECT_SOURCE_DIR}/include/stumpless/element.h - ${PROJECT_SOURCE_DIR}/include/stumpless/entry.h - ${PROJECT_SOURCE_DIR}/include/stumpless/error.h - ${PROJECT_SOURCE_DIR}/include/stumpless/facility.h - ${PROJECT_SOURCE_DIR}/include/stumpless/filter.h - ${PROJECT_SOURCE_DIR}/include/stumpless/generator.h - ${PROJECT_SOURCE_DIR}/include/stumpless/id.h - ${PROJECT_SOURCE_DIR}/include/stumpless/log.h - ${PROJECT_SOURCE_DIR}/include/stumpless/memory.h - ${PROJECT_SOURCE_DIR}/include/stumpless/option.h - ${PROJECT_SOURCE_DIR}/include/stumpless/param.h - ${PROJECT_SOURCE_DIR}/include/stumpless/severity.h - ${PROJECT_SOURCE_DIR}/include/stumpless/target.h - ${PROJECT_SOURCE_DIR}/include/stumpless/version.h - ${PROJECT_SOURCE_DIR}/include/stumpless/priority.h - ${PROJECT_SOURCE_DIR}/include/stumpless/prival.h - DESTINATION "include/stumpless" -) - -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/level/alert.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/crit.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/debug.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/emerg.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/err.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/info.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/mask.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/notice.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/trace.h - ${PROJECT_SOURCE_DIR}/include/stumpless/level/warning.h - DESTINATION "include/stumpless/level" -) - -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/target/buffer.h - ${PROJECT_SOURCE_DIR}/include/stumpless/target/file.h - ${PROJECT_SOURCE_DIR}/include/stumpless/target/function.h - ${PROJECT_SOURCE_DIR}/include/stumpless/target/sqlite3.h - ${PROJECT_SOURCE_DIR}/include/stumpless/target/stream.h - DESTINATION "include/stumpless/target" -) +if(INSTALL_HEADERS) + include(tools/cmake/install_headers.cmake) +endif() include(tools/cmake/cpack.cmake) include(FindPkgConfig QUIET) if(PKG_CONFIG_FOUND) - configure_file("${PROJECT_SOURCE_DIR}/tools/pkg-config/stumpless.pc.in" "${PROJECT_BINARY_DIR}/tools/pkg-config/stumpless.pc" @ONLY) - install(FILES "${PROJECT_BINARY_DIR}/tools/pkg-config/stumpless.pc" - DESTINATION "${CMAKE_INSTALL_PREFIX}/lib/pkgconfig") + configure_file( + "${PROJECT_SOURCE_DIR}/tools/pkg-config/libstumpless.pc.in" + "${PROJECT_BINARY_DIR}/tools/pkg-config/libstumpless.pc" + @ONLY + ) + + install(FILES "${PROJECT_BINARY_DIR}/tools/pkg-config/libstumpless.pc" + DESTINATION "${CMAKE_INSTALL_LIBDIR}/pkgconfig") endif() # installation of examples if enabled if(INSTALL_EXAMPLES) - install(DIRECTORY - ${PROJECT_SOURCE_DIR}/docs/examples - DESTINATION ${CMAKE_INSTALL_DOCDIR} + install( + DIRECTORY "${PROJECT_SOURCE_DIR}/docs/examples" + DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/doc/libstumpless" ) endif() +# installation of html if enabled and supported +if(INCLUDE_HTML_IN_INSTALL) + include(tools/cmake/install_html.cmake) +endif() + + # installation of manpages if enabled and supported if(INCLUDE_MANPAGES_IN_INSTALL) include(tools/cmake/install_manpages.cmake) @@ -1192,24 +1259,5 @@ endif() # doxygen build target if(DOXYGEN_FOUND) - configure_file(${PROJECT_SOURCE_DIR}/tools/doxygen/Doxyfile.in ${PROJECT_BINARY_DIR}/tools/doxygen/Doxyfile) - - file(GLOB_RECURSE DOXYGEN_PUBLIC_HEADERS ${DOXYGEN_INCLUDE_DIR}/stumpless/*.h) - set(EXAMPLE_SOURCES - ${PROJECT_SOURCE_DIR}/docs/examples/basic/basic_example.c - ) - - add_custom_command( - OUTPUT ${DOXYGEN_MANPAGES} - COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/tools/doxygen/Doxyfile - MAIN_DEPENDENCY ${PROJECT_BINARY_DIR}/tools/doxygen/Doxyfile - DEPENDS - ${DOXYGEN_PUBLIC_HEADERS} - ${EXAMPLE_SOURCES} - ${DOXYGEN_INCLUDE_DIR}/stumpless.h - ${PROJECT_BINARY_DIR}/include/stumpless/config.h - VERBATIM - ) - - add_custom_target(docs DEPENDS ${DOXYGEN_MANPAGES}) + include(tools/cmake/doxygen.cmake) endif() diff --git a/ChangeLog.md b/ChangeLog.md index 38b2aa880..b2f8ec171 100644 --- a/ChangeLog.md +++ b/ChangeLog.md @@ -9,12 +9,14 @@ fixes, check out the [roadmap](https://github.com/goatshriek/stumpless/blob/master/docs/roadmap.md). -## [2.2.0] - 2024-03-30 +## [2.2.0] - 2024-05-26 ### Added - @since format check enforcement in CI pipeline. - `single-file` target for rollup `.c` and `.h` files. - SQLite3 logging targets. - Target chains. + - Support for `pkg-config`. + - `INSTALL_HEADERS` and `INSTALL_HTML` build options. - Localizations for: * Albanian (sq-AL :albania:) * Danish (da-DK :denmark:) diff --git a/INSTALL.md b/INSTALL.md index 5ac365a1e..69bd2bb60 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -10,6 +10,17 @@ Stumpless is not currently registered in any online package repositories such as Chocolatey or Debian. If you need the library in a location like this, please open an issue and the project team will see what we can do. +The provided release packages contain all of the items in the following list. +If you want a package with only a selection of these items, you'll need to build +it yourself using `cpack` and the appropriate configuration. + + * shared library + * header files + * `.pc` file for `pkg-config` implementations + * examples + * HTML documentation + * man pages + ## Debian Package A `.deb` package is provided for use in environments that support them, like @@ -17,7 +28,7 @@ Debian and Ubuntu. The package can be installed with the usual command: ```sh # you might need sudo (or root privileges) to install -dpkg -i stumpless-2.2.0-amd64.deb +dpkg -i libstumpless-2.2.0-amd64.deb ``` @@ -27,7 +38,17 @@ installed in the traditional way as well: ```sh # again, make sure you have the correct permissions -rpm -i stumpless-2.2.0-x86_64.rpm +rpm -i libstumpless-2.2.0-x86_64.rpm +``` + + +## FreeBSD Package +A `.pkg` package is provided for use in FreeBSD environments. Of course, it is +installed just as any other pkg would be: + +```sh +# permissions need to be correct, of course +pkg add libstumpless-2.2.0-amd64.pkg ``` @@ -38,7 +59,7 @@ generated ebuild is in the `tools/portage` folder of the build directory. The generated ebuild will be named after the version of stumpless you have. If you want the latest commit instead of a release, you'll need to rename this -to version `stumpless-9999.ebuild` to perform what Gentoo refers to as a +to version `libstumpless-9999.ebuild` to perform what Gentoo refers to as a [live ebuild](https://wiki.gentoo.org/wiki/Ebuild#Live_ebuilds). If you have a commit in a release that hasn't been published yet and do not rename the ebuild, then the download of the source will fail. @@ -47,7 +68,7 @@ In either case, you could install the ebuild by putting it into a repository and running ebuild ultimately as something like: ```sh -ebuild stumpless-2.2.0.ebuild clean install merge +ebuild libstumpless-2.2.0.ebuild clean manifest install merge ``` USE flags and other customizations can be done here as well. Gentoo installs are @@ -66,7 +87,7 @@ files. # you might need to do this with sudo! # make sure your permissions allow you to write to the install locations cd /usr -./stumpless-2.2.0.sh +./libstumpless-2.2.0.sh ``` diff --git a/README.md b/README.md index 1c4c50aac..d6e8b8358 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Stumpless has lots of features that make logging in C fast and easy: * log to [lots of things](#what-can-it-log-to) like Splunk, rsyslog, journald, the Windows Event Log, sqlite, and more! * structured and unstructured logging to suit your needs - * builds on Linux, Windows, Mac, MinGW, MSYS2, Cygwin, DOS, and more + * builds on Linux, Windows, Mac, FreeBSD, MinGW, MSYS2, Cygwin, DOS, and more! * thread safe * can be adjusted or removed during compilation for zero runtime cost * localized for multiple languages :albania: :brazil: :bulgaria: :cn: @@ -45,11 +45,11 @@ a wide variety of log targets. This means you can focus on defining events and where you want them to go, without finding other SDKs or adding daemons and plugins to get them where you want. Stumpless can write logs to: * Simple character buffers - * Files and Streams + * Files and streams * Unix sockets (such as a local syslog daemon) - * Network Servers (IPv4 or IPv6, TCP or UDP) - * Systemd Journald Service - * Sqlite3 Databases + * Network servers (IPv4 or IPv6, TCP or UDP) + * Systemd Journald service + * Sqlite3 databases * Windows Event Log * Custom functions, for whatever else you may need! @@ -95,7 +95,7 @@ replacement for the standard library's `syslog` function: // if you're used to doing this: syslog( LOG_INFO | LOG_USER, "My message #%d", count ); -// then you can start doing this: +// then you can start by changing to this: stumplog( LOG_INFO | LOG_USER, "My message #%d", count ); ``` @@ -236,6 +236,13 @@ is also hosted on the [project website](https://goatshriek.github.io/stumpless/), for both the C library as well as the other language bindings like C++. +Stumpless also includes documentation in local installations in the form of +`man` pages. Once you've installed the library, you can check the documentation +for any header file (and the functions it contains) by running man with the +name of the header with directories replaced with underscores, for example +`man stumpless_log.h` to see documentation for functions that log simple string +messages. + There are also plenty of ways that you can reach out to the project team and broader community for support. * [Issues](https://github.com/goatshriek/stumpless/issues) and diff --git a/docs/examples/socket/socket_example.c b/docs/examples/socket/socket_example.c index 1c33b8402..62f78109c 100644 --- a/docs/examples/socket/socket_example.c +++ b/docs/examples/socket/socket_example.c @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 /* - * Copyright 2019-2021 Joel E. Anderson + * Copyright 2019-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -22,7 +22,7 @@ int main( int argc, char **argv ) { - const char *socket = "/dev/log"; + const char *socket_name = "/dev/log"; struct stumpless_entry *entry; struct stumpless_element *element; struct stumpless_entry *entry_result; @@ -61,7 +61,7 @@ main( int argc, char **argv ) { // opening the target is straightforward - socket_target = stumpless_open_socket_target( socket, + socket_target = stumpless_open_socket_target( socket_name, // making this argument NULL // means that a randomized local // socket will be created @@ -74,7 +74,7 @@ main( int argc, char **argv ) { // if you want to specify the local socket used to connect to the target // socket, then you can specify it in the local_socket parameter - manual_target = stumpless_open_socket_target( socket, "logfromthis" ); + manual_target = stumpless_open_socket_target( socket_name, "logfromthis" ); if( !manual_target ) { stumpless_perror( "couldn't create a new socket target with a manual local" " socket" ); diff --git a/include/private/cache.h b/include/private/cache.h index b7d00deae..e776b7844 100644 --- a/include/private/cache.h +++ b/include/private/cache.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2018-2020 Joel E. Anderson + * Copyright 2018-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -28,7 +28,7 @@ struct cache { void ( *entry_teardown ) ( void * ); size_t entry_size; char **pages; - int page_count; + size_t page_count; size_t page_size; # ifdef STUMPLESS_THREAD_SAFETY_SUPPORTED config_mutex_t mutex; diff --git a/include/stumpless.h b/include/stumpless.h index cd8759b0d..dba9eed4b 100644 --- a/include/stumpless.h +++ b/include/stumpless.h @@ -18,8 +18,112 @@ /** @mainpage Stumpless * - * Stumpless is a logging library built for high performance and a rich feature - * set. + * Stumpless is a C logging library built for high performance and a rich + * feature set. + * + * \section basic-usage Basic Usage + * The simplest way to get started is to use the `stumplog` function as a direct + * replacement for the standard library's `syslog` function: + * + * \code{.c} + * // if you're used to doing this: + * syslog( LOG_INFO | LOG_USER, "My message #%d", count ); + * + * // then you can start by changing to this: + * stumplog( LOG_INFO | LOG_USER, "My message #%d", count ); + * \endcode + * + * If you haven't opened a target, this will log messages to the default target + * for the platform: on Linux this is \c /dev/log, on a Mac system this will be + * \c /var/run/syslog, and on a Windows machine it is the Windows Event Log. If + * you open a target or even a few before calling `stumplog`, then logs will be + * sent to the most recently opened target. + * + * If you want an even shorter function call, you can use the stump() function + * to send a message to the current target. You can also use format specifiers + * just as you would with \c printf. + * + * \code{.c} + * stump( "Login attempt failure #%d for user %s", count, username ); + * \endcode + * + * If you don't need format specifiers, use one of the \c _str variants such as + * stump_str(): it's both faster and safer! + * + * \code{.c} + * stump_str( "Login failure! See structured data for info." ); + * \endcode + * + * If you want to open a specific target rather than using the default, then + * just open the one you need and start sending messages. For example, to log to + * a file named \c example.log + * + * \code{.c} + * target = stumpless_open_file_target( "example.log" ); + * + * // uses the last opened target by default + * stump( "Login attempt failure #%d for user %s", count, username ); + * \endcode + * + * Sending messages over the network to something like Splunk or rsyslog is just + * as easy: + * + * \code{.c} + * target = stumpless_open_udp4_target( "send-to-splunk-example", + * "mylogserver.com" ); // or use an IP + * stump( "Login attempt failure #%d for user %s", count, username ); + * \endcode + * + * If you have multiple targets, you can send messages to a chosen target like + * this: + * + * \code{.c} + * stumpless_add_message( target, + * "Login attempt failure #%d for user %s", + * count, + * username ); + * \endcode + * + * \section severity-shorthand Severity Shorthand + * It's common to specify severity levels directly in logging calls, so + * stumpless provides some macro functions to make this less verbose and more + * efficient. For example, to log messages with a severity of INFO, you can do + * this: + * + * \code{.c} + * stump_i( "this gets logged as an info message" ); + * \endcode + * + * And if you want to also see source file, line number, and function name info + * in each message you can use stump_t() (the 't' is for trace): + * + * \code{.c} + * stump_t( "this includes source info" ); + * \endcode + * + * Using these functions has the added benefit that they can be removed at + * compile time by simply defining the proper \c STUMPLESS_ENABLE_UPTO or + * \c STUMPLESS_DISABLE_DOWNTO symbols. This makes it easy to change logging + * levels between builds, for example to have prod and debug versions without + * differences in their source code. + * + * \code{.c} + * // be sure to define this before stumpless.h gets included + * #define STUMPLESS_ENABLE_UPTO_INFO + * + * // ... + * + * // this log will go through just fine + * stump_i( "I'm doing that thing you asked" ); + * + * // this debugging message is completely removed: no runtime impact whatsoever + * stump_d( "DEBUG info: %d, %d, %s", thing_1, thing_2, stringy_thingy ); + * \endcode + * + * Check out the headers in the stumpless/level include directory named after + * a severity level such as \ref alert.h to see the full list of severity + * shorthand functions, or \ref severity_level_example.c to see a + * complete program in action. */ /** @example basic_example.c diff --git a/include/stumpless/config/wel_supported.h b/include/stumpless/config/wel_supported.h index 93473f76a..0736fc704 100644 --- a/include/stumpless/config/wel_supported.h +++ b/include/stumpless/config/wel_supported.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2018-2022 Joel E. Anderson + * Copyright 2018-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -45,10 +45,10 @@ extern "C" { * * Specifically, the following registry subkey is created, or modified if it * already exists: - * HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Stumpless + * HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\EventLog\\Stumpless * - * This key is given the following registry values: - * Sources: "Stumpless" as an entry, assuming it is a REG_MULTI_SZ. + * The "Sources" subkey of this entry has "Stumpless" added to it, assuming it + * is a \c REG_MULTI_SZ type if it already exists. * * If an existing Sources key is already present and is not correctly formatted * with NULL terminating characters as required by a MULTI_SZ, then this call @@ -56,10 +56,10 @@ extern "C" { * * A subkey is also created within this key named "Stumpless", with the * following values set in it: - * CategoryCount: 8 (one category is present for each severity in RFC 5424) - * CategoryMessageFile: Points to the image containing stumpless. - * EventMessageFile: Points to the image containing stumpless. - * TypesSupported: 0x1f (all event types are allowed). + * - CategoryCount: 8 (one category is present for each severity in RFC 5424) + * - CategoryMessageFile: Points to the image containing stumpless. + * - EventMessageFile: Points to the image containing stumpless. + * - TypesSupported: 0x1f (all event types are allowed). * * This call is semantically equivalent to stumpless_add_wel_event_source_w( * L"Stumpless", L"Stumpless", 8, L"stumpless.dll", L"stumpless.dll", NULL, @@ -127,8 +127,8 @@ stumpless_add_default_wel_event_source( void ); * * @param subkey_name The name of the subkey that the source should be added to, * as a UTF-8 NULL terminated string. This subkey will be created under - * HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog. This name may - * contain backslashes to nest the key under other subkeys. + * HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\EventLog. This name + * may contain backslashes to nest the key under other subkeys. * * @param source_name The name of the event source, as a UTF-8 NULL terminated * string. This will be added to the "Sources" value of the subkey, and created @@ -203,8 +203,8 @@ stumpless_add_wel_event_source( LPCSTR subkey_name, * * @param subkey_name The name of the subkey that the source should be added to, * as a wide char NULL terminated string. This subkey will be created under - * HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog. This name may - * contain backslashes to nest the key under other subkeys. + * HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\EventLog. This name + * may contain backslashes to nest the key under other subkeys. * * @param source_name The name of the event source, as a wide char NULL * terminated string. This will be added to the "Sources" value of the subkey, @@ -453,7 +453,7 @@ stumpless_get_wel_type( const struct stumpless_entry *entry ); * Removes the registry entries for the event source for default WEL entries. * * Specifically, the following registry subkey and all subkeys are deleted: - * HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Stumpless + * HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\EventLog\\Stumpless * * This call is semantically equivalent to * stumpless_remove_wel_event_source_w( L"Stumpless", L"Stumpless" ). @@ -499,8 +499,8 @@ stumpless_remove_default_wel_event_source( void ); * * @param subkey_name The name of the subkey that the source is installed in, * as a UTF-8 NULL terminated string. This subkey will be looked for under - * HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog. This name may - * contain backslashes to nest the key under other subkeys. + * HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\EventLog. This name + * may contain backslashes to nest the key under other subkeys. * * @param source_name The name of the event source, as a UTF-8 NULL terminated * string. This will be removed from the "Sources" value of the subkey, and then @@ -533,8 +533,8 @@ stumpless_remove_wel_event_source( LPCSTR subkey_name, * * @param subkey_name The name of the subkey that the source is installed in, * as a wide char NULL terminated string. This subkey will be looked for under - * HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog. This name may - * contain backslashes to nest the key under other subkeys. + * HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Services\\EventLog. This name + * may contain backslashes to nest the key under other subkeys. * * @param source_name The name of the event source, as a wide char NULL * terminated string. This will be removed from the "Sources" value of the diff --git a/include/stumpless/element.h b/include/stumpless/element.h index d3f9674fd..f6e239189 100644 --- a/include/stumpless/element.h +++ b/include/stumpless/element.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2018-2022 Joel E. Anderson + * Copyright 2018-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -143,8 +143,8 @@ struct stumpless_element { /** * Creates a new param and adds it to the given element. * - * This is equivalent to calling stumpless_new_param and passing the result - * directly stumpless_add_param. + * This is equivalent to calling stumpless_new_param() and passing the result + * directly stumpless_add_param(). * * **Thread Safety: MT-Safe race:param_name race:param_value** * This function is thread safe, of course assuming that the param name and diff --git a/include/stumpless/entry.h b/include/stumpless/entry.h index 9812c16fa..bcea3bbf7 100644 --- a/include/stumpless/entry.h +++ b/include/stumpless/entry.h @@ -961,6 +961,8 @@ stumpless_load_entry( struct stumpless_entry *entry, * * @since release v2.2.0 * + * @param entry The entry structure to load with the given fields. + * * @param facility The facility code of the event this entry describes. This * should be a \c STUMPLESS_FACILITY value. * diff --git a/include/stumpless/error.h b/include/stumpless/error.h index c5ce9b08c..a80ad87f7 100644 --- a/include/stumpless/error.h +++ b/include/stumpless/error.h @@ -165,10 +165,11 @@ extern "C" { * different ultimate cause. To completely diagnose a problem, you will need * to look at more than just the error id. * - * @note The real implementation of enum values is now moved under `STUMPLESS_FOREACH_ERROR(ERROR)` macro. + * See STUMPLESS_FOREACH_ERROR() and STUMPLESS_GENERATE_ENUM() for how this + * enumeration is generated. */ enum stumpless_error_id { - STUMPLESS_FOREACH_ERROR(STUMPLESS_GENERATE_ENUM) + STUMPLESS_FOREACH_ERROR( STUMPLESS_GENERATE_ENUM ) }; diff --git a/include/stumpless/facility.h b/include/stumpless/facility.h index d43f144a0..256269e50 100644 --- a/include/stumpless/facility.h +++ b/include/stumpless/facility.h @@ -339,7 +339,7 @@ extern "C" { /** * All possible facility codes available to log entries. * - * In versions prior to 2.0.0, these values were simply #define symbols. They + * In versions prior to 2.0.0, these values were simply \#define symbols. They * have been changed to an enum to clearly convey proper usage. * * @since release v2.0.0. diff --git a/include/stumpless/generator.h b/include/stumpless/generator.h index b1307da7a..9429082b4 100644 --- a/include/stumpless/generator.h +++ b/include/stumpless/generator.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2020 Joel E. Anderson + * Copyright 2020-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,19 +17,20 @@ */ /** @file - * The identification for targets within the library. + * Generic functionality to be used with STUMPLESS_FOREACH macros to allow for + * more generic definition of enumerations and to string functions. */ #ifndef __STUMPLESS_GENERATOR_H -# define __STUMPLESS_GENERATOR_H +#define __STUMPLESS_GENERATOR_H /** * Returns a definition of a symbol with the given name and value fit for use in - * an enum definition. Compatible with STUMPLESS_FOREACH macro functions such as - * STUMPLESS_FOREACH_FACILITY. + * an enum definition. Compatible with \c STUMPLESS_FOREACH_ macro functions + * such as STUMPLESS_FOREACH_FACILITY(). * * @since release v2.0.0. */ -# define STUMPLESS_GENERATE_ENUM( NAME, VALUE ) NAME = ( VALUE ), +#define STUMPLESS_GENERATE_ENUM( NAME, VALUE ) NAME = ( VALUE ), #endif /* __STUMPLESS_GENERATOR_H */ diff --git a/include/stumpless/level/alert.h b/include/stumpless/level/alert.h deleted file mode 100644 index d58c255fe..000000000 --- a/include/stumpless/level/alert.h +++ /dev/null @@ -1,567 +0,0 @@ -/* SPDX-License-Identifier: Apache-2.0 */ - -/* - * Copyright 2020-2023 Joel E. Anderson - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** @file - * Macro functions that log messages and entries at the alert level. - * - * These can be turned into no-ops at compile time by defining - * STUMPLESS_DISABLE_ALERT_LEVEL during build, or at least before inclusion of - * this header (or stumpless.h). - */ - -#ifndef __STUMPLESS_LEVEL_ALERT_H -# define __STUMPLESS_LEVEL_ALERT_H - -# include - -# ifndef STUMPLESS_DISABLE_ALERT_LEVEL -# include -# include -# include -# include -# endif - -/** - * Logs a message to the current target with alert severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_ALERT, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_a instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_a_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stump_a( ... ) ( 0 ) -# else -# define stump_a( ... ) \ -stumpless_add_log( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_ALERT | STUMPLESS_DEFAULT_FACILITY, \ - __VA_ARGS__ ) -# endif - -/** - * Logs a message to the current target with alert severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_ALERT, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_a instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stump_a_str( message ) ( 0 ) -# else -# define stump_a_str( message ) \ -stumpless_add_log_str( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_ALERT | STUMPLESS_DEFAULT_FACILITY, \ - ( message ) ) -# endif - -/** - * Adds an entry to a given target with alert severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * This call does not override the severity of the entry itself. Rather, it is - * intended to allow logging calls to be removed at compile time if the severity - * is known ahead of time. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. - * - * **Async Cancel Safety: AC-Unsafe lock** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked. - * - * @param target The target to send the entry to. - * - * @param entry The entry to send to the target. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stump_a_entry( target, entry ) ( 0 ) -# else -# define stump_a_entry( target, entry ) \ -stumpless_add_entry( ( target ), ( entry ) ) -# endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_a_log_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stump_a_log( target, priority, ... ) ( 0 ) -# else -# define stump_a_log( target, priority, ... ) \ -stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) -#endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stump_a_log_str( target, priority, message ) ( 0 ) -# else -# define stump_a_log_str( target, priority, message ) \ -stumpless_add_log_str( ( target ), ( priority ), ( message ) ) -#endif - -/** - * Adds a message to a given target with alert severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_ALERT, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_a_log instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_a_message_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stump_a_message( target, ... ) ( 0 ) -# else -# define stump_a_message( target, ... ) \ -stumpless_add_log( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_ALERT, \ - __VA_ARGS__ ) -# endif - -/** - * Adds a message to a given target with alert severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_ALERT, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_a_log instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stump_a_message_str( target, message ) ( 0 ) -# else -# define stump_a_message_str( target, message ) \ -stumpless_add_log_str( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_ALERT, \ - ( message ) ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stumplog_a_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stumplog_a( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_a( priority, ... ) stumplog( ( priority ), __VA_ARGS__ ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ALERT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with alert level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - */ -# ifdef STUMPLESS_DISABLE_ALERT_LEVEL -# define stumplog_a_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_a_str( priority, message ) \ -stumplog_str( ( priority ), ( message ) ) -# endif - -#endif /* __STUMPLESS_LEVEL_ALERT_H */ diff --git a/include/stumpless/level/crit.h b/include/stumpless/level/crit.h deleted file mode 100644 index d1fd7464e..000000000 --- a/include/stumpless/level/crit.h +++ /dev/null @@ -1,575 +0,0 @@ -/* SPDX-License-Identifier: Apache-2.0 */ - -/* - * Copyright 2020-2023 Joel E. Anderson - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** @file - * Macro functions that log messages and entries at the critical level. - * - * These can be turned into no-ops at compile time by defining - * STUMPLESS_DISABLE_CRIT_LEVEL during build, or at least before inclusion of - * this header (or stumpless.h). - */ - -#ifndef __STUMPLESS_LEVEL_CRIT_H -# define __STUMPLESS_LEVEL_CRIT_H - -# include - -# ifndef STUMPLESS_DISABLE_CRIT_LEVEL -# include -# include -# include -# include -# endif - -/** - * Logs a message to the current target with critical severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_CRIT, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_c instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_c_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stump_c( ... ) ( 0 ) -# else -# define stump_c( ... ) \ -stumpless_add_log( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_CRIT | STUMPLESS_DEFAULT_FACILITY, \ - __VA_ARGS__ ) -# endif - -/** - * Logs a message to the current target with critical severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_CRIT, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_c instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_c_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stump_c_str( message ) ( 0 ) -# else -# define stump_c_str( message ) \ -stumpless_add_log_str( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_CRIT | STUMPLESS_DEFAULT_FACILITY, \ - ( message ) ) -# endif - -/** - * Adds an entry to a given target with critical severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * This call does not override the severity of the entry itself. Rather, it is - * intended to allow logging calls to be removed at compile time if the severity - * is known ahead of time. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. - * - * **Async Cancel Safety: AC-Unsafe lock** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked. - * - * @param target The target to send the entry to. - * - * @param entry The entry to send to the target. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stump_c_entry( target, entry ) ( 0 ) -# else -# define stump_c_entry( target, entry ) \ -stumpless_add_entry( ( target ), ( entry ) ) -# endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_c_log_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stump_c_log( target, priority, ... ) ( 0 ) -# else -# define stump_c_log( target, priority, ... ) \ -stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) -#endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stump_c_log_str( target, priority, message ) ( 0 ) -# else -# define stump_c_log_str( target, priority, message ) \ -stumpless_add_log_str( ( target ), ( priority ), ( message ) ) -#endif - -/** - * Adds a message to a given target with critical severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_CRIT, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_c_log instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_c_message_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stump_c_message( target, ... ) ( 0 ) -# else -# define stump_c_message( target, ... ) \ -stumpless_add_log( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_CRIT, \ - __VA_ARGS__ ) -# endif - -/** - * Adds a message to a given target with critical severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_CRIT, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_c_log instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stump_c_message_str( target, message ) ( 0 ) -# else -# define stump_c_message_str( target, message ) \ -stumpless_add_log_str( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_CRIT, \ - ( message ) ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stumplog_c_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stumplog_c( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_c( priority, ... ) stumplog( ( priority ), __VA_ARGS__ ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_CRIT_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with critical level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - */ -# ifdef STUMPLESS_DISABLE_CRIT_LEVEL -# define stumplog_c_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_c_str( priority, message ) \ -stumplog_str( ( priority ), ( message ) ) -# endif - -#endif /* __STUMPLESS_LEVEL_CRIT_H */ diff --git a/include/stumpless/level/debug.h b/include/stumpless/level/debug.h deleted file mode 100644 index 693e1c51f..000000000 --- a/include/stumpless/level/debug.h +++ /dev/null @@ -1,569 +0,0 @@ -/* SPDX-License-Identifier: Apache-2.0 */ - -/* - * Copyright 2020-2023 Joel E. Anderson - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** @file - * Macro functions that log messages and entries at the debug level. - * - * These can be turned into no-ops at compile time by defining - * STUMPLESS_DISABLE_DEBUG_LEVEL during build, or at least before inclusion of - * this header (or stumpless.h). - */ - -#ifndef __STUMPLESS_LEVEL_DEBUG_H -# define __STUMPLESS_LEVEL_DEBUG_H - -# include - -# ifndef STUMPLESS_DISABLE_DEBUG_LEVEL -# include -# include -# include -# include -# endif - -/** - * Logs a message to the current target with debug severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_DEBUG, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_d instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_d_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stump_d( ... ) ( 0 ) -# else -# define stump_d( ... ) \ -stumpless_add_log( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_DEBUG | STUMPLESS_DEFAULT_FACILITY, \ - __VA_ARGS__ ) -# endif - -/** - * Logs a message to the current target with debug severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_DEBUG, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_d instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stump_d_str( message ) ( 0 ) -# else -# define stump_d_str( message ) \ -stumpless_add_log_str( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_DEBUG | STUMPLESS_DEFAULT_FACILITY, \ - ( message ) ) -# endif - -/** - * Adds an entry to a given target with debug severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * This call does not override the severity of the entry itself. Rather, it is - * intended to allow logging calls to be removed at compile time if the severity - * is known ahead of time. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. - * - * **Async Cancel Safety: AC-Unsafe lock** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked. - * - * @param target The target to send the entry to. - * - * @param entry The entry to send to the target. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stump_d_entry( target, entry ) ( 0 ) -# else -# define stump_d_entry( target, entry ) \ -stumpless_add_entry( ( target ), ( entry ) ) -# endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_d_log_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stump_d_log( target, priority, ... ) ( 0 ) -# else -# define stump_d_log( target, priority, ... ) \ -stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) -#endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stump_d_log_str( target, priority, message ) ( 0 ) -# else -# define stump_d_log_str( target, priority, message ) \ -stumpless_add_log_str( ( target ), ( priority ), ( message ) ) -#endif - -/** - * Adds a message to a given target with debug severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_DEBUG, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_d_log instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_d_message_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stump_d_message( target, ... ) ( 0 ) -# else -# define stump_d_message( target, ... ) \ -stumpless_add_log( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_DEBUG, \ - __VA_ARGS__ ) -# endif - -/** - * Adds a message to a given target with debug severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_DEBUG, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_d_log instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stump_d_message_str( target, message ) ( 0 ) -# else -# define stump_d_message_str( target, message ) \ -stumpless_add_log_str( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_DEBUG, \ - ( message ) ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stumplog_d_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stumplog_d( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_d( priority, ... ) stumplog( ( priority ), __VA_ARGS__ ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_DEBUG_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - */ -# ifdef STUMPLESS_DISABLE_DEBUG_LEVEL -# define stumplog_d_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_d_str( priority, message ) \ -stumplog_str( ( priority ), ( message ) ) -# endif - -#endif /* __STUMPLESS_LEVEL_DEBUG_H */ diff --git a/include/stumpless/level/emerg.h b/include/stumpless/level/emerg.h deleted file mode 100644 index f85600e46..000000000 --- a/include/stumpless/level/emerg.h +++ /dev/null @@ -1,564 +0,0 @@ -/* SPDX-License-Identifier: Apache-2.0 */ - -/* - * Copyright 2020-2023 Joel E. Anderson - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** @file - * Macro functions that log messages and entries at the emergency level. - * - * These can be turned into no-ops at compile time by defining - * STUMPLESS_DISABLE_EMERG_LEVEL during build, or at least before inclusion of - * this header (or stumpless.h). - */ - -#ifndef __STUMPLESS_LEVEL_EMERG_H -# define __STUMPLESS_LEVEL_EMERG_H - -# include - -# ifndef STUMPLESS_DISABLE_EMERG_LEVEL -# include -# include -# include -# include -# endif - -/** - * Logs a message to the current target with emergency severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumpless_add_log with the provided message and calculated - * priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_EMERG, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_em instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_em_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stump_em( ... ) ( 0 ) -# else -# define stump_em( ... ) \ -stumpless_add_log( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_EMERG | STUMPLESS_DEFAULT_FACILITY, \ - __VA_ARGS__ ) -# endif - -/** - * Logs a message to the current target with emergency severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumpless_add_log with the provided message and calculated - * priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_EMERG, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_em instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stump_em_str( message ) ( 0 ) -# else -# define stump_em_str( message ) \ -stumpless_add_log_str( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_EMERG | STUMPLESS_DEFAULT_FACILITY, \ - ( message ) ) -# endif - -/** - * Adds an entry to a given target with emergency severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * This call does not override the severity of the entry itself. Rather, it is - * intended to allow logging calls to be removed at compile time if the severity - * is known ahead of time. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. - * - * **Async Cancel Safety: AC-Unsafe lock** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked. - * - * @param target The target to send the entry to. - * - * @param entry The entry to send to the target. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stump_em_entry( target, entry ) ( 0 ) -# else -# define stump_em_entry( target, entry ) \ -stumpless_add_entry( ( target ), ( entry ) ) -# endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_em_log_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stump_em_log( target, priority, ... ) ( 0 ) -# else -# define stump_em_log( target, priority, ... ) \ -stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) -#endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stump_em_log_str( target, priority, message ) ( 0 ) -# else -# define stump_em_log_str( target, priority, message ) \ -stumpless_add_log_str( ( target ), ( priority ), ( message ) ) -#endif - -/** - * Adds a message to a given target with emergency severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumpless_add_log with the provided message and calculated - * priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_EMERG, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_em_log instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_em_message_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stump_em_message( target, ... ) ( 0 ) -# else -# define stump_em_message( target, ... ) \ -stumpless_add_log( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_EMERG, \ - __VA_ARGS__ ) -# endif - -/** - * Adds a message to a given target with emergency severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumpless_add_log with the provided message and calculated - * priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_EMERG, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_em_log instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stump_em_message_str( target, message ) ( 0 ) -# else -# define stump_em_message_str( target, message ) \ -stumpless_add_log_str( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_EMERG, \ - ( message ) ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stumplog_em_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stumplog_em( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_em( priority, ... ) stumplog( ( priority ), __VA_ARGS__ ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_EMERG_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with emerg level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - */ -# ifdef STUMPLESS_DISABLE_EMERG_LEVEL -# define stumplog_em_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_em_str( priority, message ) \ -stumplog_str( ( priority ), ( message ) ) -# endif - -#endif /* __STUMPLESS_LEVEL_EMERG_H */ diff --git a/include/stumpless/level/err.h b/include/stumpless/level/err.h deleted file mode 100644 index a461e4b81..000000000 --- a/include/stumpless/level/err.h +++ /dev/null @@ -1,569 +0,0 @@ -/* SPDX-License-Identifier: Apache-2.0 */ - -/* - * Copyright 2020-2023 Joel E. Anderson - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** @file - * Macro functions that log messages and entries at the err level. - * - * These can be turned into no-ops at compile time by defining - * STUMPLESS_DISABLE_ERR_LEVEL during build, or at least before inclusion of - * this header (or stumpless.h). - */ - -#ifndef __STUMPLESS_LEVEL_ERR_H -# define __STUMPLESS_LEVEL_ERR_H - -# include - -# ifndef STUMPLESS_DISABLE_ERR_LEVEL -# include -# include -# include -# include -# endif - -/** - * Logs a message to the current target with err severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_ERR, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_er instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_er_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stump_er( ... ) ( 0 ) -# else -# define stump_er( ... ) \ -stumpless_add_log( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_ERR | STUMPLESS_DEFAULT_FACILITY, \ - __VA_ARGS__ ) -# endif - -/** - * Logs a message to the current target with err severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_ERR, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_er instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stump_er_str( message ) ( 0 ) -# else -# define stump_er_str( message ) \ -stumpless_add_log_str( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_ERR | STUMPLESS_DEFAULT_FACILITY, \ - ( message ) ) -# endif - -/** - * Adds an entry to a given target with err severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * This call does not override the severity of the entry itself. Rather, it is - * intended to allow logging calls to be removed at compile time if the severity - * is known ahead of time. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. - * - * **Async Cancel Safety: AC-Unsafe lock** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked. - * - * @param target The target to send the entry to. - * - * @param entry The entry to send to the target. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stump_er_entry( target, entry ) ( 0 ) -# else -# define stump_er_entry( target, entry ) \ -stumpless_add_entry( ( target ), ( entry ) ) -# endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_er_log_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stump_er_log( target, priority, ... ) ( 0 ) -# else -# define stump_er_log( target, priority, ... ) \ -stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) -#endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stump_er_log_str( target, priority, message ) ( 0 ) -# else -# define stump_er_log_str( target, priority, message ) \ -stumpless_add_log_str( ( target ), ( priority ), ( message ) ) -#endif - -/** - * Adds a message to a given target with err severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_ERR, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_er_log instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_er_message_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stump_er_message( target, ... ) ( 0 ) -# else -# define stump_er_message( target, ... ) \ -stumpless_add_log( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_ERR, \ - __VA_ARGS__ ) -# endif - -/** - * Adds a message to a given target with err severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_ERR, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_er_log instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stump_er_message_str( target, message ) ( 0 ) -# else -# define stump_er_message_str( target, message ) \ -stumpless_add_log_str( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_ERR, \ - ( message ) ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stumplog_er_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stumplog_er( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_er( priority, ... ) stumplog( ( priority ), __VA_ARGS__ ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_ERR_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with err level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - */ -# ifdef STUMPLESS_DISABLE_ERR_LEVEL -# define stumplog_er_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_er_str( priority, message ) \ -stumplog_str( ( priority ), ( message ) ) -# endif - -#endif /* __STUMPLESS_LEVEL_ERR_H */ diff --git a/include/stumpless/level/info.h b/include/stumpless/level/info.h deleted file mode 100644 index e7c82ad11..000000000 --- a/include/stumpless/level/info.h +++ /dev/null @@ -1,564 +0,0 @@ -/* SPDX-License-Identifier: Apache-2.0 */ - -/* - * Copyright 2020-2023 Joel E. Anderson - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** @file - * Macro functions that log messages and entries at the informational level. - * - * These can be turned into no-ops at compile time by defining - * STUMPLESS_DISABLE_INFO_LEVEL during build, or at least before inclusion of - * this header (or stumpless.h). - */ - -#ifndef __STUMPLESS_LEVEL_INFO_H -# define __STUMPLESS_LEVEL_INFO_H - -# include - -# ifndef STUMPLESS_DISABLE_INFO_LEVEL -# include -# include -# include -# include -# endif - -/** - * Logs a message to the current target with informational severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumpless_add_log with the provided message and calculated - * priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_INFO, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_i instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_i_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stump_i( ... ) ( 0 ) -# else -# define stump_i( ... ) \ -stumpless_add_log( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_INFO | STUMPLESS_DEFAULT_FACILITY, \ - __VA_ARGS__ ) -# endif - -/** - * Logs a message to the current target with informational severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumpless_add_log with the provided message and calculated - * priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_INFO, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_i instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stump_i_str( message ) ( 0 ) -# else -# define stump_i_str( message ) \ -stumpless_add_log_str( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_INFO | STUMPLESS_DEFAULT_FACILITY, \ - ( message ) ) -# endif - -/** - * Adds an entry to a given target with informational severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * This call does not override the severity of the entry itself. Rather, it is - * intended to allow logging calls to be removed at compile time if the severity - * is known ahead of time. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. - * - * **Async Cancel Safety: AC-Unsafe lock** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked. - * - * @param target The target to send the entry to. - * - * @param entry The entry to send to the target. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stump_i_entry( target, entry ) ( 0 ) -# else -# define stump_i_entry( target, entry ) \ -stumpless_add_entry( ( target ), ( entry ) ) -# endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_i_log_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stump_i_log( target, priority, ... ) ( 0 ) -# else -# define stump_i_log( target, priority, ... ) \ -stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) -#endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stump_i_log_str( target, priority, message ) ( 0 ) -# else -# define stump_i_log_str( target, priority, message ) \ -stumpless_add_log_str( ( target ), ( priority ), ( message ) ) -#endif - -/** - * Adds a message to a given target with informational severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumpless_add_log with the provided message and calculated - * priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_INFO, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_i_log instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_i_message_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stump_i_message( target, ... ) ( 0 ) -# else -# define stump_i_message( target, ... ) \ -stumpless_add_log( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_INFO, \ - __VA_ARGS__ ) -# endif - -/** - * Adds a message to a given target with informational severity. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumpless_add_log with the provided message and calculated - * priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_INFO, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_i_log instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stump_i_message_str( target, message ) ( 0 ) -# else -# define stump_i_message_str( target, message ) \ -stumpless_add_log_str( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_INFO, \ - ( message ) ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stumplog_i_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stumplog_i( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_i( priority, ... ) stumplog( ( priority ), __VA_ARGS__ ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if STUMPLESS_DISABLE_INFO_LEVEL - * has been defined during build. If it is disabled, then this function is - * removed at compile time and will have no effect. Otherwise, it is equivalent - * to a call to stumplog with the provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with info level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - */ -# ifdef STUMPLESS_DISABLE_INFO_LEVEL -# define stumplog_i_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_i_str( priority, message ) \ -stumplog_str( ( priority ), ( message ) ) -# endif - -#endif /* __STUMPLESS_LEVEL_INFO_H */ diff --git a/include/stumpless/level/notice.h b/include/stumpless/level/level.h.in similarity index 69% rename from include/stumpless/level/notice.h rename to include/stumpless/level/level.h.in index db1f47058..ee0852362 100644 --- a/include/stumpless/level/notice.h +++ b/include/stumpless/level/level.h.in @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2020-2023 Joel E. Anderson + * Copyright 2021-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -17,51 +17,52 @@ */ /** @file - * Macro functions that log messages and entries at the notice level. + * Macro functions that log messages and entries at the @LEVEL_NAME_DOWNCASE@ + * level. * * These can be turned into no-ops at compile time by defining - * STUMPLESS_DISABLE_NOTICE_LEVEL during build, or at least before inclusion of - * this header (or stumpless.h). + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL during build, or at least before + * inclusion of this header (or stumpless.h). */ -#ifndef __STUMPLESS_LEVEL_NOTICE_H -# define __STUMPLESS_LEVEL_NOTICE_H +#ifndef __STUMPLESS_LEVEL_@LEVEL_NAME_UPCASE@_H +#define __STUMPLESS_LEVEL_@LEVEL_NAME_UPCASE@_H -# include +#include -# ifndef STUMPLESS_DISABLE_NOTICE_LEVEL -# include -# include -# include -# include -# endif +#ifndef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# include +# include +# include +# include +#endif /** - * Logs a message to the current target with notice severity. + * Logs a message to the current target with @LEVEL_NAME_DOWNCASE@ severity. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. + * If it is disabled, then this function is removed at compile time and will + * have no effect. Otherwise, it is equivalent to a call to + * \ref stumpless_add_log with the provided message and calculated priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_NOTICE, and the facility defined by the + * STUMPLESS_SEVERITY_@LEVEL_NAME_UPCASE@, and the facility defined by the * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_n instead. + * you will need to use \ref stumplog_@LEVEL_SHORTNAME@ instead. * * The message must be a valid format specifier string provided along with the * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stump_n_str instead. + * \ref stump_@LEVEL_SHORTNAME@_str instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -80,13 +81,9 @@ * cancelled, due to the use of locks in some targets that could be left locked * and the potential for memory allocation. * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. + * @param ... The message to log, optionally along with the values for any + * format specifiers valid in \c printf. This must be a valid UTF-8 string in + * shortest form. * * @return A non-negative value if no error is encountered. If an error is * encountered, then a negative value is returned and an error code is set @@ -94,35 +91,36 @@ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stump_n( ... ) ( 0 ) -# else -# define stump_n( ... ) \ -stumpless_add_log( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_NOTICE | STUMPLESS_DEFAULT_FACILITY, \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stump_@LEVEL_SHORTNAME@( ... ) ( 0 ) +#else +# define stump_@LEVEL_SHORTNAME@( ... ) \ +stumpless_add_log( stumpless_get_current_target(), \ + STUMPLESS_SEVERITY_@LEVEL_NAME_UPCASE@ | \ + STUMPLESS_DEFAULT_FACILITY, \ __VA_ARGS__ ) -# endif +#endif /** - * Logs a message to the current target with notice severity. + * Logs a message to the current target with @LEVEL_NAME_DOWNCASE@ severity. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumpless_add_log + * with the provided message and calculated priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_NOTICE, and the facility defined by the + * STUMPLESS_SEVERITY_@LEVEL_NAME_UPCASE@, and the facility defined by the * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_n instead. + * you will need to use stumplog_em instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -152,34 +150,35 @@ stumpless_add_log( stumpless_get_current_target( ), \ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stump_n_str( message ) ( 0 ) -# else -# define stump_n_str( message ) \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stump_@LEVEL_SHORTNAME@_str( message ) ( 0 ) +#else +# define stump_@LEVEL_SHORTNAME@_str( message ) \ stumpless_add_log_str( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_NOTICE | STUMPLESS_DEFAULT_FACILITY, \ + STUMPLESS_SEVERITY_@LEVEL_NAME_UPCASE@ | \ + STUMPLESS_DEFAULT_FACILITY, \ ( message ) ) -# endif +#endif /** - * Adds an entry to a given target with notice severity. + * Adds an entry to a given target with @LEVEL_NAME_DOWNCASE@ severity. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumpless_add_entry + * with the provided target and entry. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * * This call does not override the severity of the entry itself. Rather, it is * intended to allow logging calls to be removed at compile time if the severity * is known ahead of time. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -205,34 +204,34 @@ stumpless_add_log_str( stumpless_get_current_target( ), \ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stump_n_entry( target, entry ) ( 0 ) -# else -# define stump_n_entry( target, entry ) \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stump_@LEVEL_SHORTNAME@_entry( target, entry ) ( 0 ) +#else +# define stump_@LEVEL_SHORTNAME@_entry( target, entry ) \ stumpless_add_entry( ( target ), ( entry ) ) -# endif +#endif /** * Adds a message to a given target with the specified priority. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to stumplog with the + * provided message and priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * * The message must be a valid format specifier string provided along with the * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stump_n_log_str instead. + * \ref stump_@LEVEL_SHORTNAME@_log_str instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -256,13 +255,9 @@ stumpless_add_entry( ( target ), ( entry ) ) * @param priority The priority of the message - this should be the bitwise or * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. + * @param ... The message to log, optionally along with the values for any + * format specifiers valid in \c printf. This must be a valid UTF-8 string in + * shortest form. * * @return A non-negative value if no error is encountered. If an error is * encountered, then a negative value is returned and an error code is set @@ -270,10 +265,10 @@ stumpless_add_entry( ( target ), ( entry ) ) * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stump_n_log( target, priority, ... ) ( 0 ) -# else -# define stump_n_log( target, priority, ... ) \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stump_@LEVEL_SHORTNAME@_log( target, priority, ... ) ( 0 ) +#else +# define stump_@LEVEL_SHORTNAME@_log( target, priority, ... ) \ stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) #endif @@ -281,17 +276,18 @@ stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) * Adds a message to a given target with the specified priority. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to + * \ref stump_@LEVEL_SHORTNAME@_log_str with the provided target, message, and + * priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -326,39 +322,39 @@ stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stump_n_log_str( target, priority, message ) ( 0 ) -# else -# define stump_n_log_str( target, priority, message ) \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stump_@LEVEL_SHORTNAME@_log_str( target, priority, message ) ( 0 ) +#else +# define stump_@LEVEL_SHORTNAME@_log_str( target, priority, message ) \ stumpless_add_log_str( ( target ), ( priority ), ( message ) ) #endif /** - * Adds a message to a given target with notice severity. + * Adds a message to a given target with @LEVEL_NAME_DOWNCASE@ severity. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumpless_add_log + * with the provided message and calculated priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_NOTICE, and the facility defined by the + * STUMPLESS_SEVERITY_@LEVEL_NAME_UPCASE@, and the facility defined by the * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_n_log instead. + * you will need to use stump_@LEVEL_SHORTNAME@_log instead. * * The message must be a valid format specifier string provided along with the * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stump_n_message_str instead. + * \ref stump_@LEVEL_SHORTNAME@_message_str instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -379,13 +375,9 @@ stumpless_add_log_str( ( target ), ( priority ), ( message ) ) * * @param target The target to send the entry to. * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. + * @param ... The message to log, optionally along with the values for any + * format specifiers valid in \c printf. This must be a valid UTF-8 string in + * shortest form. * * @return A non-negative value if no error is encountered. If an error is * encountered, then a negative value is returned and an error code is set @@ -393,35 +385,36 @@ stumpless_add_log_str( ( target ), ( priority ), ( message ) ) * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stump_n_message( target, ... ) ( 0 ) -# else -# define stump_n_message( target, ... ) \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stump_@LEVEL_SHORTNAME@_message( target, ... ) ( 0 ) +#else +# define stump_@LEVEL_SHORTNAME@_message( target, ... ) \ stumpless_add_log( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_NOTICE, \ + STUMPLESS_DEFAULT_FACILITY | \ + STUMPLESS_SEVERITY_@LEVEL_NAME_UPCASE@, \ __VA_ARGS__ ) -# endif +#endif /** - * Adds a message to a given target with notice severity. + * Adds a message to a given target with @LEVEL_NAME_DOWNCASE@ severity. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. + * If it is disabled, then this function is removed at compile time and will + * have no effect. Otherwise, it is equivalent to a call to + * \ref stumpless_add_log_str with the provided target and message. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_NOTICE, and the facility defined by the + * STUMPLESS_SEVERITY_@LEVEL_NAME_UPCASE@, and the facility defined by the * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_n_log instead. + * you will need to use \ref stump_@LEVEL_SHORTNAME@_log instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -453,36 +446,37 @@ stumpless_add_log( ( target ), \ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stump_n_message_str( target, message ) ( 0 ) -# else -# define stump_n_message_str( target, message ) \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stump_@LEVEL_SHORTNAME@_message_str( target, message ) ( 0 ) +#else +# define stump_@LEVEL_SHORTNAME@_message_str( target, message ) \ stumpless_add_log_str( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_NOTICE, \ + STUMPLESS_DEFAULT_FACILITY | \ + STUMPLESS_SEVERITY_@LEVEL_NAME_UPCASE@, \ ( message ) ) -# endif +#endif /** * Adds a message to the current target with the specified priority. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumplog with the + * provided priority and message. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * * The message must be a valid format specifier string provided along with the * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stumplog_n_str instead. + * \ref stumplog_@LEVEL_SHORTNAME@_str instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -504,36 +498,32 @@ stumpless_add_log_str( ( target ), \ * @param priority The priority of the message - this should be the bitwise or * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. + * @param ... The message to log, optionally along with the values for any + * format specifiers valid in \c printf. This must be a valid UTF-8 string in + * shortest form. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stumplog_n( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_n( priority, ... ) \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stumplog_@LEVEL_SHORTNAME@( priority, ... ) ( ( void ) 0 ) +#else +# define stumplog_@LEVEL_SHORTNAME@( priority, ... ) \ stumplog( ( priority ), __VA_ARGS__ ) -# endif +#endif /** * Adds a message to the current target with the specified priority. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_NOTICE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumplog_str with + * the provided message and calculated priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with notice level calls disabled. + * a build with @LEVEL_NAME_DOWNCASE@ level calls disabled. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -560,11 +550,11 @@ stumplog( ( priority ), __VA_ARGS__ ) * @param message The message to log. This must be a valid UTF-8 string in * shortest form. */ -# ifdef STUMPLESS_DISABLE_NOTICE_LEVEL -# define stumplog_n_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_n_str( priority, message ) \ +#ifdef STUMPLESS_DISABLE_@LEVEL_NAME_UPCASE@_LEVEL +# define stumplog_@LEVEL_SHORTNAME@_str( priority, message ) ( ( void ) 0 ) +#else +# define stumplog_@LEVEL_SHORTNAME@_str( priority, message ) \ stumplog_str( ( priority ), ( message ) ) -# endif +#endif -#endif /* __STUMPLESS_LEVEL_NOTICE_H */ +#endif /* __STUMPLESS_LEVEL_@LEVEL_NAME_UPCASE@_H */ diff --git a/include/stumpless/level/mask.h b/include/stumpless/level/mask.h index aba1f6d9f..787877a6a 100644 --- a/include/stumpless/level/mask.h +++ b/include/stumpless/level/mask.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2020-2021 Joel E. Anderson + * Copyright 2020-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,6 +16,10 @@ * limitations under the License. */ +/** @dir level + * Header files for working with specific logging levels. + */ + /** @file * Masks that provide shorthand for enabling or disabling logging levels at * compile time. diff --git a/include/stumpless/level/trace.h b/include/stumpless/level/trace.h index 82fa89ae8..08af17641 100644 --- a/include/stumpless/level/trace.h +++ b/include/stumpless/level/trace.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2021-2022 Joel E. Anderson + * Copyright 2021-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -13,6 +13,7 @@ * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and + * See the License for the specific language governing permissions and * limitations under the License. */ @@ -29,16 +30,16 @@ */ #ifndef __STUMPLESS_LEVEL_TRACE_H -# define __STUMPLESS_LEVEL_TRACE_H +#define __STUMPLESS_LEVEL_TRACE_H -# include +#include -# ifndef STUMPLESS_DISABLE_TRACE_LEVEL -# include -# include -# include -# include -# endif +#ifndef STUMPLESS_DISABLE_TRACE_LEVEL +# include +# include +# include +# include +#endif /** * Logs a message to the current target with debug severity, along with the @@ -49,28 +50,28 @@ * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. + * If it is disabled, then this function is removed at compile time and will + * have no effect. Otherwise, it is equivalent to a call to + * \ref stumpless_add_log with the provided message and calculated priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_DEBUG, and the facility defined by the + * STUMPLESS_SEVERITY_TRACE, and the facility defined by the * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_t instead. + * you will need to use \ref stumplog_t instead. * * The message must be a valid format specifier string provided along with the * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stump_t_str instead. + * \ref stump_t_str instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -89,13 +90,9 @@ * cancelled, due to the use of locks in some targets that could be left locked * and the potential for memory allocation. * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. + * @param ... The message to log, optionally along with the values for any + * format specifiers valid in \c printf. This must be a valid UTF-8 string in + * shortest form. * * @return A non-negative value if no error is encountered. If an error is * encountered, then a negative value is returned and an error code is set @@ -103,17 +100,17 @@ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stump_t( ... ) ( 0 ) -# else -# define stump_t( ... ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stump_t( ... ) ( 0 ) +#else +# define stump_t( ... ) \ stumpless_trace_log( stumpless_get_current_target( ), \ STUMPLESS_SEVERITY_DEBUG | STUMPLESS_DEFAULT_FACILITY, \ __FILE__, \ __LINE__, \ __func__, \ __VA_ARGS__ ) -# endif +#endif /** * Logs a message to the current target with debug severity, along with the @@ -124,22 +121,22 @@ stumpless_trace_log( stumpless_get_current_target( ), \ * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumpless_add_log + * with the provided message and calculated priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_DEBUG, and the facility defined by the + * STUMPLESS_SEVERITY_TRACE, and the facility defined by the * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_t instead. + * you will need to use stumplog_em instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -169,42 +166,42 @@ stumpless_trace_log( stumpless_get_current_target( ), \ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stump_t_str( message ) ( 0 ) -# else -# define stump_t_str( message ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stump_t_str( message ) ( 0 ) +#else +# define stump_t_str( message ) \ stumpless_trace_log_str( stumpless_get_current_target( ), \ STUMPLESS_SEVERITY_DEBUG | STUMPLESS_DEFAULT_FACILITY,\ __FILE__, \ __LINE__, \ __func__, \ ( message ) ) -# endif +#endif /** - * Adds an entry to a given target with debug severity. The entry has a - * structured data element added to it with the file, line, and function of - * the invocation specified. + * Adds an entry to a given target with debug severity, along with the + * file, line, and function of the invocation specified in a structured data + * element. * * The trace information is added in an element named `trace` with params named * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumpless_add_entry + * with the provided target and entry. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * * This call does not override the severity of the entry itself. Rather, it is * intended to allow logging calls to be removed at compile time if the severity * is known ahead of time. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -230,12 +227,12 @@ stumpless_trace_log_str( stumpless_get_current_target( ), \ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stump_t_entry( target, entry ) ( 0 ) -# else -# define stump_t_entry( target, entry ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stump_t_entry( target, entry ) ( 0 ) +#else +# define stump_t_entry( target, entry ) \ stumpless_trace_entry( ( target ), ( entry ), __FILE__, __LINE__, __func__ ) -# endif +#endif /** * Adds a message to a given target with the specified priority, along with the @@ -246,23 +243,23 @@ stumpless_trace_entry( ( target ), ( entry ), __FILE__, __LINE__, __func__ ) * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to stumplog with the + * provided message and priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * * The message must be a valid format specifier string provided along with the * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stump_t_log_str instead. + * \ref stump_t_log_str instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -286,13 +283,9 @@ stumpless_trace_entry( ( target ), ( entry ), __FILE__, __LINE__, __func__ ) * @param priority The priority of the message - this should be the bitwise or * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. + * @param ... The message to log, optionally along with the values for any + * format specifiers valid in \c printf. This must be a valid UTF-8 string in + * shortest form. * * @return A non-negative value if no error is encountered. If an error is * encountered, then a negative value is returned and an error code is set @@ -300,10 +293,10 @@ stumpless_trace_entry( ( target ), ( entry ), __FILE__, __LINE__, __func__ ) * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stump_t_log( target, priority, ... ) ( 0 ) -# else -# define stump_t_log( target, priority, ... ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stump_t_log( target, priority, ... ) ( 0 ) +#else +# define stump_t_log( target, priority, ... ) \ stumpless_trace_log( ( target ), \ ( priority ), \ __FILE__, \ @@ -321,17 +314,18 @@ stumpless_trace_log( ( target ), \ * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to + * \ref stump_t_log_str with the provided target, message, and + * priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -366,10 +360,10 @@ stumpless_trace_log( ( target ), \ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stump_t_log_str( target, priority, message ) ( 0 ) -# else -# define stump_t_log_str( target, priority, message ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stump_t_log_str( target, priority, message ) ( 0 ) +#else +# define stump_t_log_str( target, priority, message ) \ stumpless_trace_log_str( ( target ), \ ( priority ), \ __FILE__, \ @@ -379,25 +373,26 @@ stumpless_trace_log_str( ( target ), \ #endif /** - * Adds a message to a given target with debug severity, along with the file, - * line, and function of the invocation specified in a structured data element. + * Adds a message to a given target with trace severity, along with the + * file, line, and function of the invocation specified in a structured data + * element. * * The trace information is added in an element named `trace` with params named * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumpless_add_log + * with the provided message and calculated priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_DEBUG, and the facility defined by the + * STUMPLESS_SEVERITY_TRACE, and the facility defined by the * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then * you will need to use stump_t_log instead. * @@ -405,9 +400,9 @@ stumpless_trace_log_str( ( target ), \ * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stump_t_message_str instead. + * \ref stump_t_message_str instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -428,13 +423,9 @@ stumpless_trace_log_str( ( target ), \ * * @param target The target to send the entry to. * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. + * @param ... The message to log, optionally along with the values for any + * format specifiers valid in \c printf. This must be a valid UTF-8 string in + * shortest form. * * @return A non-negative value if no error is encountered. If an error is * encountered, then a negative value is returned and an error code is set @@ -442,42 +433,43 @@ stumpless_trace_log_str( ( target ), \ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stump_t_message( target, ... ) ( 0 ) -# else -# define stump_t_message( target, ... ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stump_t_message( target, ... ) ( 0 ) +#else +# define stump_t_message( target, ... ) \ stumpless_trace_log( ( target ), \ STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_DEBUG, \ __FILE__, \ __LINE__, \ __func__, \ __VA_ARGS__ ) -# endif +#endif /** - * Adds a message to a given target with debug severity, along with the file, - * line, and function of the invocation specified in a structured data element. + * Adds a message to a given target with debug severity. The entry has a + * structured data element added to it with the file, line, and function of + * the invocation specified. * * The trace information is added in an element named `trace` with params named * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. + * If it is disabled, then this function is removed at compile time and will + * have no effect. Otherwise, it is equivalent to a call to + * \ref stumpless_add_log_str with the provided target and message. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_DEBUG, and the facility defined by the + * STUMPLESS_SEVERITY_TRACE, and the facility defined by the * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_t_log instead. + * you will need to use \ref stump_t_log instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -509,17 +501,17 @@ stumpless_trace_log( ( target ), \ * is zero, although a return value of zero does not guarantee that this * function is disabled. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stump_t_message_str( target, message ) ( 0 ) -# else -# define stump_t_message_str( target, message ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stump_t_message_str( target, message ) ( 0 ) +#else +# define stump_t_message_str( target, message ) \ stumpless_trace_log_str( ( target ), \ STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_DEBUG,\ __FILE__, \ __LINE__, \ __func__, \ ( message ) ) -# endif +#endif /** * Adds a message to the current target with the specified priority, along with @@ -530,23 +522,23 @@ stumpless_trace_log_str( ( target ), \ * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumplog with the + * provided priority and message. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * * The message must be a valid format specifier string provided along with the * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stumplog_t_str instead. + * \ref stumplog_t_str instead. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -568,20 +560,16 @@ stumpless_trace_log_str( ( target ), \ * @param priority The priority of the message - this should be the bitwise or * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. + * @param ... The message to log, optionally along with the values for any + * format specifiers valid in \c printf. This must be a valid UTF-8 string in + * shortest form. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stumplog_t( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_t( priority, ... ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stumplog_t( priority, ... ) ( ( void ) 0 ) +#else +# define stumplog_t( priority, ... ) \ stumplog_trace( ( priority ), __FILE__, __LINE__, __func__, __VA_ARGS__ ) -# endif +#endif /** * Adds a message to the current target with the specified priority, along with @@ -592,17 +580,17 @@ stumplog_trace( ( priority ), __FILE__, __LINE__, __func__, __VA_ARGS__ ) * `file`, `line`, and `function` for the respective pieces of information. * * This function will be removed at compile time if - * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. + * STUMPLESS_DISABLE_TRACE_LEVEL has been defined during build. If + * it is disabled, then this function is removed at compile time and will have + * no effect. Otherwise, it is equivalent to a call to \ref stumplog_str with + * the provided message and calculated priority. * * Note that if this function is disabled, then the arguments will not be * evaluated, meaning that any side effects will not happen. Be sure that any * side effects you rely on will not cause problems if they are left out during - * a build with debug level calls disabled. + * a build with trace level calls disabled. * - * **Thread Safety: MT-Safe env locale + * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety * differently, as some require per-target locks and others can rely on system * libraries to log safely, but all targets support thread safe logging in some @@ -629,11 +617,11 @@ stumplog_trace( ( priority ), __FILE__, __LINE__, __func__, __VA_ARGS__ ) * @param message The message to log. This must be a valid UTF-8 string in * shortest form. */ -# ifdef STUMPLESS_DISABLE_TRACE_LEVEL -# define stumplog_t_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_t_str( priority, message ) \ +#ifdef STUMPLESS_DISABLE_TRACE_LEVEL +# define stumplog_t_str( priority, message ) ( ( void ) 0 ) +#else +# define stumplog_t_str( priority, message ) \ stumplog_trace_str( ( priority ), __FILE__, __LINE__, __func__, ( message ) ) -# endif +#endif #endif /* __STUMPLESS_LEVEL_TRACE_H */ diff --git a/include/stumpless/level/warning.h b/include/stumpless/level/warning.h deleted file mode 100644 index 5f591fd26..000000000 --- a/include/stumpless/level/warning.h +++ /dev/null @@ -1,569 +0,0 @@ -/* SPDX-License-Identifier: Apache-2.0 */ - -/* - * Copyright 2020-2023 Joel E. Anderson - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ - -/** @file - * Macro functions that log messages and entries at the warning level. - * - * These can be turned into no-ops at compile time by defining - * STUMPLESS_DISABLE_WARNING_LEVEL during build, or at least before inclusion of - * this header (or stumpless.h). - */ - -#ifndef __STUMPLESS_LEVEL_WARNING_H -# define __STUMPLESS_LEVEL_WARNING_H - -# include - -# ifndef STUMPLESS_DISABLE_WARNING_LEVEL -# include -# include -# include -# include -# endif - -/** - * Logs a message to the current target with warning severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_WARNING, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_w instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_w_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stump_w( ... ) ( 0 ) -# else -# define stump_w( ... ) \ -stumpless_add_log( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_WARNING | STUMPLESS_DEFAULT_FACILITY, \ - __VA_ARGS__ ) -# endif - -/** - * Logs a message to the current target with warning severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_WARNING, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stumplog_w instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stump_w_str( message ) ( 0 ) -# else -# define stump_w_str( message ) \ -stumpless_add_log_str( stumpless_get_current_target( ), \ - STUMPLESS_SEVERITY_WARNING | STUMPLESS_DEFAULT_FACILITY,\ - ( message ) ) -# endif - -/** - * Adds an entry to a given target with warning severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * This call does not override the severity of the entry itself. Rather, it is - * intended to allow logging calls to be removed at compile time if the severity - * is known ahead of time. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. - * - * **Async Cancel Safety: AC-Unsafe lock** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked. - * - * @param target The target to send the entry to. - * - * @param entry The entry to send to the target. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stump_w_entry( target, entry ) ( 0 ) -# else -# define stump_w_entry( target, entry ) \ -stumpless_add_entry( ( target ), ( entry ) ) -# endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_w_log_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stump_w_log( target, priority, ... ) ( 0 ) -# else -# define stump_w_log( target, priority, ... ) \ -stumpless_add_log( ( target ), ( priority ), __VA_ARGS__ ) -#endif - -/** - * Adds a message to a given target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stump_w_log_str( target, priority, message ) ( 0 ) -# else -# define stump_w_log_str( target, priority, message ) \ -stumpless_add_log_str( ( target ), ( priority ), ( message ) ) -#endif - -/** - * Adds a message to a given target with warning severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_WARNING, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_w_log instead. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stump_w_message_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param target The target to send the entry to. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stump_w_message( target, ... ) ( 0 ) -# else -# define stump_w_message( target, ... ) \ -stumpless_add_log( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_WARNING, \ - __VA_ARGS__ ) -# endif - -/** - * Adds a message to a given target with warning severity. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumpless_add_log with the - * provided message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * This function will log the given message with a severity of - * STUMPLESS_SEVERITY_WARNING, and the facility defined by the - * STUMPLESS_DEFAULT_FACILITY. If you wish to specify a different priority, then - * you will need to use stump_w_log instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param target The target to send the entry to. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - * - * @return A non-negative value if no error is encountered. If an error is - * encountered, then a negative value is returned and an error code is set - * appropriately. If the function is disabled then the effective return value - * is zero, although a return value of zero does not guarantee that this - * function is disabled. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stump_w_message_str( target, message ) ( 0 ) -# else -# define stump_w_message_str( target, message ) \ -stumpless_add_log_str( ( target ), \ - STUMPLESS_DEFAULT_FACILITY | STUMPLESS_SEVERITY_WARNING,\ - ( message ) ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * The message must be a valid format specifier string provided along with the - * appropriate number of variable arguments afterwards. This means that it - * should not be a user-controlled value under any circumstances. If you need a - * safer alternative without the risks of format strings, use - * \c stumplog_w_str instead. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log, optionally containing any format - * specifiers valid in \c printf. This must be a valid UTF-8 string in shortest - * form. - * - * @param ... Substitutions for any format specifiers provided in message. The - * number of substitutions provided must exactly match the number of - * specifiers given. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stumplog_w( priority, ... ) ( ( void ) 0 ) -# else -# define stumplog_w( priority, ... ) stumplog( ( priority ), __VA_ARGS__ ) -# endif - -/** - * Adds a message to the current target with the specified priority. - * - * This function will be removed at compile time if - * STUMPLESS_DISABLE_WARNING_LEVEL has been defined during build. If it is - * disabled, then this function is removed at compile time and will have no - * effect. Otherwise, it is equivalent to a call to stumplog with the provided - * message and calculated priority. - * - * Note that if this function is disabled, then the arguments will not be - * evaluated, meaning that any side effects will not happen. Be sure that any - * side effects you rely on will not cause problems if they are left out during - * a build with warning level calls disabled. - * - * **Thread Safety: MT-Safe env locale - * This function is thread safe. Different target types handle thread safety - * differently, as some require per-target locks and others can rely on system - * libraries to log safely, but all targets support thread safe logging in some - * manner. For target-specific information on how thread safety is supported and - * whether AS or AC safety can be assumed, refer to the documentation for the - * target's header file (in the `stumpless/target` include folder). - * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers as some targets make - * use of non-reentrant locks to coordinate access. It also may make memory - * allocation calls to create internal cached structures, and memory allocation - * may not be signal safe. - * - * **Async Cancel Safety: AC-Unsafe lock heap** - * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of locks in some targets that could be left locked - * and the potential for memory allocation. - * - * @since release v2.1.0. - * - * @param priority The priority of the message - this should be the bitwise or - * of a single STUMPLESS_SEVERITY and single STUMPLESS_FACILITY value. - * - * @param message The message to log. This must be a valid UTF-8 string in - * shortest form. - */ -# ifdef STUMPLESS_DISABLE_WARNING_LEVEL -# define stumplog_w_str( priority, message ) ( ( void ) 0 ) -# else -# define stumplog_w_str( priority, message ) \ -stumplog_str( ( priority ), ( message ) ) -# endif - -#endif /* __STUMPLESS_LEVEL_WARNING_H */ diff --git a/include/stumpless/log.h b/include/stumpless/log.h index 836cc2b4b..b7bba3c99 100644 --- a/include/stumpless/log.h +++ b/include/stumpless/log.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2018-2023 Joel E. Anderson + * Copyright 2018-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -37,7 +37,7 @@ extern "C" { * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stump_str instead. + * stump_str() instead. * * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety @@ -375,7 +375,7 @@ stumplog_str( int priority, const char *message ); * appropriate number of variable arguments afterwards. This means that it * should not be a user-controlled value under any circumstances. If you need a * safer alternative without the risks of format strings, use - * \c stumplog_trace_str instead. + * stumplog_trace_str() instead. * * **Thread Safety: MT-Safe env locale** * This function is thread safe. Different target types handle thread safety diff --git a/include/stumpless/severity.h b/include/stumpless/severity.h index 37d097d6d..a3d1693f4 100644 --- a/include/stumpless/severity.h +++ b/include/stumpless/severity.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2018-2023 Joel E. Anderson + * Copyright 2018-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -178,9 +178,12 @@ extern "C" { /** * All possible severity codes available to log entries. * - * In versions prior to 2.0.0, these values were simply #define symbols. They + * In versions prior to 2.0.0, these values were simply \#define symbols. They * have been changed to an enum to clearly convey proper usage. * + * See STUMPLESS_FOREACH_SEVERITY() and STUMPLESS_GENERATE_ENUM() for how the + * enumeration is actually defined. + * * @since release v2.0.0. */ enum stumpless_severity { diff --git a/include/stumpless/target.h b/include/stumpless/target.h index cee494c1f..f1d2bc2be 100644 --- a/include/stumpless/target.h +++ b/include/stumpless/target.h @@ -43,31 +43,31 @@ extern "C" { #endif -/**< write to a character buffer */ +/** write to a character buffer */ #define STUMPLESS_BUFFER_TARGET_VALUE 0 -/**< write to a file */ +/** write to a file */ #define STUMPLESS_FILE_TARGET_VALUE 1 -/**< call a custom function */ +/** call a custom function */ #define STUMPLESS_FUNCTION_TARGET_VALUE 2 -/**< send to the systemd journald service */ +/** send to the systemd journald service */ #define STUMPLESS_JOURNALD_TARGET_VALUE 3 -/**< send to a network endpoint */ +/** send to a network endpoint */ #define STUMPLESS_NETWORK_TARGET_VALUE 4 -/**< write to a Unix socket */ +/** write to a Unix socket */ #define STUMPLESS_SOCKET_TARGET_VALUE 5 -/**< write to a FILE stream */ +/** write to a FILE stream */ #define STUMPLESS_STREAM_TARGET_VALUE 6 -/**< add to the Windows Event Log */ +/** add to the Windows Event Log */ #define STUMPLESS_WINDOWS_EVENT_LOG_TARGET_VALUE 7 -/**< add to a SQLite3 database */ +/** add to a SQLite3 database */ #define STUMPLESS_SQLITE3_TARGET_VALUE 8 /** @@ -84,28 +84,20 @@ extern "C" { * value of the target_type. */ #define STUMPLESS_FOREACH_TARGET_TYPE( ACTION )\ -/**< write to a character buffer */\ ACTION( STUMPLESS_BUFFER_TARGET, STUMPLESS_BUFFER_TARGET_VALUE )\ -/**< write to a file */\ ACTION( STUMPLESS_FILE_TARGET, STUMPLESS_FILE_TARGET_VALUE )\ -/**< call a custom function */\ ACTION( STUMPLESS_FUNCTION_TARGET, STUMPLESS_FUNCTION_TARGET_VALUE )\ -/**< send to the systemd journald service */\ ACTION( STUMPLESS_JOURNALD_TARGET, STUMPLESS_JOURNALD_TARGET_VALUE )\ -/**< send to a network endpoint */\ ACTION( STUMPLESS_NETWORK_TARGET, STUMPLESS_NETWORK_TARGET_VALUE )\ -/**< write to a Unix socket */\ ACTION( STUMPLESS_SOCKET_TARGET, STUMPLESS_SOCKET_TARGET_VALUE )\ -/**< write to a FILE stream */\ ACTION( STUMPLESS_STREAM_TARGET, STUMPLESS_STREAM_TARGET_VALUE )\ -/**< add to the Windows Event Log */\ ACTION( STUMPLESS_WINDOWS_EVENT_LOG_TARGET, STUMPLESS_WINDOWS_EVENT_LOG_TARGET_VALUE )\ -/**< add to a SQLite3 database */\ ACTION( STUMPLESS_SQLITE3_TARGET, STUMPLESS_SQLITE3_TARGET_VALUE )\ -/**< write to a series of targets and filters **/\ ACTION( STUMPLESS_CHAIN_TARGET, STUMPLESS_CHAIN_TARGET_VALUE ) -/** Types of targets that may be created. */ +/** + * Types of targets that may be created. + */ enum stumpless_target_type { STUMPLESS_FOREACH_TARGET_TYPE( STUMPLESS_GENERATE_ENUM ) }; @@ -1645,7 +1637,7 @@ vstumpless_trace_message( struct stumpless_target *target, */ STUMPLESS_PUBLIC_FUNCTION const char * -stumpless_get_target_type_string( enum stumpless_target_type target ); +stumpless_get_target_type_string( enum stumpless_target_type target_type ); #ifdef __cplusplus diff --git a/include/stumpless/target/wel.h b/include/stumpless/target/wel.h index 7899e35ad..59d0df9d9 100644 --- a/include/stumpless/target/wel.h +++ b/include/stumpless/target/wel.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: Apache-2.0 */ /* - * Copyright 2018-2022 Joel E. Anderson + * Copyright 2018-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -139,9 +139,6 @@ stumpless_open_local_wel_target( const char *name ); * @param name The name of the target to open. This should match the name of the * Windows Event Source that the logs will be added to. * - * @param options The options to use for the logging target. This is a bit-wise - * or of one or more \c STUMPLESS_OPTION values. - * * @return The opened target if no error is encountered. In the event of an * error, NULL is returned and an error code is set appropriately. */ diff --git a/src/config/have_getaddrinfo.c b/src/config/have_getaddrinfo.c index fcc7621d3..e00b320e9 100644 --- a/src/config/have_getaddrinfo.c +++ b/src/config/have_getaddrinfo.c @@ -1,7 +1,7 @@ // SPDX-License-Identifier: Apache-2.0 /* - * Copyright 2023 Joel E. Anderson + * Copyright 2023-2024 Joel E. Anderson * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -19,6 +19,7 @@ #include #include #include +#include #include #include "private/config/have_getaddrinfo.h" #include "private/config/wrapper/locale.h" diff --git a/src/config/have_winsock2.c b/src/config/have_winsock2.c index 3c13921f7..e14f36180 100644 --- a/src/config/have_winsock2.c +++ b/src/config/have_winsock2.c @@ -21,6 +21,7 @@ #include #include +#include #include "private/config/have_winsock2.h" #include "private/config/wrapper/locale.h" #include "private/config/wrapper/thread_safety.h" diff --git a/src/entry.c b/src/entry.c index b2f0942e8..975cad181 100644 --- a/src/entry.c +++ b/src/entry.c @@ -1273,7 +1273,7 @@ locked_get_element_by_index( const struct stumpless_entry *entry, struct stumpless_element * locked_get_element_by_name( const struct stumpless_entry *entry, const char *name ) { - int i; + size_t i; struct stumpless_element *element; int cmp_result; diff --git a/src/target.c b/src/target.c index 9199f33fa..d06c76791 100644 --- a/src/target.c +++ b/src/target.c @@ -160,12 +160,14 @@ add_trace_element( void ) { const char * stumpless_get_target_type_string( enum stumpless_target_type target_type ){ - size_t target_type_upper_bound = - sizeof target_type_enum_to_string / sizeof target_type_enum_to_string[0]; - if ( target_type >= 0 && target_type < target_type_upper_bound ) { + size_t upper_bound; + + upper_bound = sizeof( target_type_enum_to_string ) / sizeof( const char * ); + if ( target_type >= 0 && target_type < cap_size_t_to_int( upper_bound ) ) { return target_type_enum_to_string[target_type]; + } else { + return "NO_SUCH_TARGET_TYPE"; } - return "NO_SUCH_TARGET_TYPE"; } static diff --git a/test/function/target.cpp b/test/function/target.cpp index c838e4b76..4131d25bd 100644 --- a/test/function/target.cpp +++ b/test/function/target.cpp @@ -537,6 +537,7 @@ namespace { stumpless_set_cons_stream( file ); EXPECT_TRUE( stumpless_get_cons_stream() == file ); fclose( file ); + remove( filename ); stumpless_free_all( ); } @@ -697,6 +698,7 @@ namespace { EXPECT_EQ( line_count, 1 ); stumpless_free_all( ); + remove( error_filename ); } TEST( PerrorOption, NullErrorStream ) { diff --git a/tools/check_headers/c_standard_library.yml b/tools/check_headers/c_standard_library.yml index 99ecc88b2..a8c6b558e 100644 --- a/tools/check_headers/c_standard_library.yml +++ b/tools/check_headers/c_standard_library.yml @@ -7,6 +7,9 @@ "CRITICAL_SECTION": - "private/windows_wrapper.h" - "windows.h" +"socket": + - "sys/socket.h" + - "winsock2.h" "size_t": - "stddef.h" - "stdio.h" @@ -20,3 +23,4 @@ "wchar_t": - "stddef.h" - "wchar.h" +"WSAStartup": "winsock2.h" diff --git a/tools/check_headers/stumpless_private.yml b/tools/check_headers/stumpless_private.yml index 58a2817d6..e2a2201b5 100644 --- a/tools/check_headers/stumpless_private.yml +++ b/tools/check_headers/stumpless_private.yml @@ -173,6 +173,9 @@ "struct chain_target": "private/target/chain.h" "struct function_target": "private/target/function.h" "struct sqlite3_target": "private/target/sqlite3.h" +"STUMPLESS_DISABLE_": "stumpless/level/mask.h" +"STUMPLESS_SEVERITY_": "stumpless/severity.h" +"stumplog_": "stumpless/level/level.h" "SUPPORT_ABSTRACT_SOCKET_NAMES": "private/config.h" "SUPPORT_GETHOSTBYNAME": "private/config.h" "SUPPORT_UNISTD_SYSCONF_GETPAGESIZE": "private/config.h" diff --git a/tools/cmake/chain.cmake b/tools/cmake/chain.cmake index 82af8aa4d..5d64ae0f4 100644 --- a/tools/cmake/chain.cmake +++ b/tools/cmake/chain.cmake @@ -1,18 +1,20 @@ -list(APPEND STUMPLESS_SOURCES ${PROJECT_SOURCE_DIR}/src/target/chain.c) -list(APPEND WRAPTURE_SPECS ${PROJECT_SOURCE_DIR}/tools/wrapture/chain_target.yml) +list(APPEND STUMPLESS_SOURCES "${PROJECT_SOURCE_DIR}/src/target/chain.c") +list(APPEND WRAPTURE_SPECS "${PROJECT_SOURCE_DIR}/tools/wrapture/chain_target.yml") -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/target/chain.h - DESTINATION "include/stumpless/target" -) +if(INSTALL_HEADERS) + install( + FILES "${PROJECT_SOURCE_DIR}/include/stumpless/target/chain.h" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/target" + ) +endif() -list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/man/man3/chain.h.3) +list(APPEND DOXYGEN_MANPAGES "${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/chain.h.3") if(INCLUDE_MANPAGES_IN_INSTALL) install(FILES - ${PROJECT_BINARY_DIR}/docs/man/man3/chain.h.3 - RENAME stumpless_target_chain.h.3 - DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 + "${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/chain.h.3" + RENAME "stumpless_target_chain.h.3" + DESTINATION "${CMAKE_INSTALL_MANDIR}/man3" ) endif() diff --git a/tools/cmake/cpack.cmake b/tools/cmake/cpack.cmake index 6dd958214..e75c75577 100644 --- a/tools/cmake/cpack.cmake +++ b/tools/cmake/cpack.cmake @@ -10,6 +10,7 @@ string(CONCAT CPACK_PACKAGE_DESCRIPTION "https://goatshriek.github.io/stumpless/ for more info and documentation." ) +set(CPACK_PACKAGE_NAME "libstumpless") set(CPACK_PACKAGE_CONTACT "Joel Anderson ") set(CPACK_PACKAGE_VENDOR "Goatshriek Software") set(CPACK_PACKAGE_RELOCATABLE ON) @@ -29,6 +30,14 @@ set(CPACK_DEBIAN_PACKAGE_SECTION "libs") set(CPACK_DEBIAN_ARCHIVE_TYPE "gnutar") set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.19-18)") +if(STUMPLESS_JOURNALD_TARGETS_SUPPORTED) + set(CPACK_DEBIAN_PACKAGE_DEPENDS "${CPACK_DEBIAN_PACKAGE_DEPENDS}, libsystemd0") +endif() + +if(STUMPLESS_SQLITE3_TARGETS_SUPPORTED) + set(CPACK_DEBIAN_PACKAGE_DEPENDS "${CPACK_DEBIAN_PACKAGE_DEPENDS}, libsqlite3-0") +endif() + # RPM settings set(CPACK_RPM_PACKAGE_LICENSE "ASL 2.0") @@ -37,11 +46,29 @@ set(CPACK_RPM_PACKAGE_REQUIRES "glibc") set(CPACK_RPM_PACKAGE_RELEASE "1") set(CPACK_RPM_PACKAGE_DESCRIPTION "${CPACK_PACKAGE_DESCRIPTION}") +if(STUMPLESS_JOURNALD_TARGETS_SUPPORTED) + set(CPACK_RPM_PACKAGE_REQUIRES "${CPACK_RPM_PACKAGE_REQUIRES}, systemd-libs") +endif() + +if(STUMPLESS_SQLITE3_TARGETS_SUPPORTED) + set(CPACK_RPM_PACKAGE_REQUIRES "${CPACK_RPM_PACKAGE_REQUIRES}, sqlite-libs") +endif() + + + +# FreeBSD PKG settings +set(CPACK_FREEBSD_PACKAGE_CATEGORIES "devel") + +if(STUMPLESS_SQLITE3_TARGETS_SUPPORTED) + set(CPACK_FREEBSD_PACKAGE_DEPS "databases/sqlite3") +endif() + # WIX settings set(CPACK_WIX_PRODUCT_GUID "c0ac11a2-d1ab-4aa9-9f4f-b67d7c6db291") set(CPACK_WIX_UPGRADE_GUID "21affd82-0719-4144-9f54-5e893a08633d") -set(CPACK_WIX_PRODUCT_ICON "${PROJECT_SOURCE_DIR}/assets/logo.ico") +# TODO: this needs to be updated to generate an ico from the logo svg +#set(CPACK_WIX_PRODUCT_ICON "${PROJECT_SOURCE_DIR}/assets/logo.ico") include(CPack) diff --git a/tools/cmake/cpp.cmake b/tools/cmake/cpp.cmake index 0245a9885..90e3eb301 100644 --- a/tools/cmake/cpp.cmake +++ b/tools/cmake/cpp.cmake @@ -126,7 +126,7 @@ file(MAKE_DIRECTORY ${CPP_LIB_BUILD_DIR}) if(MSVC) add_custom_command( - OUTPUT ${GENERATED_CPP_LIB_SOURCES} + OUTPUT ${GENERATED_CPP_LIB_SOURCES} ${GENERATED_CPP_LIB_HEADERS} COMMAND call wrapture ${WRAPTURE_SPECS} COMMAND powershell ${PROJECT_SOURCE_DIR}/scripts/Repair-HeaderDllExports.ps1 -InputFileDir ${CPP_LIB_BUILD_DIR} -OutputFileDir ${CMAKE_BINARY_DIR}/include/stumpless DEPENDS ${WRAPTURE_SPECS} @@ -135,7 +135,7 @@ if(MSVC) ) else() add_custom_command( - OUTPUT ${GENERATED_CPP_LIB_SOURCES} + OUTPUT ${GENERATED_CPP_LIB_SOURCES} ${GENERATED_CPP_LIB_HEADERS} COMMAND wrapture ${WRAPTURE_SPECS} COMMAND ruby ${PROJECT_SOURCE_DIR}/scripts/copy_headers.rb ${CMAKE_BINARY_DIR}/include/stumpless DEPENDS ${WRAPTURE_SPECS} @@ -148,11 +148,11 @@ endif() # create the rollup header SET(cpp_rollup_header "${PROJECT_BINARY_DIR}/include/stumpless.hpp") FILE(WRITE ${cpp_rollup_header} "#ifndef __STUMPLESS_HPP\n") -FILE(APPEND ${cpp_rollup_header} "# define __STUMPLESS_HPP\n\n") +FILE(APPEND ${cpp_rollup_header} "#define __STUMPLESS_HPP\n\n") foreach(header_path ${GENERATED_CPP_LIB_HEADERS}) get_filename_component(header_filename ${header_path} NAME) - FILE(APPEND ${cpp_rollup_header} "# include \n") + FILE(APPEND ${cpp_rollup_header} "#include \n") endforeach(header_path) FILE(APPEND ${cpp_rollup_header} "\n#endif /* __STUMPLESS_HPP */\n") @@ -177,7 +177,6 @@ target_include_directories(stumplesscpp set_target_properties(stumplesscpp PROPERTIES VERSION ${PROJECT_VERSION} - PUBLIC_HEADER ${cpp_rollup_header} ) if(WIN32) @@ -271,14 +270,20 @@ add_custom_target(run-example-cpp install(TARGETS stumplesscpp RUNTIME DESTINATION "bin" LIBRARY DESTINATION "lib" - PUBLIC_HEADER DESTINATION "include" ARCHIVE DESTINATION "lib" ) -install( - FILES ${GENERATED_CPP_LIB_HEADERS} - DESTINATION "include/stumpless" -) +if(INSTALL_HEADERS) + install( + FILES "${cpp_rollup_header}" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}" + ) + + install( + FILES ${GENERATED_CPP_LIB_HEADERS} + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/stumpless" + ) +endif() #documentation generation if(DOXYGEN_FOUND) diff --git a/tools/cmake/doxygen.cmake b/tools/cmake/doxygen.cmake new file mode 100644 index 000000000..114c631f0 --- /dev/null +++ b/tools/cmake/doxygen.cmake @@ -0,0 +1,41 @@ +set(DOXYGEN_INPUT "${PROJECT_BINARY_DIR}/include/doxygen") +set(DOXYGEN_OUTPUT "${PROJECT_DOCS_DIR}") + +configure_file( + "${PROJECT_SOURCE_DIR}/tools/doxygen/Doxyfile.in" + "${PROJECT_BINARY_DIR}/tools/doxygen/Doxyfile" +) + +# detect files for dependency tracking +# note that this doesn't support new files being added after configuring: +# cmake will need to be re-run if this happens to include them in dependency tracking +file(GLOB_RECURSE DOXYGEN_SOURCE_HEADERS "${L10N_INCLUDE_DIR}/stumpless/*.h") +file(GLOB_RECURSE DOXYGEN_L10N_HEADERS "${L10N_INCLUDE_DIR}/stumpless/*.h") +file(GLOB_RECURSE DOXYGEN_BINARY_HEADERS "${PROJECT_BINARY_DIR}/include/stumpless/*.h") +file(GLOB_RECURSE DOXYGEN_EXAMPLE_SOURCES "${L10N_EXAMPLE_DIR}/*.c") + +# we copy files into a specific doxygen folder because otherwise doxygen +# generates multiple folders with the same name in the file tree +# see https://github.com/doxygen/doxygen/issues/8318 for details +add_custom_command( + OUTPUT ${DOXYGEN_MANPAGES} + COMMAND ${CMAKE_COMMAND} -E make_directory "${PROJECT_DOCS_DIR}" + COMMAND ${CMAKE_COMMAND} -E rm -rf "${DOXYGEN_INPUT}" + COMMAND ${CMAKE_COMMAND} -E copy_directory "${PROJECT_BINARY_DIR}/include/stumpless" "${DOXYGEN_INPUT}/stumpless" + COMMAND ${CMAKE_COMMAND} -E copy_directory "${PROJECT_SOURCE_DIR}/include/stumpless" "${DOXYGEN_INPUT}/stumpless" + COMMAND ${CMAKE_COMMAND} -E copy "${PROJECT_SOURCE_DIR}/include/stumpless.h" "${DOXYGEN_INPUT}/stumpless.h" + COMMAND ${CMAKE_COMMAND} -E copy_directory "${L10N_INCLUDE_DIR}/stumpless" "${DOXYGEN_INPUT}/stumpless" + COMMAND ${CMAKE_COMMAND} -E copy "${L10N_INCLUDE_DIR}/stumpless.h" "${DOXYGEN_INPUT}/stumpless.h" + COMMAND ${DOXYGEN_EXECUTABLE} "${CMAKE_BINARY_DIR}/tools/doxygen/Doxyfile" + MAIN_DEPENDENCY "${PROJECT_BINARY_DIR}/tools/doxygen/Doxyfile" + DEPENDS + ${DOXYGEN_SOURCE_HEADERS} + ${DOXYGEN_L10N_HEADERS} + ${DOXYGEN_BINARY_HEADERS} + ${DOXYGEN_EXAMPLE_SOURCES} + "${L10N_INCLUDE_DIR}/stumpless.h" + "${PROJECT_SOURCE_DIR}/include/stumpless.h" + VERBATIM +) + +add_custom_target(docs DEPENDS ${DOXYGEN_MANPAGES}) diff --git a/tools/cmake/install_headers.cmake b/tools/cmake/install_headers.cmake new file mode 100644 index 000000000..9b5b7315a --- /dev/null +++ b/tools/cmake/install_headers.cmake @@ -0,0 +1,54 @@ +install( + FILES "${PROJECT_SOURCE_DIR}/include/stumpless.h" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}" +) + +install( + FILES + "${PROJECT_BINARY_DIR}/include/stumpless/config.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/element.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/entry.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/error.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/facility.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/filter.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/generator.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/id.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/log.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/memory.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/option.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/param.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/priority.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/prival.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/severity.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/target.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/version.h" + DESTINATION + "${CMAKE_INSTALL_INCLUDEDIR}/stumpless" +) + +install( + FILES + "${PROJECT_BINARY_DIR}/include/stumpless/level/alert.h" + "${PROJECT_BINARY_DIR}/include/stumpless/level/crit.h" + "${PROJECT_BINARY_DIR}/include/stumpless/level/debug.h" + "${PROJECT_BINARY_DIR}/include/stumpless/level/emerg.h" + "${PROJECT_BINARY_DIR}/include/stumpless/level/err.h" + "${PROJECT_BINARY_DIR}/include/stumpless/level/info.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/level/mask.h" + "${PROJECT_BINARY_DIR}/include/stumpless/level/notice.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/level/trace.h" + "${PROJECT_BINARY_DIR}/include/stumpless/level/warning.h" + DESTINATION + "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/level" +) + +install( + FILES + "${PROJECT_SOURCE_DIR}/include/stumpless/target/buffer.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/target/file.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/target/function.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/target/sqlite3.h" + "${PROJECT_SOURCE_DIR}/include/stumpless/target/stream.h" + DESTINATION + "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/target" +) diff --git a/tools/cmake/install_html.cmake b/tools/cmake/install_html.cmake new file mode 100644 index 000000000..2b3f1a12c --- /dev/null +++ b/tools/cmake/install_html.cmake @@ -0,0 +1,5 @@ +set(HTML_BUILD_DIR "${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/html") + +install(DIRECTORY "${HTML_BUILD_DIR}" + DESTINATION "${CMAKE_INSTALL_DATAROOTDIR}/doc/libstumpless" +) diff --git a/tools/cmake/install_manpages.cmake b/tools/cmake/install_manpages.cmake index 2f86d3f72..905bfbd1b 100644 --- a/tools/cmake/install_manpages.cmake +++ b/tools/cmake/install_manpages.cmake @@ -1,4 +1,4 @@ -set(MANPAGE_BUILD_DIR "${PROJECT_BINARY_DIR}/docs/man/man3") +set(MANPAGE_BUILD_DIR "${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3") # install the generated manpages # rename them so that they are globally unique @@ -163,6 +163,12 @@ install(FILES DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 ) +install(FILES + ${MANPAGE_BUILD_DIR}/chain.h.3 + RENAME stumpless_target_chain.h.3 + DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 +) + install(FILES ${MANPAGE_BUILD_DIR}/file.h.3 RENAME stumpless_target_file.h.3 diff --git a/tools/cmake/journald.cmake b/tools/cmake/journald.cmake index 2e7b01086..dbb5057b9 100644 --- a/tools/cmake/journald.cmake +++ b/tools/cmake/journald.cmake @@ -2,28 +2,30 @@ list(APPEND STUMPLESS_SOURCES ${PROJECT_SOURCE_DIR}/src/target/journald.c) list(APPEND STUMPLESS_SOURCES ${PROJECT_SOURCE_DIR}/src/config/journald_supported.c) list(APPEND WRAPTURE_SPECS ${PROJECT_SOURCE_DIR}/tools/wrapture/journald_target.yml) -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/target/journald.h - DESTINATION "include/stumpless/target" -) +if(INSTALL_HEADERS) + install( + FILES "${PROJECT_SOURCE_DIR}/include/stumpless/target/journald.h" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/target" + ) -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/config/journald_supported.h - DESTINATION "include/stumpless/config" -) + install( + FILES "${PROJECT_SOURCE_DIR}/include/stumpless/config/journald_supported.h" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/config" + ) +endif() -list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/man/man3/journald.h.3) -list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/man/man3/journald_supported.h.3) +list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/journald.h.3) +list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/journald_supported.h.3) if(INCLUDE_MANPAGES_IN_INSTALL) install(FILES - ${PROJECT_BINARY_DIR}/docs/man/man3/journald.h.3 + ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/journald.h.3 RENAME stumpless_target_journald.h.3 DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 ) install(FILES - ${PROJECT_BINARY_DIR}/docs/man/man3/journald_supported.h.3 + ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/journald_supported.h.3 RENAME stumpless_config_journald_supported.h.3 DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 ) diff --git a/tools/cmake/l10n.cmake b/tools/cmake/l10n.cmake index 62db9615a..4bd7ac49a 100644 --- a/tools/cmake/l10n.cmake +++ b/tools/cmake/l10n.cmake @@ -77,18 +77,13 @@ else() endif() -# set the doxygen input files +# set the input files for documentation if(USE_LOCALE_ZH_CN) - set(DOXYGEN_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/l10n/zh-cn/包含") - set(DOXYGEN_EXAMPLE_DIR "${PROJECT_SOURCE_DIR}/l10n/zh-cn/文档/示例") + set(L10N_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/l10n/zh-cn/包含") + set(L10N_EXAMPLE_DIR "${PROJECT_SOURCE_DIR}/l10n/zh-cn/文档/示例") set(DOXYGEN_OUTPUT_LANGUAGE "Chinese") else() # default to USE_LOCALE_EN_US - set(DOXYGEN_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/include/") - set(DOXYGEN_EXAMPLE_DIR "${PROJECT_SOURCE_DIR}/docs/examples") + set(L10N_INCLUDE_DIR "${PROJECT_SOURCE_DIR}/include/") + set(L10N_EXAMPLE_DIR "${PROJECT_SOURCE_DIR}/docs/examples") set(DOXYGEN_OUTPUT_LANGUAGE "English") endif() - - -# we add the source dir include path at the very end so that any elements not -# documented in the localized headers get default documentation of English -set(DOXYGEN_INPUT "${DOXYGEN_INCLUDE_DIR}/stumpless.h ${DOXYGEN_INCLUDE_DIR}/stumpless ${PROJECT_BINARY_DIR}/include/stumpless ${PROJECT_SOURCE_DIR}/include/stumpless ") diff --git a/tools/cmake/network.cmake b/tools/cmake/network.cmake index a279bd7ce..196dfbea4 100644 --- a/tools/cmake/network.cmake +++ b/tools/cmake/network.cmake @@ -16,16 +16,18 @@ elseif(HAVE_WINSOCK2_H) find_library(WINSOCK2 NAMES Ws2_32) endif() -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/target/network.h - DESTINATION "include/stumpless/target" -) +if(INSTALL_HEADERS) + install( + FILES "${PROJECT_SOURCE_DIR}/include/stumpless/target/network.h" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/target" + ) +endif() -list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/man/man3/network.h.3) +list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/network.h.3) if(INCLUDE_MANPAGES_IN_INSTALL) install(FILES - ${PROJECT_BINARY_DIR}/docs/man/man3/network.h.3 + ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/network.h.3 RENAME stumpless_target_network.h.3 DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 ) diff --git a/tools/cmake/socket.cmake b/tools/cmake/socket.cmake index f62ed777d..b36c85620 100644 --- a/tools/cmake/socket.cmake +++ b/tools/cmake/socket.cmake @@ -3,16 +3,18 @@ list(APPEND STUMPLESS_SOURCES ${PROJECT_SOURCE_DIR}/src/config/socket_supported. list(APPEND WRAPTURE_SPECS ${PROJECT_SOURCE_DIR}/tools/wrapture/socket_target.yml) -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/target/socket.h - DESTINATION "include/stumpless/target" -) +if(INSTALL_HEADERS) + install( + FILES "${PROJECT_SOURCE_DIR}/include/stumpless/target/socket.h" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/target" + ) +endif() -list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/man/man3/socket.h.3) +list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/socket.h.3) if(INCLUDE_MANPAGES_IN_INSTALL) install(FILES - ${PROJECT_BINARY_DIR}/docs/man/man3/socket.h.3 + ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/socket.h.3 RENAME stumpless_target_socket.h.3 DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 ) diff --git a/tools/cmake/sqlite3.cmake b/tools/cmake/sqlite3.cmake index 23c611055..3b495b626 100644 --- a/tools/cmake/sqlite3.cmake +++ b/tools/cmake/sqlite3.cmake @@ -1,10 +1,10 @@ list(APPEND STUMPLESS_SOURCES "${PROJECT_SOURCE_DIR}/src/target/sqlite3.c") list(APPEND WRAPTURE_SPECS "${PROJECT_SOURCE_DIR}/tools/wrapture/sqlite3_target.yml") -list(APPEND DOXYGEN_MANPAGES "${PROJECT_BINARY_DIR}/docs/man/man3/sqlite3.h.3") +list(APPEND DOXYGEN_MANPAGES "${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/sqlite3.h.3") if(INCLUDE_MANPAGES_IN_INSTALL) install(FILES - "${PROJECT_BINARY_DIR}/docs/man/man3/sqlite3.h.3" + "${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/sqlite3.h.3" RENAME "stumpless_target_sqlite3.h.3" DESTINATION "${CMAKE_INSTALL_MANDIR}/man3" ) diff --git a/tools/cmake/wel.cmake b/tools/cmake/wel.cmake index a14001d96..04b0d2427 100644 --- a/tools/cmake/wel.cmake +++ b/tools/cmake/wel.cmake @@ -4,21 +4,23 @@ list(APPEND STUMPLESS_SOURCES ${PROJECT_SOURCE_DIR}/src/config/wel_supported.c) list(INSERT WRAPTURE_SPECS 0 ${PROJECT_SOURCE_DIR}/tools/wrapture/have_wel_templates.yml) list(APPEND WRAPTURE_SPECS ${PROJECT_SOURCE_DIR}/tools/wrapture/wel_target.yml) -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/config/wel_supported.h - DESTINATION "include/stumpless/config" -) +if(INSTALL_HEADERS) + install( + FILES "${PROJECT_SOURCE_DIR}/include/stumpless/config/wel_supported.h" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/config" + ) -install(FILES - ${PROJECT_SOURCE_DIR}/include/stumpless/target/wel.h - DESTINATION "include/stumpless/target" -) + install( + FILES "${PROJECT_SOURCE_DIR}/include/stumpless/target/wel.h" + DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}/stumpless/target" + ) +endif() -list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/man/man3/wel.h.3) +list(APPEND DOXYGEN_MANPAGES ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/wel.h.3) if(INCLUDE_MANPAGES_IN_INSTALL) install(FILES - ${PROJECT_BINARY_DIR}/docs/man/man3/wel.h.3 + ${PROJECT_BINARY_DIR}/docs/${STUMPLESS_LANGUAGE}/man/man3/wel.h.3 RENAME stumpless_target_wel.h.3 DESTINATION ${CMAKE_INSTALL_MANDIR}/man3 ) diff --git a/tools/doxygen/CppDoxyfile.in b/tools/doxygen/CppDoxyfile.in index 99c4cc229..178707c66 100644 --- a/tools/doxygen/CppDoxyfile.in +++ b/tools/doxygen/CppDoxyfile.in @@ -91,14 +91,12 @@ REFERENCES_LINK_SOURCE = YES USE_HTAGS = NO VERBATIM_HEADERS = YES ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 5 GENERATE_HTML = YES HTML_OUTPUT = html HTML_FILE_EXTENSION = .html HTML_COLORSTYLE_HUE = 220 HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -HTML_TIMESTAMP = YES HTML_DYNAMIC_SECTIONS = NO HTML_INDEX_NUM_ENTRIES = 100 GENERATE_DOCSET = NO @@ -121,7 +119,6 @@ ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -FORMULA_TRANSPARENT = YES USE_MATHJAX = NO MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest SEARCHENGINE = YES @@ -136,7 +133,6 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain GENERATE_RTF = NO RTF_OUTPUT = rtf @@ -159,12 +155,9 @@ SEARCH_INCLUDES = YES SKIP_FUNCTION_MACROS = YES ALLEXTERNALS = NO EXTERNAL_GROUPS = YES -CLASS_DIAGRAMS = YES HIDE_UNDOC_RELATIONS = YES HAVE_DOT = NO DOT_NUM_THREADS = 0 -DOT_FONTNAME = Helvetica -DOT_FONTSIZE = 10 CLASS_GRAPH = YES COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES @@ -181,7 +174,6 @@ DOT_IMAGE_FORMAT = png INTERACTIVE_SVG = NO DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -DOT_TRANSPARENT = NO DOT_MULTI_TARGETS = YES GENERATE_LEGEND = YES DOT_CLEANUP = YES diff --git a/tools/doxygen/Doxyfile.in b/tools/doxygen/Doxyfile.in index 231c40ade..db298578c 100644 --- a/tools/doxygen/Doxyfile.in +++ b/tools/doxygen/Doxyfile.in @@ -1,16 +1,15 @@ # deliberate settings DOXYFILE_ENCODING = UTF-8 INPUT_ENCODING = UTF-8 -INPUT_FILE_ENCODING = UTF-8 PROJECT_NAME = "stumpless" PROJECT_NUMBER = @PROJECT_VERSION_MAJOR@.@PROJECT_VERSION_MINOR@.@PROJECT_VERSION_PATCH@ INPUT = @DOXYGEN_INPUT@ -OUTPUT_DIRECTORY = @PROJECT_DOCS_DIR@ +OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT@ CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = @DOXYGEN_OUTPUT_LANGUAGE@ FILE_PATTERNS = *.h FULL_PATH_NAMES = YES -STRIP_FROM_PATH = @DOXYGEN_INCLUDE_DIR@ @PROJECT_BINARY_DIR@/include +STRIP_FROM_PATH = @DOXYGEN_INPUT@ OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO @@ -26,7 +25,7 @@ EXPAND_ONLY_PREDEF = YES PREDEFINED = __attribute__(x)= SHOW_INCLUDE_FILES = NO -EXAMPLE_PATH = @DOXYGEN_EXAMPLE_DIR@ +EXAMPLE_PATH = @L10N_EXAMPLE_DIR@ EXAMPLE_PATTERNS = *.c *.cpp EXAMPLE_RECURSIVE = NO @@ -38,7 +37,6 @@ HTML_FILE_EXTENSION = .html HTML_COLORSTYLE_HUE = 220 HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -HTML_TIMESTAMP = YES HTML_DYNAMIC_SECTIONS = NO HTML_INDEX_NUM_ENTRIES = 100 @@ -122,7 +120,6 @@ REFERENCES_LINK_SOURCE = YES USE_HTAGS = NO VERBATIM_HEADERS = YES ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 5 GENERATE_DOCSET = NO DOCSET_FEEDNAME = "Doxygen generated docs" DOCSET_BUNDLE_ID = org.doxygen.Project @@ -142,7 +139,6 @@ ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -FORMULA_TRANSPARENT = YES USE_MATHJAX = NO MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest SEARCHENGINE = YES @@ -157,7 +153,6 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain GENERATE_RTF = NO RTF_OUTPUT = rtf @@ -174,12 +169,9 @@ EXPAND_ONLY_PREDEF = NO SKIP_FUNCTION_MACROS = YES ALLEXTERNALS = NO EXTERNAL_GROUPS = YES -CLASS_DIAGRAMS = YES HIDE_UNDOC_RELATIONS = YES HAVE_DOT = NO DOT_NUM_THREADS = 0 -DOT_FONTNAME = Helvetica -DOT_FONTSIZE = 10 CLASS_GRAPH = YES COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES @@ -196,7 +188,6 @@ DOT_IMAGE_FORMAT = png INTERACTIVE_SVG = NO DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -DOT_TRANSPARENT = NO DOT_MULTI_TARGETS = YES GENERATE_LEGEND = YES DOT_CLEANUP = YES diff --git a/tools/pkg-config/stumpless.pc.in b/tools/pkg-config/libstumpless.pc.in similarity index 63% rename from tools/pkg-config/stumpless.pc.in rename to tools/pkg-config/libstumpless.pc.in index b8c573bcb..d4a7c8611 100644 --- a/tools/pkg-config/stumpless.pc.in +++ b/tools/pkg-config/libstumpless.pc.in @@ -3,8 +3,8 @@ exec_prefix=${prefix} libdir=${exec_prefix}/lib includedir=${prefix}/include -Name: @CMAKE_PROJECT_NAME@ -Description: C logging library built for high performance and a rich feature set +Name: libstumpless +Description: a fast and feature-rich C logging library Version: @PROJECT_VERSION@ Libs: -L${libdir} -lstumpless Cflags: -I${includedir} diff --git a/tools/portage/stumpless.ebuild.in b/tools/portage/libstumpless.ebuild.in similarity index 62% rename from tools/portage/stumpless.ebuild.in rename to tools/portage/libstumpless.ebuild.in index 9b40c22a2..aa3646df3 100644 --- a/tools/portage/stumpless.ebuild.in +++ b/tools/portage/libstumpless.ebuild.in @@ -1,4 +1,4 @@ -# Copyright 1999-2023 Gentoo Authors +# Copyright 1999-2024 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 EAPI=8 @@ -8,33 +8,38 @@ inherit cmake DESCRIPTION="a C logging library built for high performance and a rich feature set" HOMEPAGE="http://stumpless.goatshriek.com" if [[ ${PV} == *9999 ]]; then - SRC_URI="https://github.com/goatshriek/stumpless/archive/refs/heads/latest.tar.gz -> stumpless-${PV}.tar.gz" + SRC_URI="https://github.com/goatshriek/stumpless/archive/refs/heads/latest.tar.gz -> libstumpless-${PV}.tar.gz" S="${WORKDIR}/stumpless-latest" SLOT="0" else - SRC_URI="https://github.com/goatshriek/stumpless/archive/refs/tags/v${PV}.tar.gz -> stumpless-${PV}.tar.gz" + SRC_URI="https://github.com/goatshriek/stumpless/archive/refs/tags/v${PV}.tar.gz -> libstumpless-${PV}.tar.gz" SLOT="$(ver_cut 1)/$(ver_cut 2)" fi LICENSE="Apache-2.0" KEYWORDS="~amd64 ~x86" -IUSE="doc examples sockets systemd test threads" +IUSE="chain-targets doc examples man sockets sqlite systemd test threads" DEPEND="test? ( dev-cpp/gtest ) + sqlite? ( dev-db/sqlite ) systemd? ( sys-apps/systemd )" RDEPEND="${DEPEND}" -BDEPEND="doc? ( app-doc/doxygen )" +BDEPEND="doc? ( app-text/doxygen ) + man? ( app-text/doxygen )" # disable test phase if the test USE flag is disabled RESTRICT="!test? ( test )" src_configure() { local mycmakeargs=( + -DENABLE_CHAIN_TARGETS="$(usex chain-targets)" -DENABLE_NETWORK_TARGETS="$(usex sockets)" -DENABLE_JOURNALD_TARGETS="$(usex systemd)" + -DENABLE_SQLITE3_TARGETS="$(usex sqlite)" -DENABLE_THREAD_SAFETY="$(usex threads)" -DINSTALL_EXAMPLES="$(usex examples)" - -DINSTALL_MANPAGES="$(usex doc)" + -DINSTALL_HTML="$(usex doc)" + -DINSTALL_MANPAGES="$(usex man)" ) cmake_src_configure } @@ -45,9 +50,10 @@ src_test() { cmake_build "build-test" # journald tests are unable to detect if journald isn't present - # because of this they fail in a sandbox without journald access + # because of this they fail without journald access # so we exclude them from the test suite in the ebuild - # running the test suite yourself (outside of the ebuild sandbox) should pass - local myctestargs=( -E journald ) + # running the test suite outside of the ebuild should pass + # we also exclude network tests to avoid generating any network traffic + local myctestargs=( --exclude-regex "journald|network|tcp|udp" ) cmake_src_test } diff --git a/tools/wrapture/element.yml b/tools/wrapture/element.yml index 21170c337..59e8e8d4a 100644 --- a/tools/wrapture/element.yml +++ b/tools/wrapture/element.yml @@ -274,6 +274,8 @@ classes: doc: | The name of the Param at the given index. If there is no Param, or some other error occurs, a StumplessException will be thrown. + type: + name: "const char *" wrapped-function: name: "stumpless_get_param_name_by_index" includes: "stumpless/element.h"