Inheritance diagram for clues::TermTracer:

Public Member Functions
	TermTracer (const TermTracer &)=delete

TermTracer &	operator= (const TermTracer &)=delete

Protected Types
enum class	FollowExecContext { YES , NO , ASK , CHECK_PATH , CHECK_GLOB }
	What to do upon execve. More...

enum class	FollowChildMode { YES , NO , ASK , THREADS }

enum class	Flag { SEEN_INITIAL_EXEC = 1 << 0 , DROPPED_TO_LAST_TRACEE = 1 << 1 }

using	Flags = cosmos::BitMask<Flag>

Protected Member Functions
bool	processPars ()

void	printSyscalls ()

void	printABISyscalls (const std::string &abi)

void	printABIs ()

cosmos::ExitStatus	main (const int argc, const char **argv) override

bool	configureTracee (const cosmos::ProcessID pid)

void	runTrace ()

void	configureLogger ()

std::string	formatTraceeInvocation (const Tracee &tracee)

std::string	formatTraceeInvocation (const std::string &exe, const cosmos::StringVector &cmdline) const

void	printPar (std::ostream &trace, const SystemCallItem &value) const

void	printParsOnEntry (std::ostream &trace, const SystemCall::ParameterVector &pars) const

void	printParsOnExit (std::ostream &trace, const SystemCall::ParameterVector &pars) const

bool	followExecutionContext (Tracee &tracee)

std::ostream &	traceStream (const Tracee &tracee, const bool new_line=true)
	Returns the currently active trace output stream, starting a new output line.

