Refactor signal handling for robustness and platform correctness

- POSIX: use a signal-safe self-pipe mechanism and safer shutdown handling
- Windows: switch to console control handler and improve lifecycle handling

Overall improves robustness, correctness, and alignment with platform expectations.

Author: erbsland-dev

doc/chapters/reference/terminal.rst

@@ -235,3 +235,8 @@ Interface
     :members:
 
 .. doxygentypedef:: erbsland::cterm::TerminalPtr
+
+.. doxygenenum:: erbsland::cterm::TerminalFlag
+
+.. doxygenclass:: erbsland::cterm::TerminalFlags
+    :members:

include/erbsland/cterm/TerminalFlags.hpp

@@ -0,0 +1,5 @@
+#pragma once
+#include "../../../src/erbsland/cterm/TerminalFlags.hpp"
+// !!! WARNING - THIS IS A GENERATED FILE - DO NOT EDIT MANUALLY !!!
+// This file was generated by the `generate_header_files.py` script.
+

src/erbsland/cterm/Backend.hpp

@@ -7,6 +7,7 @@
 #include "Input.hpp"
 #include "MoveMode.hpp"
 #include "Size.hpp"
+#include "TerminalFlags.hpp"
 
 #include <memory>
 #include <optional>
@@ -119,15 +120,15 @@ class Backend : public std::enable_shared_from_this<Backend> {
     /// In `Input::Mode::ReadLine` mode, the user has to enter a character and press enter.
     /// @param timeout Maximum wait time in `Mode::Key`; ignored in `Mode::ReadLine`.
     /// @return The parsed key event, or an invalid key if no supported input was read.
-    [[nodiscard]] virtual auto readKey(std::chrono::milliseconds timeout = {}) -> Key = 0;
+    [[nodiscard]] virtual auto readKey(std::chrono::milliseconds timeout) -> Key = 0;
     /// Read text input in the terminal.
     /// Can be ignored in `Input::Mode::Key` mode.
     /// @return The read text, without line breaks.
     [[nodiscard]] virtual auto readLine() -> std::string = 0;
 
 public:
     /// Create the default backend for this platform.
-    [[nodiscard]] static auto createPlatformDefault() -> BackendPtr;
+    [[nodiscard]] static auto createPlatformDefault(TerminalFlags terminalFlags) -> BackendPtr;
 };
 
 

src/erbsland/cterm/CMakeLists.txt