void	startNewLine (std::ostream &trace, const Tracee &tracee)
	Start a new output line concerning `tracee.

bool	storeUnfinishedSyscallCtx ()
	Store an active system call in m_unfinished_syscalls.

void	checkResumedSyscall (const Tracee &tracee)
	Check whether `tracee` has an unfinished system call pending.

bool	hasActiveSyscall (const Tracee &tracee) const

bool	hasActiveSyscall (const cosmos::ProcessID pid) const

const SystemCall *	activeSyscall (const cosmos::ProcessID pid) const

const SystemCall *	activeSyscall (const Tracee &tracee) const

const SystemCall *	activeSyscall () const

const SystemCall *	findSyscall (const Tracee &tracee) const
	Find any active or unfinished system call for `pid`.

bool	isExecSyscall (const SystemCall &sc) const

bool	isEnabled (const SystemCall *sc) const
	Returns `true` if `sc` is set and supposed to the printed.

const SystemCall *	currentSyscall (const Tracee &tracee) const
	Returns the system call last seen for `tracee`, or `nullptr` if there's none.

void	cleanupTracee (const Tracee &tracee)

void	updateTracee (const Tracee &tracee, const cosmos::ProcessID old_pid)
	Update internal data structures in case a tracee changed PID.

bool	seenInitialExec () const

void	abortSyscall (const Tracee &tracee)
	Abort syscall if one was active for `tracee`.

void	checkABI (const Tracee &tracee, const SystemCallInfo &info)
	Checks the current system call's ABI and reports ABI changes.

void	syscallEntry (Tracee &tracee, const SystemCall &sc, const StatusFlags flags) override
	A system call is about to be executed in the Tracee.

void	syscallExit (Tracee &tracee, const SystemCall &sc, const StatusFlags flags) override
	A system call has been finished.

void	signaled (Tracee &tracee, const cosmos::SigInfo &info) override
	The tracee has received a signal.

void	attached (Tracee &tracee) override
	The tracee is now properly attached to.

void	exited (Tracee &tracee, const cosmos::WaitStatus status, const StatusFlags flags) override
	The tracee is about to end execution.

void	newExecutionContext (Tracee &tracee, const std::string &old_exe, const cosmos::StringVector &old_cmdline, const std::optional< cosmos::ProcessID > old_pid) override
	A new program is executed in the tracee.

void	newChildProcess (Tracee &parent, Tracee &child, const cosmos::ptrace::Event event, const StatusFlags flags) override
	A new child process has been created.

void	stopped (Tracee &tracee) override
	The tracee entered group-stop due to a stopping signal.

void	disappeared (Tracee &tracee, const cosmos::ChildState &data) override
	The tracee disappeared for unclear reasons.

Protected Member Functions inherited from clues::EventConsumer
virtual void	resumed (Tracee &tracee)
	The tracee resumed due to SIGCONT.

virtual void	vforkComplete (Tracee &parent, TraceePtr child)
	A `vfork()` in `parent` for `child` completed.

Protected Attributes
Args	m_args
	Command line arguments and parser.

cosmos::StdLogger	m_logger
	cosmos ILogger instance for clues library logging.

cosmos::Init	m_cosmos

Engine	m_engine
	libclues main object.

bool	m_print_pars = true
	Whether to print system call parameters at all (-s 0 disables it).

size_t	m_par_truncation_len = 64
	Maximum length of of system call parameter values to print before truncating the output.

std::string	m_exec_context_arg
	optional argument to m_follow_exec (e.g. path, glob, script)

std::set< SystemCallNr >	m_syscall_filter
	Whitelist of system calls to trace, if any.

FollowExecContext	m_follow_exec = FollowExecContext::YES
	Behaviour upon newExecutionContext()

FollowChildMode	m_follow_children = FollowChildMode::NO
	Behaviour upon newChildProcess()

size_t	m_num_tracees = 0
	The number of tracees we're currently dealing with.

Flags	m_flags
	State flags with global context or carried between different callbacks.

cosmos::ProcessID	m_main_tracee_pid
	The PID of the main process we're tracing (the one we created or attached to).

std::optional< cosmos::WaitStatus >	m_main_status
	The WaitStatus of the main process we've seen upon it exiting.

std::optional< std::tuple< cosmos::ProcessID, const SystemCall * > >	m_active_syscall
	The currently active system call, if any.

std::map< cosmos::ProcessID, const SystemCall * >	m_unfinished_syscalls
	Unfinished / preempted system calls.

std::map< cosmos::ProcessID, std::pair< cosmos::ProcessID, cosmos::ptrace::Event > >	m_new_tracees
	Newly created tracees that haven't seen any ptrace stop yet.

clues::ABI	m_last_abi = clues::ABI::UNKNOWN
	The ABI of the last system call we've seen.

Additional Inherited Members
Public Types inherited from clues::EventConsumer
enum class	StatusFlag { INTERRUPTED = 1 << 0 , RESUMED = 1 << 1 , LOST_TO_MT_EXIT = 1 << 2 , ABI_CHANGED = 1 << 3 , CLONED_THREAD = 1 << 4 }
	Different status flags that can appear in callbacks. More...

using	StatusFlags = cosmos::BitMask<StatusFlag>

Detailed Description

Definition at line 25 of file TermTracer.hxx.

Member Typedef Documentation

◆ Flags

using clues::TermTracer::Flags = cosmos::BitMask<Flag>

protected

Definition at line 58 of file TermTracer.hxx.

Member Enumeration Documentation

◆ Flag

enum class clues::TermTracer::Flag

strongprotected

Enumerator
SEEN_INITIAL_EXEC	whether we've seen a ChildTracee's initial newExecutionContext().
DROPPED_TO_LAST_TRACEE	whether we've returned to tracing only a single PID anymore.

Definition at line 53 of file TermTracer.hxx.

                        {
                SEEN_INITIAL_EXEC      = 1 << 0, 
                DROPPED_TO_LAST_TRACEE = 1 << 1, 
        };

◆ FollowChildMode

enum class clues::TermTracer::FollowChildMode

strongprotected

Definition at line 46 of file TermTracer.hxx.

◆ FollowExecContext

enum class clues::TermTracer::FollowExecContext

strongprotected

What to do upon execve.

Definition at line 38 of file TermTracer.hxx.

                                     {
                YES,
                NO,
                ASK,
                CHECK_PATH,
                CHECK_GLOB
        };

Constructor & Destructor Documentation

◆ TermTracer()

clues::TermTracer::TermTracer ( )

Definition at line 65 of file TermTracer.cxx.

                       :
                m_engine{*this} {
}

Member Function Documentation

◆ abortSyscall()

void clues::TermTracer::abortSyscall ( const Tracee & tracee )

protected

Abort syscall if one was active for tracee.

A condition in tracee occurred which requires to abort a possible already started system call trace. This function performs the necessary steps to do so.

Definition at line 741 of file TermTracer.cxx.

                                                  {
        // obtain this information before the active syscall is reset below
        const auto is_enabled = isEnabled(currentSyscall(tracee));
 
        if (hasActiveSyscall(tracee)) {
                m_active_syscall.reset();
        } else if (is_enabled) {
                checkResumedSyscall(tracee);
        }
 
        if (is_enabled) {
                /*
                 * finish any possibly pending system call to make clear it
                 * never visibly returned.
                 */
                traceStream(tracee, false) << ") = ?\n";
        }
}

◆ activeSyscall() [1/3]

const SystemCall * clues::TermTracer::activeSyscall ( ) const

inlineprotected

Definition at line 144 of file TermTracer.hxx.

                                                {
                if (!m_active_syscall)
                        return nullptr;
 
                return std::get<const SystemCall*>(*m_active_syscall);
        }

◆ activeSyscall() [2/3]

const SystemCall * clues::TermTracer::activeSyscall ( const cosmos::ProcessID pid ) const

inlineprotected

Definition at line 127 of file TermTracer.hxx.

                                                                         {
                if (!m_active_syscall)
                       return nullptr;
 
                const auto info = *m_active_syscall;
 
                if (std::get<cosmos::ProcessID>(info) != pid) {
                        return nullptr;
                }
 
                return std::get<const SystemCall*>(info);
        }

◆ activeSyscall() [3/3]

const SystemCall * clues::TermTracer::activeSyscall ( const Tracee & tracee ) const

inlineprotected

Definition at line 140 of file TermTracer.hxx.

                                                                    {
                return activeSyscall(tracee.pid());
        }

◆ attached()

void clues::TermTracer::attached ( Tracee & tracee )

overrideprotectedvirtual

The tracee is now properly attached to.

This should be the first call that that is visible for a tracee. It occurs when the ptrace() relationship is established and a defined tracing state has been reached. The Tracee will be in PTRACE_EVENT_STOP.

The following situations can cause an attached() callback:

tracee was actively registered via Engine::addTracee().
an already present tracee created a new thread or child process. This is preceded by newChildProcess().
an existing process has been attached to via Engine::addTracee(const cosmos::ProcessID, ..., AttachThreads{true}). Any additional threads that exist in the process will then automatically be attached to. tracee.isInitiallyAttachedThread() will return true in this case.

Reimplemented from clues::EventConsumer.

Definition at line 447 of file TermTracer.cxx.

                                        {
        if (m_num_tracees++ == 0) {
                // the initial process, don't print anything special in this case
                return;
        } else if (tracee.isInitiallyAttachedThread()) {
                // part of the initial attach procedure when attaching to a
                // possibly multi-threaded existing process.
                traceStream(tracee) << "→ additionally attached thread\n";
        } else if (auto it = m_new_tracees.find(tracee.pid()); it != m_new_tracees.end()) {
                auto [parent, event] = it->second;
 
                traceStream(tracee) << "→ automatically attached (created by PID " << parent << " via " << to_label(event) << ")\n";
                m_new_tracees.erase(it);
        } else {
                traceStream(tracee) << "unknown Tracee " << cosmos::to_integral(tracee.pid()) << " attached?!";
        }
}

◆ checkABI()

void clues::TermTracer::checkABI	(	const Tracee &	tracee,
		const SystemCallInfo &	info )

protected

Checks the current system call's ABI and reports ABI changes.

Definition at line 760 of file TermTracer.cxx.

                                                                          {
        bool report_abi = false;
 
        if (m_last_abi == clues::ABI::UNKNOWN) {
                // check if the initial system call already has some
                // non-default ABI.
                if (!clues::is_default_abi(info.abi()))
                        report_abi = true;
        } else if (info.abi() != m_last_abi) {
                report_abi = true;
        }
 
        if (report_abi) {
                traceStream(tracee) << "[system call ABI changed to " << get_abi_label(info.abi()) << "]\n";
        }
}

◆ checkResumedSyscall()

void clues::TermTracer::checkResumedSyscall ( const Tracee & tracee )

protected

Check whether tracee has an unfinished system call pending.

If tracee has an unfinished system call pending in m_unfinished_syscalls, then clean up the data structure and output appropriate text to indicate the situation.

Definition at line 686 of file TermTracer.cxx.

                                                         {
        if (hasActiveSyscall(tracee))
                return;
 
        /*
         * when there's no active system call then we expect one to be stored
         * as unfinished, otherwise something is off.
         */
 
        auto node = m_unfinished_syscalls.extract(tracee.pid());
        assert(!node.empty());
        auto sc = node.mapped();
 
        auto &trace = traceStream(tracee);
        trace << "<resuming ...> " << sc->name();
        if (sc->hasOutParameter()) {
                trace << "(..., ";
        } else {
                trace << "(...";
        }
}

◆ cleanupTracee()

void clues::TermTracer::cleanupTracee ( const Tracee & tracee )

protected

Definition at line 708 of file TermTracer.cxx.

                                                   {
        /* remove the given tracee from all bookkeeping */
        if (hasActiveSyscall(tracee)) {
                m_active_syscall.reset();
        } else {
                m_unfinished_syscalls.erase(tracee.pid());
        }
 
        m_new_tracees.erase(tracee.pid());
 
        if (--m_num_tracees == 1) {
                m_flags.set(Flag::DROPPED_TO_LAST_TRACEE);
        }
}

◆ configureLogger()

void clues::TermTracer::configureLogger ( )

protected

Definition at line 250 of file TermTracer.cxx.

                                 {
        // enable errors and warnings by default
        m_logger.setChannels(true, true, false, false);
        m_logger.configFromEnvVar("CLUES_LOGGING");
        clues::set_logger(m_logger);
}

◆ configureTracee()

bool clues::TermTracer::configureTracee ( const cosmos::ProcessID pid )

protected

Definition at line 777 of file TermTracer.cxx.

                                                          {
        // this is only for newly created child processes, so set it right away
        m_flags.set(Flag::SEEN_INITIAL_EXEC);
        TraceePtr tracee;
        try {
                /* strace ties the attach threads behaviour to `-f`. There
                 * can be situations when this is not helpful. Thus we do the
                 * same but offer a `-1` switch to opt out of this and only
                 * attach to the single thread specified on the command line.
                 */
                tracee = m_engine.addTracee(pid,
                                FollowChildren{m_follow_children == FollowChildMode::NO ? false : true},
                                AttachThreads{m_follow_children == FollowChildMode::NO || m_args.no_initial_threads_attach.isSet() ? false : true});
        } catch (const cosmos::ApiError &e) {
                std::cerr << "Failed to attach to PID " << pid << ": " << e.msg() << "\n";
                if (e.errnum() == cosmos::Errno::PERMISSION) {
                        std::cerr << "You need to be root to attach to processes not owned by you\n";
                        std::cerr << "The YAMA kernel security extension can also prevent attaching your own processes.\n";
                        std::cerr << "This also happens when another process is already tracing this process.\n";
                }
                return false;
        }
 
        traceStream(*tracee, false) << "--- tracing " << formatTraceeInvocation(*tracee) << " ---\n";
 
        m_main_tracee_pid = tracee->pid();
 
        return true;
}

◆ currentSyscall()

const SystemCall * clues::TermTracer::currentSyscall ( const Tracee & tracee ) const

protected

Returns the system call last seen for tracee, or nullptr if there's none.

This checks both the currently active as well as any unfinished system calls for tracee.

Definition at line 660 of file TermTracer.cxx.

                                                                       {
        if (m_active_syscall) {
                auto &[pid, syscall] = *m_active_syscall;
 
                if (pid == tracee.pid()) {
                        return syscall;
                }
        }
 
        auto it = m_unfinished_syscalls.find(tracee.pid());
        if (it != m_unfinished_syscalls.end()) {
                return it->second;
        }
 
        return nullptr;
}

◆ disappeared()

void clues::TermTracer::disappeared	(	Tracee &	tracee,
		const cosmos::ChildState &	data )

overrideprotectedvirtual

The tracee disappeared for unclear reasons.

This callback can occur in a number of special situations like:

another thread of the same process called exit(). This is not always caught as an exit event, which would lead to a call to exited(). This is especially the case when the other thread which calls exit() is not also traced.
generally the ptrace() documentation says that a tracee can disappear at any time without warning, which is unlucky. libclues attempts to provide as much contextual information as possible. In the case of disappeared(), the cause remains uncertain, however.

When this call occurs then the tracee can no longer be accessed via the tracing API. data still tells whether the tracee exited regularly or due to a signal.

Reimplemented from clues::EventConsumer.

Definition at line 497 of file TermTracer.cxx.

                                                                         {
        abortSyscall(tracee);
 
        traceStream(tracee) << "!!! disappeared (e.g. exit() or execve() in another thread)\n";
 
        if (data.exited()) {
                traceStream(tracee) << "+++ exited with " << cosmos::to_integral(*data.status) << " +++\n";
        } else {
                traceStream(tracee) << "+++ killed by signal " << cosmos::to_integral(data.signal->raw()) << " +++\n";
        }
 
        if (tracee.pid() == m_main_tracee_pid) {
                /*
                 * Here we get a more complex cosmos::ChildState instead of
                 * WaitStatus as in the other callbacks. Convert it into a
                 * WaitStatus so that we can treat all exit paths
                 * homogeneously.
                 */
                m_main_status = cosmos::WaitStatus{data};
        }
 
        cleanupTracee(tracee);
}

◆ exited()

void clues::TermTracer::exited	(	Tracee &	tracee,
		const cosmos::WaitStatus	status,
		const StatusFlags	flags )

overrideprotectedvirtual

The tracee is about to end execution.

The tracee is about to either exit regularly, to be killed by a signal or to disappear due to an execve() in a multi-threaded process.

When this callback occurs the tracee can still be inspected using ptrace(). Once execution is continued the tracer <-> tracee relationship is lost.

If the exit happens due to an execve in a multi-threaded process then Status::LOST_TO_MT_EXIT is set in flags.

Reimplemented from clues::EventConsumer.

Definition at line 465 of file TermTracer.cxx.

                                                                                              {
        if (tracee.prevState() == Tracee::State::SYSCALL_ENTER_STOP) {
                abortSyscall(tracee);
        }
 
        if (flags[StatusFlag::LOST_TO_MT_EXIT]) {
                auto &trace = traceStream(tracee);
                trace << "--- <lost to exit or execve in another thread> ---\n";
        }
 
        if (status.exited()) {
                traceStream(tracee) << "+++ exited with " << cosmos::to_integral(*status.status()) << " +++\n";
                if (!seenInitialExec()) {
                        traceStream(tracee) << "!!! failed to execute the specified program\n";
                }
        } else {
                traceStream(tracee) << "+++ killed by signal " << cosmos::to_integral(status.termSig()->raw()) << " +++\n";
        }
 
        if (tracee.pid() == m_main_tracee_pid) {
                m_main_status = status;
        }
 
        cleanupTracee(tracee);
}

◆ findSyscall()

const SystemCall * clues::TermTracer::findSyscall ( const Tracee & tracee ) const

protected

Find any active or unfinished system call for pid.

Since system calls can be preempted by other tracees we sometimes need to lookup a SystemCall instance in both, the currently active system call and the unfinished system calls. This is mostly relevant during PTRACE_EVENT stops.

If no entry is found for pid, then nullptr is returned.

Definition at line 640 of file TermTracer.cxx.

                                                                    {
        if (const auto syscall = activeSyscall(tracee); syscall)
                return syscall;
 
        if (auto it = m_unfinished_syscalls.find(tracee.pid()); it != m_unfinished_syscalls.end()) {
                return it->second;
        }
 
        return nullptr;
}

◆ followExecutionContext()

bool clues::TermTracer::followExecutionContext ( Tracee & tracee )

protected

Definition at line 584 of file TermTracer.cxx.

                                                      {
        switch (m_follow_exec) {
                case FollowExecContext::YES: return true;
                case FollowExecContext::NO: return false;
                case FollowExecContext::ASK: {
                        std::cout << "Follow into new execution context?\n";
                        return ask_yes_no();
                } case FollowExecContext::CHECK_PATH: {
                        return m_exec_context_arg == tracee.executable();
                } case FollowExecContext::CHECK_GLOB: {
                        return ::fnmatch(m_exec_context_arg.c_str(), tracee.executable().c_str(), 0) == 0;
                }
                default:
                        return false;
        }
}

◆ formatTraceeInvocation() [1/2]

std::string clues::TermTracer::formatTraceeInvocation	(	const std::string &	exe,
		const cosmos::StringVector &	cmdline ) const

protected

Definition at line 333 of file TermTracer.cxx.

                                                         {
        std::stringstream ss;
        ss << exe << " [";
        bool first = true;
        for (const auto &arg: cmdline) {
                if (first) {
                        first = false;
                } else {
                        ss << ", ";
                }
                ss << "\"" << arg << "\"";
        }
 
        ss << "]";
 
        return ss.str();
}

◆ formatTraceeInvocation() [2/2]

std::string clues::TermTracer::formatTraceeInvocation ( const Tracee & tracee )

protected

Definition at line 329 of file TermTracer.cxx.

                                                                 {
        return formatTraceeInvocation(tracee.executable(), tracee.cmdLine());
}

◆ hasActiveSyscall() [1/2]

bool clues::TermTracer::hasActiveSyscall ( const cosmos::ProcessID pid ) const

inlineprotected

Definition at line 123 of file TermTracer.hxx.

                                                               {
                return activeSyscall(pid) != nullptr;
        }

◆ hasActiveSyscall() [2/2]

bool clues::TermTracer::hasActiveSyscall ( const Tracee & tracee ) const

inlineprotected

Definition at line 119 of file TermTracer.hxx.

                                                          {
                return hasActiveSyscall(tracee.pid());
        }

◆ isEnabled()

bool clues::TermTracer::isEnabled ( const SystemCall * sc ) const

protected

Returns true if sc is set and supposed to the printed.

Definition at line 677 of file TermTracer.cxx.

                                                     {
        if (!sc)
                return false;
        else if (m_syscall_filter.empty())
                return true;
 
        return m_syscall_filter.count(sc->callNr()) != 0;
}

◆ isExecSyscall()

bool clues::TermTracer::isExecSyscall ( const SystemCall & sc ) const

protected

Definition at line 651 of file TermTracer.cxx.

                                                         {
        switch (sc.callNr()) {
                default: return false;
                case SystemCallNr::EXECVE:
                case SystemCallNr::EXECVEAT:
                         return true;
        }
}

◆ main()

cosmos::ExitStatus clues::TermTracer::main	(	const int	argc,
		const char **	argv )

overrideprotected

Definition at line 807 of file TermTracer.cxx.

                                                                   {
        constexpr auto FAILURE = cosmos::ExitStatus::FAILURE;
        m_args.cmdline.parse(argc, argv);
 
        configureLogger();
 
        if (!processPars()) {
                return FAILURE;
        }
 
        cosmos::signal::block(cosmos::SigSet{cosmos::signal::CHILD});
 
        if (m_args.attach_proc.isSet()) {
                if (!configureTracee(cosmos::ProcessID{m_args.attach_proc.getValue()})) {
                        return FAILURE;
                }
        } else {
                // extract any additional arguments into a StringVector
                cosmos::StringVector sv;
                bool found_sep = false;
 
                for (auto arg = 1; arg < argc; arg++) {
                        if (found_sep) {
                                sv.push_back(argv[arg]);
                        } else if (std::string{argv[arg]} == "--") {
                                found_sep = true;
                        }
                }
 
                if (sv.empty()) {
                        std::cerr << "Neither -p nor command to execute after '--' was given. Nothing to do.\n";
                        return FAILURE;
                }
 
                try {
                        auto tracee = m_engine.addTracee(sv,
                                        FollowChildren{m_follow_children == FollowChildMode::NO ? false : true});
                        m_main_tracee_pid = tracee->pid();
                } catch (const cosmos::CosmosError &ex) {
                        std::cerr << ex.shortWhat() << "\n";
                        return FAILURE;
                }
        }
 
        try {
                m_engine.trace();
        } catch (const std::exception &ex) {
                std::cerr << "internal tracing error: " << ex.what() << std::endl;
                // try to do a hard exit to avoid blocking in the Engine's
                // destructor, should the state be messed up
                cosmos::proc::exit(FAILURE);
        }
 
        auto status = cosmos::ExitStatus::SUCCESS;
 
        /*
         * Evaluate exit code of the tracee, valid only after detach().
         *
         * We mimic the behaviour of the tracee by returning the same exit
         * status.
         */
        if (m_main_status) {
                if (m_main_status->exited()) {
                        status = *m_main_status->status();
                } else if (m_main_status->signaled()) {
                        // this is what the shell returns for children that have been killed.
                        // TODO: strace actually sends the same kill signal to iself
                        // I don't know whether this is very useful. It can
                        // cause core dumps of the tracer, thus we'd need to
                        // change ulimit to prevent that.
                        status = cosmos::ExitStatus{128 + cosmos::to_integral(m_main_status->termSig()->raw())};
                }
        }
 
        return status;
}

◆ newChildProcess()

void clues::TermTracer::newChildProcess	(	Tracee &	parent,
		Tracee &	child,
		const cosmos::ptrace::Event	event,
		const StatusFlags	flags )

overrideprotectedvirtual

A new child process has been created.

The existing tracee parent has created a new child process, which has automatically been attached to and is now represented in child.

Different ways to create a child process exist, these are differentiated via event. Note that some forms of clone() calls will appear as cosmos::ptrace::Event::FORK or cosmos::ptrace::Event::VFORK instead of cosmos::ptrace::Event::CLONE (when the clone() exit signal is set to SIGCHILD).

cosmos::ptrace::Event::VFORK_DONE occurs when the child process exited or exec()'d and can be ignored if there is no need for it.

StatusFlag::CLONED_THREAD will be set in flags in case the new child process is a thread of parent.

Reimplemented from clues::EventConsumer.

Definition at line 564 of file TermTracer.cxx.

                                                                        {
        auto follow = m_follow_children;
 
        if (follow == FollowChildMode::ASK) {
                traceStream(parent) << "Follow into new child process created by PID " << parent.pid() << " via " << to_label(event) << "?\n";
                std::cout << "PID " << parent.pid() << " is " << formatTraceeInvocation(parent) << "\n";
                follow = ask_yes_no() ? FollowChildMode::YES : FollowChildMode::NO;
        } else if (follow == FollowChildMode::THREADS) {
                follow = flags[StatusFlag::CLONED_THREAD] ? FollowChildMode::YES : FollowChildMode::NO;
        }
 
        if (follow == FollowChildMode::YES) {
                // keep this information for later when something actually happens in the new child
                m_new_tracees.insert({child.pid(), {parent.pid(), event}});
        } else {
                child.detach();
        }
}

◆ newExecutionContext()

void clues::TermTracer::newExecutionContext	(	Tracee &	tracee,
		const std::string &	old_executable,
		const cosmos::StringVector &	old_cmdline,
		const std::optional< cosmos::ProcessID >	old_pid )

overrideprotectedvirtual

A new program is executed in the tracee.

This call occurs after a successful execve() by the tracee.

The new executable path and command line can be retrieved via Tracee::executable() and Tracee::cmdLine(). The previous values are provided as input parameters.

The callee can decide to stop tracing (by detaching) at this point to prevent following the new tracing context.

If the tracee's process was multi-threaded then there is more complexity involved:

all but one thread will have exited at this point. Only the main process ID (main thread PID) will remain.
The thread that caused the execve() can be a different thread. In this case the different thread will receive a new PID personality (it will receive the main thread PID).
In case of a personality change, former_pid contains the former PID that the exec'ing thread had, which is now continuing as the main thread of the new execution context.
the current implementation of libclues will attempt to reuse the main thread's Tracee object even if a personality change happened. If the main thread was not traced at all then the exec()'ing thread's Tracee object will be reused. Due to this it is best to rely on the PIDs only (not Tracee pointers) to identify the new/old context.

Reimplemented from clues::EventConsumer.

Definition at line 521 of file TermTracer.cxx.

                                                            {
        if (old_pid) {
                // this needs to be done first to avoid any inconsistent state down below.
                updateTracee(tracee, *old_pid);
        }
 
        // cache this state here, because checkResumedSyscall() might alter the info
        const auto is_enabled = isEnabled(currentSyscall(tracee));
 
        if (is_enabled) {
                checkResumedSyscall(tracee);
                /* anticipate the success system call status to avoid
                 * complexities while outputting status messages and
                 * interactive dialogs. */
                traceStream(tracee, false) << ") = 0 (success)\n";
        }
 
        m_active_syscall = {};
 
        if (old_pid) {
                traceStream(tracee) << "--- PID " << *old_pid << " is now known as PID " << tracee.pid() << " ---\n";
        }
 
        // skip the output for the initial exec of a new child process,
        // because there's no interesting information in that
        if (seenInitialExec()) {
                traceStream(tracee) << "--- no longer running " << formatTraceeInvocation(old_exe, old_cmdline) << " ---\n";
        }
        traceStream(tracee) << "--- now running " << formatTraceeInvocation(tracee) << " ---\n";
 
        if (!seenInitialExec()) {
                m_flags.set(Flag::SEEN_INITIAL_EXEC);
        } else {
                if (!followExecutionContext(tracee)) {
                        traceStream(tracee) << "--- detaching after execve ---\n";
                        tracee.detach();
                }
        }
}

◆ printABIs()

void clues::TermTracer::printABIs ( )

protected

Definition at line 244 of file TermTracer.cxx.

                           {
        for (const auto abi: clues::get_supported_abis()) {
                std::cout << clues::get_abi_label(abi) << "\n";
        }
}

◆ printABISyscalls()

void clues::TermTracer::printABISyscalls ( const std::string & abi )

protected

Definition at line 200 of file TermTracer.cxx.

                                                          {
        auto print_syscalls = [](auto sysnr) {
                using ABISystemCallNr = decltype(sysnr);
                for (sysnr = ABISystemCallNr::_FIRST;
                                sysnr != ABISystemCallNr::_LAST;
                                sysnr = ABISystemCallNr{cosmos::to_integral(sysnr)+1}) {
                        /*
                         * convert to the generic system call number, this way
                         * we can get the system call name
                         */
                        auto gen_sysnr = clues::to_generic(sysnr);
                        if (gen_sysnr == clues::SystemCallNr::UNKNOWN)
                                // unassigned
                                continue;
 
                        auto name = clues::SYSTEM_CALL_NAMES[cosmos::to_integral(gen_sysnr)];
 
                        std::cout << name << " (";
                        if constexpr (std::is_same<ABISystemCallNr, SystemCallNrX32>::value) {
                                std::cout << "X32_SYSCALL_BIT + " << (cosmos::to_integral(sysnr) & (~clues::X32_SYSCALL_BIT));
                        } else {
                                std::cout << cosmos::to_integral(sysnr);
                        }
                        std::cout << ")\n";
                }
        };
 
        clues::AnySystemCallNr sys_nr;
 
        if (abi_str == "i386") {
                sys_nr = SystemCallNrI386{};
        } else if (abi_str == "x86-64") {
                sys_nr = SystemCallNrX64{};
        } else if (abi_str == "x32") {
                sys_nr = SystemCallNrX32{};
        } else if (abi_str == "aarch64") {
                sys_nr = SystemCallNrAARCH64{};
        } else {
                throw cosmos::RuntimeError{"unexpected abi string encountered"};
        }
 
        std::visit(print_syscalls, sys_nr);
}

◆ printPar()

void clues::TermTracer::printPar	(	std::ostream &	trace,
		const SystemCallItem &	value ) const

protected

Definition at line 352 of file TermTracer.cxx.

                                                                            {
        trace << (m_args.verbose.isSet() ? par.longName() : par.shortName());
 
        if (m_print_pars) {
                auto value = par.str();
 
                if (value.size() > m_par_truncation_len) {
                        value.resize(m_par_truncation_len);
                        value += "...";
                }
 
                trace << "=" << value;
        }
}

◆ printParsOnEntry()

void clues::TermTracer::printParsOnEntry	(	std::ostream &	trace,
		const SystemCall::ParameterVector &	pars ) const

protected

Definition at line 257 of file TermTracer.cxx.

                                                                                                {
        /*
         * This logic covers printing of parameters during system-call entry.
         *
         * During entry we can print all input-only parameters and stop once
         * we see a non-input parameter or once we are finished with all
         * parameters.
         *
         * During exit we continue printing from the first non-input parameter
         * onwards. This way we can present at least some of the system call
         * data already for blocking system calls.
         *
         * There exist system calls where the order of parameters is like
         * this:
         *
         * <input>, <output>, <input>
         *
         * In this case, while the final parameter would still be printable,
         * we will stop at the third parameter which is an output parameter.
         * `strace` does this similarly. In theory we could print a '?' in
         * this case for the not yet available output data, then do a
         * carriage-return during syscall-exit to print the end result.
         */
 
        if (pars.empty())
                return;
 
        const auto &last = pars.back();
 
        for (const auto &par: pars) {
                if (clues::item::is_unused_par(*par)) {
                        continue;
                } else if (!par->isIn()) {
                        // non-input parameter encountered, stop output
                        break;
                }
 
                printPar(trace, *par);
 
                if (const auto is_last = &par == &last; !is_last) {
                        trace << ", ";
                }
        }
}

◆ printParsOnExit()

void clues::TermTracer::printParsOnExit	(	std::ostream &	trace,
		const SystemCall::ParameterVector &	pars ) const

protected

Definition at line 302 of file TermTracer.cxx.

                                                                                               {
        if (pars.empty())
                return;
 
        const auto &last = pars.back();
        bool seen_non_input = false;
 
        for (const auto &par: pars) {
                if (clues::item::is_unused_par(*par)) {
                        continue;
                } else if (!seen_non_input) {
                        if (par->isIn()) {
                                // this was already printed during entry
                                continue;
                        } else {
                                seen_non_input = true;
                        }
                }
 
                printPar(trace, *par);
 
                if (const auto is_last = &par == &last; !is_last) {
                        trace << ", ";
                }
        }
}

◆ printSyscalls()

void clues::TermTracer::printSyscalls ( )

protected

Definition at line 190 of file TermTracer.cxx.

                               {
        // start at index one to skip the "UKNOWN" system call
        for (size_t nr = 1; nr < SYSTEM_CALL_NAMES.size(); nr++) {
                auto NAME = SYSTEM_CALL_NAMES[nr];
                if (!NAME[0])
                        continue;
                std::cout << NAME << "\n";
        }
}

◆ processPars()

bool clues::TermTracer::processPars ( )

protected

Definition at line 69 of file TermTracer.cxx.

                             {
 
        auto handle_bad_arg = [](auto &arg) {
                std::cerr << "bad argument to --" << arg.getName() << ": '" << arg.getValue() << "'\n";
                return false;
        };
 
        if (m_args.list_syscalls.isSet()) {
                printSyscalls();
                throw cosmos::ExitStatus::SUCCESS;
        } else if (m_args.list_abis.isSet()) {
                printABIs();
                throw cosmos::ExitStatus::SUCCESS;
        } else if (m_args.list_abi_syscalls.isSet()) {
                printABISyscalls(m_args.list_abi_syscalls.getValue());
                throw cosmos::ExitStatus::SUCCESS;
        }
 
        if (const auto max_len = m_args.max_value_len.getValue(); max_len == 0)
                m_print_pars = false;
        else if (max_len < 0)
                m_par_truncation_len = SIZE_MAX;
        else
                m_par_truncation_len = static_cast<size_t>(max_len);
 
        if (m_args.follow_execve.isSet()) {
                const auto &follow = m_args.follow_execve.getValue();
                constexpr std::string_view PATH_PREFIX{"path:"};
                constexpr std::string_view GLOB_PREFIX{"glob:"};
 
                if (follow == "yes") {
                        m_follow_exec = FollowExecContext::YES;
                } else if (follow == "no") {
                        m_follow_exec = FollowExecContext::NO;
                } else if (follow == "ask") {
                        m_follow_exec = FollowExecContext::ASK;
                } else if (cosmos::is_prefix(follow, PATH_PREFIX)) {
                        m_follow_exec = FollowExecContext::CHECK_PATH;
                        m_exec_context_arg = follow.substr(PATH_PREFIX.size());
                } else if (cosmos::is_prefix(follow, GLOB_PREFIX)) {
                        m_follow_exec = FollowExecContext::CHECK_GLOB;
                        m_exec_context_arg = follow.substr(GLOB_PREFIX.size());
                } else {
                        return handle_bad_arg(m_args.follow_execve);
                }
        }
 
        if (m_args.follow_children.isSet() && m_args.follow_children_switch.isSet()) {
                std::cerr << "cannot set both '-f' and '--follow-children'\n";
                return false;
        } else if (m_args.follow_children_switch.isSet()) {
                m_follow_children = FollowChildMode::YES;
        } else if (m_args.follow_children.isSet()) {
                const auto &follow = m_args.follow_children.getValue();
 
                if (follow == "yes") {
                        m_follow_children = FollowChildMode::YES;
                } else if (follow == "no") {
                        m_follow_children = FollowChildMode::NO;
                } else if (follow == "ask") {
                        m_follow_children = FollowChildMode::ASK;
                } else if (follow == "threads") {
                        m_follow_children = FollowChildMode::THREADS;
                } else {
                        return handle_bad_arg(m_args.follow_children);
                }
        }
 
        if (m_args.follow_threads.isSet()) {
                if (m_follow_children != FollowChildMode::NO) {
                        std::cerr << "cannot combine '--threads' with '-f' or '--follow-children'\n";
                        return false;
                }
 
                m_follow_children = FollowChildMode::THREADS;
        }
 
        if (m_args.syscall_filter.isSet()) {
                auto parts = cosmos::split(m_args.syscall_filter.getValue(), ",");
 
                auto translate_name = [](const std::string_view name) {
                        if (auto nr = lookup_system_call(name); nr) {
                                return *nr;
                        }
 
                        std::cerr << "invalid system call name: "
                                << name << "\n";
                        throw cosmos::ExitStatus::FAILURE;
                };
 
                std::vector<SystemCallNr> to_add;
                std::vector<SystemCallNr> to_remove;
 
                for (auto &part: parts) {
                        if (part.starts_with("!")) {
                                part = part.substr(1);
                                to_remove.push_back(translate_name(part));
                        } else {
                                to_add.push_back(translate_name(part));
                        }
                }
 
                for (const auto nr: to_add) {
                        m_syscall_filter.insert(nr);
                }
 
                // NOTE: this removal logic can make sense in the future when
                // we support system call groups (→ add a group, remove a few
                // again)
                for (const auto nr: to_remove) {
                        m_syscall_filter.erase(nr);
                }
        }
 
        if (m_args.print_fd_info.isSet()) {
                m_engine.setFormatFlags(Engine::FormatFlag::FD_INFO);
        }
 
        return true;
}

◆ seenInitialExec()

bool clues::TermTracer::seenInitialExec ( ) const

inlineprotected

Definition at line 179 of file TermTracer.hxx.

                                     {
                return m_flags[Flag::SEEN_INITIAL_EXEC];
        }

◆ signaled()

void clues::TermTracer::signaled	(	Tracee &	tracee,
		const cosmos::SigInfo &	info )

overrideprotectedvirtual

The tracee has received a signal.

This callback notifies about signals being delivered to the tracee.

Reimplemented from clues::EventConsumer.

Definition at line 443 of file TermTracer.cxx.

                                                                   {
        traceStream(tracee) << "-- " << clues::format::sig_info(info) << " --\n";
}

◆ startNewLine()

void clues::TermTracer::startNewLine	(	std::ostream &	trace,
		const Tracee &	tracee )

protected

Start a new output line concerning `tracee.