@@ -53,6 +53,7 @@ target_sources(erbsland-color-term PRIVATE
         String.hpp
         Terminal.cpp
         Terminal.hpp
+        TerminalFlags.hpp
         Text.hpp
         TextAnimation.hpp
         Tile9Style.cpp

src/erbsland/cterm/Terminal.cpp

@@ -14,8 +14,24 @@
 namespace erbsland::cterm {
 
 
-Terminal::Terminal(const Size size) : _size{size.componentMin(cMaximumSize).componentMax(cMinimumSize)} {
-    _backend = Backend::createPlatformDefault();
+Terminal::Terminal() : Terminal(Size{80, 25}, TerminalFlags{}) {
+}
+
+Terminal::Terminal(const TerminalFlags flags) : Terminal(Size{80, 25}, flags) {
+}
+
+Terminal::Terminal(const Size size, const TerminalFlags flags) :
+    _flags{flags}, _size{size.componentMin(cMaximumSize).componentMax(cMinimumSize)} {
+    _backend = Backend::createPlatformDefault(flags);
+    _input.setBackend(_backend);
+    _lineBuffer.setBackend(_backend);
+}
+
+Terminal::Terminal(BackendPtr backend, const Size size) :
+    _backend{std::move(backend)}, _size{size.componentMin(cMaximumSize).componentMax(cMinimumSize)} {
+    if (_backend == nullptr) {
+        _backend = Backend::createPlatformDefault(TerminalFlags{});
+    }
     _input.setBackend(_backend);
     _lineBuffer.setBackend(_backend);
 }
@@ -96,7 +112,7 @@ void Terminal::setBackBufferEnabled(const bool enabled) noexcept {
 void Terminal::setBackend(BackendPtr backend) noexcept {
     if (_backend != backend) {
         if (backend == nullptr) {
-            _backend = Backend::createPlatformDefault();
+            _backend = Backend::createPlatformDefault(_flags);
         } else {
             _backend = std::move(backend);
         }

src/erbsland/cterm/Terminal.hpp

@@ -9,6 +9,7 @@
 #include "MoveMode.hpp"
 #include "Size.hpp"
 #include "String.hpp"
+#include "TerminalFlags.hpp"
 #include "UpdateSettings.hpp"
 #include "WritableBuffer.hpp"
 
@@ -64,10 +65,21 @@ class Terminal {
     };
 
 public:
+    /// Create a new terminal instance with default values.
+    explicit Terminal();
     /// Create a new terminal instance.
+    /// @param flags The terminal flags to use.
+    explicit Terminal(TerminalFlags flags = {});
+    /// Create a new terminal instance.
+    /// The size is automatically bounded to the minimum and maximum supported sizes.
+    /// @param size The fallback terminal size used when automatic detection is unavailable.
+    /// @param flags The terminal flags to use.
+    explicit Terminal(Size size = {80, 25}, TerminalFlags flags = {});
+    /// Create a new terminal instance with a custom backend.
     /// The size is automatically bounded to the minimum and maximum supported sizes.
+    /// @param backend The backend to use for the terminal.
     /// @param size The fallback terminal size used when automatic detection is unavailable.
-    explicit Terminal(Size size = {80, 25});
+    explicit Terminal(BackendPtr backend, Size size = {80, 25});
 
 public: // settings
     /// Get the currently configured or detected drawable terminal size.
@@ -93,7 +105,7 @@ class Terminal {
     /// Set if dynamic terminal size detection is enabled.
     /// Can only be enabled while the output mode is `OutputMode::FullControl`.
     /// @param enabled `true` to enable automatic size detection.
-    void setSizeDetectionEnabled(const bool enabled) noexcept;
+    void setSizeDetectionEnabled(bool enabled) noexcept;
     /// Check whether line buffering is enabled for incremental writes.
     /// @return `true` if text output is collected until a newline or `flush()`.
     [[nodiscard]] auto lineBufferEnabled() const noexcept -> bool;
@@ -294,6 +306,7 @@ class Terminal {
     void printLinePart(const char text[]) noexcept { write(text); }
 
 private:
+    TerminalFlags _flags;                             ///< Flags for the terminal behaviour.
     BackendPtr _backend;                              ///< The backend that is used by the terminal.
     OutputMode _outputMode{OutputMode::FullControl};  ///< The current output mode.
     bool _sizeDetectionEnabled{true};                 ///< If size detection is enabled.

src/erbsland/cterm/TerminalFlags.hpp

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Tobias Erbsland - https://erbsland.dev
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+
+#include <cstdint>
+#include <type_traits>
+
+
+namespace erbsland::cterm {
+
+/// A terminal flag.
+enum class TerminalFlag : uint8_t {
+    /// Disables signal handling to restore the screen when the application is terminated.
+    /// If this flag is set, you must ensure that the `restoreScreen()` method is called when the application
+    /// is terminated by a signal. Otherwise, the terminal will not be restored properly.
+    NoSignalHandling = 1 << 0,
+};
+
+/// A set of terminal flags.
+/// Terminal flags control the behavior of the built-in terminal backend.
+/// These flags can only be set at construction time and cannot be modified after that.
+class TerminalFlags {
+public:
+    using Mask = uint8_t;
+    using Enum = TerminalFlag;
+
+public:
+    /// Create a combined set of flags.
+    template <typename... tFlags>
+        requires(sizeof...(tFlags) > 0 && (std::is_same_v<Enum, tFlags> && ...))
+    constexpr TerminalFlags(tFlags... flags) : // NOLINT(*-explicit-constructor)
+        _flags{static_cast<Mask>((static_cast<Mask>(flags) | ...))} {}
+
+    // defaults
+    TerminalFlags() = default;
+    TerminalFlags(const TerminalFlags &) = default;
+    auto operator=(const TerminalFlags &) -> TerminalFlags & = default;
+
+public:
+    auto operator|(const TerminalFlag flag) const -> TerminalFlags {
+        return TerminalFlags{static_cast<Mask>(_flags | static_cast<Mask>(flag))};
+    }
+    friend auto operator|(const TerminalFlag flag, const TerminalFlags flags) -> TerminalFlags {
+        return TerminalFlags{static_cast<Mask>(flags._flags | static_cast<Mask>(flag))};
+    }
+    friend auto operator|(const TerminalFlag flag1, const TerminalFlag flag2) -> TerminalFlags {
+        return TerminalFlags{flag1, flag2};
+    }
+    friend auto operator|(const TerminalFlags flags1, const TerminalFlags flags2) -> TerminalFlags {
+        return TerminalFlags{static_cast<Mask>(flags1._flags | flags2._flags)};
+    }
+
+public:
+    /// Test if a flag is set.
+    [[nodiscard]] auto has(const TerminalFlag flag) const noexcept -> bool {
+        return (_flags & static_cast<Mask>(flag)) != 0;
+    }
+    /// Set a flag.
+    void set(const TerminalFlag flag, const bool enabled = true) {
+        if (enabled) {
+            _flags |= static_cast<Mask>(flag);
+        } else {
+            _flags &= ~static_cast<Mask>(flag);
+        }
+    }
+    /// Clear a flag.
+    void clear(const TerminalFlag flag) { _flags &= ~static_cast<Mask>(flag); }
+
+private:
+    explicit TerminalFlags(const Mask flags) : _flags(flags) {}
+
+private:
+    Mask _flags{0};
+};
+
+}

src/erbsland/cterm/all.hpp

@@ -37,6 +37,7 @@
 #include "Size.hpp"
 #include "String.hpp"
 #include "Terminal.hpp"
+#include "TerminalFlags.hpp"
 #include "Text.hpp"
 #include "TextAnimation.hpp"
 #include "Tile9Style.hpp"

src/erbsland/cterm/impl/CMakeLists.txt

@@ -26,10 +26,14 @@ if (WIN32)
     target_sources(erbsland-color-term PRIVATE
             WindowsBackend.cpp
             WindowsBackend.hpp
+            WindowsSignalDispatcher.cpp
+            WindowsSignalDispatcher.hpp
     )
 else ()
     target_sources(erbsland-color-term PRIVATE
             PosixBackend.cpp
             PosixBackend.hpp
+            PosixSignalDispatcher.cpp
+            PosixSignalDispatcher.hpp
     )
 endif ()

src/erbsland/cterm/impl/PosixBackend.cpp

@@ -2,21 +2,22 @@
 // SPDX-License-Identifier: Apache-2.0
 #include "PosixBackend.hpp"
 
+
+#include "PosixSignalDispatcher.hpp"
+
 #include <fcntl.h>
 #include <sys/ioctl.h>
 #include <sys/select.h>
 #include <unistd.h>
 
-#include <array>
-#include <csignal>
 #include <iostream>
 #include <thread>
 
 
 namespace erbsland::cterm {
 
-auto Backend::createPlatformDefault() -> BackendPtr {
-    return impl::PosixBackend::getOrCreate();
+auto Backend::createPlatformDefault(const TerminalFlags terminalFlags) -> BackendPtr {
+    return impl::PosixBackend::getOrCreate(terminalFlags);
 }
 
 }
@@ -25,17 +26,19 @@ namespace erbsland::cterm::impl {
 
 std::mutex PosixBackend::_instanceMutex;
 PosixBackend *PosixBackend::_instance = nullptr;
-std::array<struct sigaction, PosixBackend::cSignals.size()> PosixBackend::_previousSignalActions{};
 
-PosixBackend::PosixBackend() {
+PosixBackend::PosixBackend(TerminalFlags terminalFlags) : _terminalFlags{terminalFlags} {
     // called once per application.
     _instance = this;
-    registerExitHandlers();
+    if (!_terminalFlags.has(TerminalFlag::NoSignalHandling)) {
+        _signalHandler = std::make_unique<PosixSignalDispatcher>(
+            [this](const int signalNumber) -> void { handleProcessSignal(signalNumber); });
+    }
 }
 
 PosixBackend::~PosixBackend() {
-    unregisterExitHandlers();
-    std::lock_guard lock{_instanceMutex};
+    _signalHandler.reset();
+    std::scoped_lock lock{_instanceMutex};
     if (_instance != nullptr) {
         _instance->restorePlatform();
         _instance = nullptr;
@@ -57,9 +60,9 @@ void PosixBackend::restorePlatform() {
         if (_isAlternateScreenActive) {
             std::cout << "\x1b[?1049l"; // disable alternative screen buffer
         }
-        std::cout << "\x1b[0m"; // restore to default color
-        std::cout << "\x1b[?25h"; // make the cursor visible.
-        std::cout << "\n"; // add a newline for compatibility.
+        std::cout << "\x1b[0m";         // restore to default color
+        std::cout << "\x1b[?25h";       // make the cursor visible.
+        std::cout << "\n";              // add a newline for compatibility.
         std::cout.flush();
     }
     if (_keyInputSessionActive) {
@@ -191,21 +194,21 @@ auto PosixBackend::readLine() -> std::string {
     return input;
 }
 
-auto PosixBackend::getOrCreate() noexcept -> BackendPtr {
-    std::lock_guard lock{_instanceMutex};
+auto PosixBackend::getOrCreate(const TerminalFlags terminalFlags) noexcept -> BackendPtr {
+    std::scoped_lock lock{_instanceMutex};
     if (_instance == nullptr) {
-        return std::make_shared<PosixBackend>();
+        return std::make_shared<PosixBackend>(terminalFlags);
     }
     return _instance->shared_from_this();
 }
 
 auto PosixBackend::instance() noexcept -> PosixBackend * {
-    std::lock_guard lock(_instanceMutex);
+    std::scoped_lock lock(_instanceMutex);
     return _instance;
 }
 
 void PosixBackend::restoreGlobalPlatform() noexcept {
-    std::lock_guard lock(_instanceMutex);
+    std::scoped_lock lock(_instanceMutex);
     if (_instance == nullptr) {
         return;
     }
@@ -300,31 +303,14 @@ void PosixBackend::restoreKeyInputSession() {
     _keyInputSessionActive = false;
 }
 
-void PosixBackend::registerExitHandlers() {
-    std::atexit(&PosixBackend::onExit);
+void PosixBackend::handleProcessSignal(const int signalNumber) noexcept {
+    restoreGlobalPlatform();
     struct sigaction action{};
-    action.sa_handler = &PosixBackend::onSignal;
+    action.sa_handler = SIG_DFL;
     sigemptyset(&action.sa_mask);
     action.sa_flags = 0;
-    for (std::size_t index = 0; index < cSignals.size(); ++index) {
-        sigaction(cSignals[index], &action, &_previousSignalActions[index]);
-    }
-}
-
-void PosixBackend::unregisterExitHandlers() {
-    for (std::size_t index = 0; index < cSignals.size(); ++index) {
-        sigaction(cSignals[index], &_previousSignalActions[index], nullptr);
-    }
-}
-
-void PosixBackend::onExit() noexcept {
-    restoreGlobalPlatform();
-}
-
-void PosixBackend::onSignal(const int signalNumber) noexcept {
-    restoreGlobalPlatform();
-    std::signal(signalNumber, SIG_DFL);
-    std::raise(signalNumber);
+    sigaction(signalNumber, &action, nullptr);
+    kill(getpid(), signalNumber);
     std::_Exit(128 + signalNumber);
 }