This prints out any preamble that might be necessary for starting a new trace output line, like [<pid>], when multiple tracees are present.

It also cares about managing the system call state to make sure unfinished system calls are kept track of.

Definition at line 613 of file TermTracer.cxx.

                                                                     {
        // make sure to terminate a possibly pending system call line
        if (storeUnfinishedSyscallCtx()) {
                // a system call in another thread remains unfinished
                trace << " <...unfinished>\n";
        }
 
        if (m_num_tracees > 1) {
                trace << "[" << tracee.pid() << "] ";
        } else if (m_flags.steal(Flag::DROPPED_TO_LAST_TRACEE)) {
                trace << "--- only PID " << tracee.pid() << " is remaining ---\n";
        }
}

◆ stopped()

void clues::TermTracer::stopped ( Tracee & tracee )

overrideprotectedvirtual

The tracee entered group-stop due to a stopping signal.

Reimplemented from clues::EventConsumer.

Definition at line 491 of file TermTracer.cxx.

                                       {
        if (tracee.syscallCtr() == 0) {
                traceStream(tracee) << "--- currently in stopped state due to " << *tracee.stopSignal() << " ---\n";
        }
}

◆ storeUnfinishedSyscallCtx()

bool clues::TermTracer::storeUnfinishedSyscallCtx ( )

protected

Store an active system call in m_unfinished_syscalls.

If there's an active system call then store if in m_unfinished_syscalls and reset it.

The return value indicates whether a traced system call has been interrupted by this operation. Interrupted but filtered-out system calls are not counted here.

Definition at line 627 of file TermTracer.cxx.

                                           {
        if (!m_active_syscall) {
                return false;
        }
 
        auto [pid, syscall] = *m_active_syscall;
        const bool ret = isEnabled(syscall);
 
        m_unfinished_syscalls[pid] = syscall;
        m_active_syscall.reset();
        return ret;
}

◆ syscallEntry()

void clues::TermTracer::syscallEntry	(	Tracee &	tracee,
		const SystemCall &	sc,
		const StatusFlags	flags )

overrideprotectedvirtual

A system call is about to be executed in the Tracee.

At this stage only the type of system call as well system call parameters of ItemType::PARAM_IN or ItemType::PARAM_IN_OUT have useful values. Any out parameters and the return value should not be inspected.

Reimplemented from clues::EventConsumer.

Definition at line 367 of file TermTracer.cxx.

                                         {
 
        if (!isEnabled(&sc)) {
                return;
        }
 
        // this needs to be assigned before returning from this function but
        // after traceStream() is called, if at all.
        auto defer_assign_syscall = cosmos::defer([this, &tracee, &sc]() {
                m_active_syscall = std::make_optional(
                                std::make_tuple(tracee.pid(), &sc));
        });
 
        const auto syscall_info = *tracee.currentSystemCallInfo();
        checkABI(tracee, syscall_info);
        /* libclues also offers an ABI_CHANGED flag in `cflags`, but this
         * doesn't suffice for us, since we might filter system calls, which
         * means we don't necessarily need to report every ABI change.
         */
        m_last_abi = syscall_info.abi();
 
        auto &trace = traceStream(tracee);
 
        if (flags[StatusFlag::RESUMED]) {
                trace << "<resuming previously interrupted " << sc.name() << "...>\n";
        }
        trace << sc.name() << "(";
 
        printParsOnEntry(trace, sc.parameters());
 
        trace << std::flush;
}

◆ syscallExit()

void clues::TermTracer::syscallExit	(	Tracee &	tracee,
		const SystemCall &	sc,
		const StatusFlags	flags )

overrideprotectedvirtual

A system call has been finished.

If the system call failed then sc.hasErrorCode() returns true and the ErrnoResult can be inspected from sc.error().

If the system call succeeded sc.hasResultValue() returns true and any system call parameters of ItemType::PARAM_OUT or ItemType::PARAM_IN_OUT should have been updated by the kernel and can be updated and processed by the implementation.

If flags[StatusFlag::INTERRUPTED] is set, then the system call was interrupted by a signal and aborted by the kernel. Whether this happens depends on various factors, e.g. if the SA_RESTART flag is set in the Tracee for the signal which was received and also on the type of system call which is executed. If automatic system call restarting is not active then a regular EINTR error return will be observed and the Tracee has to actively deal with the situation.

libclues tries to keep track of when an automatically restarted system call will be resumed and will set flags[StatusFlag::RESUMED] during syscallEntry() accordingly. There are two different scenarios to take into account here:

restart_syscall() is injected by the kernel. This is the case when the signal was SIGSTOP and the system call was time-related, like clock_nanosleep(), to give userspace (libc) the chance to adjust times before resuming the system call.

libclues looks up the original system call and will not report SystemCallNr::RESTART_SYSCALL, but the resumed system call and will set StatusFlag::RESUMED accordingly.
the system call is transparently restarted by the kernel. In this case the system call entry is not easily distinguishable from a completely new system call. The Tracee might have executed additional system calls in-between when an asynchronous signal handler was executed. libclues is looking for the rt_sigreturn() system call to appear to make out the end of the interruption and then looks for the next system call of the same type as the interrupted system call. When this situation is detected then StatusFlag::RESUMED is set as well.

This needs to be reset before returning from this function but after checkResumedSyscall() is called, if at all.

Reimplemented from clues::EventConsumer.

Definition at line 402 of file TermTracer.cxx.

                                         {
 
        if (isExecSyscall(sc) && sc.result()) {
                // this was already dealt with in newExecutionContext()
                return;
        } else if (!isEnabled(&sc)) {
                return;
        }
        auto defer_reset_syscall = cosmos::defer([this]() {
                m_active_syscall.reset();
        });
 
 
        checkResumedSyscall(tracee);
 
        // we are preempting another Tracee's system call (one Tracee already entered, this Tracee exits
        const bool need_newline = m_active_syscall && !hasActiveSyscall(tracee);
 
        auto &trace = traceStream(tracee, need_newline);
        printParsOnExit(trace, sc.parameters());
 
        trace << ") = ";
 
        if (auto res = sc.result(); res) {
                trace << res->str() << " (" << (m_args.verbose.isSet() ? res->longName() : res->shortName()) << ")";
        } else {
                const auto err = *sc.error();
                trace << err.str() << " (errno)";
        }
 
        if (flags[StatusFlag::INTERRUPTED]) {
                trace << " (interrupted)";
        }
 
        trace << std::endl;
}

◆ traceStream()

std::ostream & clues::TermTracer::traceStream	(	const Tracee &	tracee,
		const bool	new_line = true )

protected

Returns the currently active trace output stream, starting a new output line.

Definition at line 601 of file TermTracer.cxx.

                                                                             {
        // TODO: this is currently fixed to cerr, but we should implement
        // trace to file, maybe also separate files for each PID, or even
        // separate PTYs in some form.
        auto &stream = std::cerr;
 
        if (new_line) {
                startNewLine(stream, tracee);
        }
        return std::cerr;
}

◆ updateTracee()

void clues::TermTracer::updateTracee	(	const Tracee &	tracee,
		const cosmos::ProcessID	old_pid )

protected

Update internal data structures in case a tracee changed PID.

Definition at line 723 of file TermTracer.cxx.

                                                                                 {
        if (hasActiveSyscall(old_pid)) {
                m_active_syscall = std::make_tuple(tracee.pid(), activeSyscall());
        } else if (auto it = m_unfinished_syscalls.find(old_pid); it != m_unfinished_syscalls.end()) {
                m_unfinished_syscalls[tracee.pid()] = it->second;
                m_unfinished_syscalls.erase(it);
        }
 
        // if there should be an entry for the new PID already, then it's from
        // an already dead sibbling tracee. get rid of that.
        m_new_tracees.erase(tracee.pid());
 
        if (auto it = m_new_tracees.find(old_pid); it != m_new_tracees.end()) {
                m_new_tracees[tracee.pid()] = it->second;
                m_new_tracees.erase(it);
        }
}

Member Data Documentation

◆ m_active_syscall

std::optional<std::tuple<cosmos::ProcessID, const SystemCall*> > clues::TermTracer::m_active_syscall

protected

The currently active system call, if any.

This is only keeping track of system calls that are actually printed to stdout. Ignored system calls are not kept track of here. The Tracee objects keep track of any active system calls already.

Definition at line 261 of file TermTracer.hxx.

◆ m_args

Args clues::TermTracer::m_args

protected

Command line arguments and parser.

Definition at line 224 of file TermTracer.hxx.

◆ m_cosmos

cosmos::Init clues::TermTracer::m_cosmos

protected

Definition at line 228 of file TermTracer.hxx.

◆ m_engine

Engine clues::TermTracer::m_engine

protected

libclues main object.

Definition at line 231 of file TermTracer.hxx.

◆ m_exec_context_arg

std::string clues::TermTracer::m_exec_context_arg

protected

optional argument to m_follow_exec (e.g. path, glob, script)

Definition at line 238 of file TermTracer.hxx.

◆ m_flags

Flags clues::TermTracer::m_flags

protected

State flags with global context or carried between different callbacks.

Definition at line 249 of file TermTracer.hxx.

◆ m_follow_children

FollowChildMode clues::TermTracer::m_follow_children = FollowChildMode::NO

protected

Behaviour upon newChildProcess()

Definition at line 244 of file TermTracer.hxx.

◆ m_follow_exec

FollowExecContext clues::TermTracer::m_follow_exec = FollowExecContext::YES

protected

Behaviour upon newExecutionContext()

Definition at line 242 of file TermTracer.hxx.

◆ m_last_abi

clues::ABI clues::TermTracer::m_last_abi = clues::ABI::UNKNOWN

protected

The ABI of the last system call we've seen.

Definition at line 276 of file TermTracer.hxx.

◆ m_logger

cosmos::StdLogger clues::TermTracer::m_logger

protected

cosmos ILogger instance for clues library logging.

Definition at line 227 of file TermTracer.hxx.

◆ m_main_status

std::optional<cosmos::WaitStatus> clues::TermTracer::m_main_status

protected

The WaitStatus of the main process we've seen upon it exiting.

Definition at line 253 of file TermTracer.hxx.

◆ m_main_tracee_pid

cosmos::ProcessID clues::TermTracer::m_main_tracee_pid

protected

The PID of the main process we're tracing (the one we created or attached to).

Definition at line 251 of file TermTracer.hxx.

◆ m_new_tracees

std::map<cosmos::ProcessID, std::pair<cosmos::ProcessID, cosmos::ptrace::Event> > clues::TermTracer::m_new_tracees

protected

Newly created tracees that haven't seen any ptrace stop yet.

The values contain the PID that created the tracee and the type of event that led to the creation.

Definition at line 274 of file TermTracer.hxx.

◆ m_num_tracees

size_t clues::TermTracer::m_num_tracees = 0

protected

The number of tracees we're currently dealing with.

Definition at line 247 of file TermTracer.hxx.

◆ m_par_truncation_len

size_t clues::TermTracer::m_par_truncation_len = 64

protected

Maximum length of of system call parameter values to print before truncating the output.

Definition at line 236 of file TermTracer.hxx.

◆ m_print_pars

bool clues::TermTracer::m_print_pars = true

protected

Whether to print system call parameters at all (-s 0 disables it).

Definition at line 234 of file TermTracer.hxx.

◆ m_syscall_filter

std::set<SystemCallNr> clues::TermTracer::m_syscall_filter

protected

Whitelist of system calls to trace, if any.

Definition at line 240 of file TermTracer.hxx.

◆ m_unfinished_syscalls

std::map<cosmos::ProcessID, const SystemCall*> clues::TermTracer::m_unfinished_syscalls

protected

Unfinished / preempted system calls.

Unfinished in this context is purely tracing related, it only means that we already started printing system call entry for one tracee, while another event came in, preempting this line.

Definition at line 268 of file TermTracer.hxx.

The documentation for this class was generated from the following files:

src/termtracer/TermTracer.hxx
src/termtracer/TermTracer.cxx

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ Flags

Member Enumeration Documentation

◆ Flag

◆ FollowChildMode

◆ FollowExecContext

Constructor & Destructor Documentation

◆ TermTracer()

Member Function Documentation

◆ abortSyscall()

◆ activeSyscall() [1/3]

◆ activeSyscall() [2/3]

◆ activeSyscall() [3/3]

◆ attached()

◆ checkABI()

◆ checkResumedSyscall()

◆ cleanupTracee()

◆ configureLogger()

◆ configureTracee()

◆ currentSyscall()

◆ disappeared()

◆ exited()

◆ findSyscall()

◆ followExecutionContext()

◆ formatTraceeInvocation() [1/2]

◆ formatTraceeInvocation() [2/2]

◆ hasActiveSyscall() [1/2]

◆ hasActiveSyscall() [2/2]

◆ isEnabled()

◆ isExecSyscall()

◆ main()

◆ newChildProcess()

◆ newExecutionContext()

◆ printABIs()

◆ printABISyscalls()

◆ printPar()

◆ printParsOnEntry()

◆ printParsOnExit()

◆ printSyscalls()

◆ processPars()

◆ seenInitialExec()

◆ signaled()

◆ startNewLine()

◆ stopped()

◆ storeUnfinishedSyscallCtx()

◆ syscallEntry()

◆ syscallExit()

◆ traceStream()

◆ updateTracee()

Member Data Documentation

◆ m_active_syscall

◆ m_args

◆ m_cosmos

◆ m_engine

◆ m_exec_context_arg

◆ m_flags

◆ m_follow_children

◆ m_follow_exec

◆ m_last_abi

◆ m_logger

◆ m_main_status

◆ m_main_tracee_pid

◆ m_new_tracees

◆ m_num_tracees

◆ m_par_truncation_len

◆ m_print_pars

◆ m_syscall_filter

◆ m_unfinished_syscalls