TeeJee.Process

1. Overview

The TeeJee.Process module provides process and shell execution utilities for BastionGuard Backup. It creates temporary script environments, executes commands synchronously or asynchronously, supports privileged and user-session execution, reads process metadata, sends signals, and changes process priority.

The implementation is written in Vala and uses GLib/GIO together with the application utility namespaces required by the file.

2. Dependencies and Integration

The module imports:

  • TeeJee.Logging
  • TeeJee.FileSystem
  • TeeJee.Misc

Key runtime integrations include:

  • GIO/GLib streams – filesystem and process I/O

3. Declared Types

3.1 TeeJee.ProcessHelper

namespace TeeJee.ProcessHelper

This namespace groups stateless utility functions and shared constants.

4. State, Properties, Constants, and Signals

Public and protected state

  • public string TEMP_DIR – Process-specific temporary working directory.

5. Public API and Operational Methods

5.1 init_tmp()

public static void init_tmp()

Initializes tmp and prepares it for use.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.2 exec_sync()

public int exec_sync (string cmd, out string? std_out = null, out string? std_err = null)

Implements the exec sync operation for this module.

  • Catches runtime errors locally and reports them through the logging layer or return value.

5.3 exec_script_sync()

public int exec_script_sync (string script, out string? std_out = null, out string? std_err = null, bool supress_errors = false, bool run_as_admin = false, bool cleanup_tmp = true, bool print_to_terminal = false)

Writes the supplied shell content to a temporary script, optionally executes it with elevated privileges, captures output, and cleans the temporary script.

  • Executes an external process or generated shell command and uses its return status as part of the result.
  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.4 exec_script_async()

public int exec_script_async (string script)

Implements the exec script async operation for this module.

  • Uses asynchronous callbacks, child watches, or worker-thread behavior.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.5 exec_user_async()

public static int exec_user_async(string command)

Implements the exec user async operation for this module.

  • Uses asynchronous callbacks, child watches, or worker-thread behavior.

5.6 save_bash_script_temp()

public string? save_bash_script_temp (string commands, string? script_path = null, bool force_locale = true, bool supress_errors = false)

Persists bash script temp using the module storage format.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.7 get_temp_file_path()

public string get_temp_file_path()

Returns or resolves temp file path from the current state or underlying system data.

5.8 cmd_exists()

public static bool cmd_exists(string cmd_tool)

Implements the cmd exists operation for this module.

5.9 get_process_exe_name()

public string get_process_exe_name(long pid = -1)

Returns or resolves process exe name from the current state or underlying system data.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.10 get_process_parent()

public Pid get_process_parent(Pid process = -1)

Returns or resolves process parent from the current state or underlying system data.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.11 get_euid_of_process()

public int get_euid_of_process(Pid process)

Returns or resolves euid of process from the current state or underlying system data.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.12 get_user_process()

public Pid get_user_process()

Returns or resolves user process from the current state or underlying system data.

5.13 get_process_env()

public string[]? get_process_env(Pid pid)

Returns or resolves process env from the current state or underlying system data.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.

5.14 get_env()

public string? get_env(string[] env, string name, string? default_value = null)

Returns or resolves env from the current state or underlying system data.

5.15 get_process_children()

public Pid[] get_process_children (Pid parent_pid)

Returns or resolves process children from the current state or underlying system data.

  • Performs filesystem access and handles files or directories through GLib or TeeJee helpers.
  • Catches runtime errors locally and reports them through the logging layer or return value.

5.16 process_quit()

public void process_quit(Pid process_pid, bool killChildren = true)

Implements the process quit operation for this module.

5.17 process_kill()

public void process_kill(Pid process_pid, bool killChildren = true)

Implements the process kill operation for this module.

5.18 process_send_signal()

public void process_send_signal(Pid process_pid, Posix.Signal sig, bool children = true)

Sends a POSIX signal to the target process and, when requested, recursively applies it to child processes.

5.19 process_set_priority()

public void process_set_priority (Pid procID, int prio)

Implements the process set priority operation for this module.

5.20 process_get_priority()

public int process_get_priority (Pid procID)

Implements the process get priority operation for this module.

5.21 process_set_priority_normal()

public void process_set_priority_normal (Pid procID)

Implements the process set priority normal operation for this module.

5.22 process_set_priority_low()

public void process_set_priority_low (Pid procID)

Implements the process set priority low operation for this module.

6. Filesystem Paths and Resource Locations

The source references the following absolute or template paths:

/.temp
/bastionguard-backup-
/dev/shm
/proc/
/proc/%d
/proc/%i/environ
/proc/%s/exe
/proc/%s/stat
/var/tmp

Some values are templates completed at runtime with application names, process IDs, device identifiers, or file names.

7. External Commands and System Interfaces

The module constructs, checks, or parses commands containing:

#!/usr/bin/env bash\n
pkexec --user %s env DISPLAY=$DISPLAY XAUTHORITY=$XAUTHORITY DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS 
pkexec env DISPLAY=$DISPLAY XAUTHORITY=$XAUTHORITY
script-admin.sh

Execution success is determined from command exit status and, where applicable, parsed standard output or standard error.

8. Operational Flow

  1. Initialize object state, widgets, regular expressions, paths, or generated scripts.
  2. Read or discover source data and normalize it into the module data model.
  3. Apply the requested operation and update runtime or persistent state.

9. Error Handling and Diagnostics

  • GLib and filesystem exceptions are caught locally in the operations that can fail.
  • The TeeJee logging layer records errors, debug state, generated commands, and operational messages.
  • Boolean, nullable, or empty-string return values communicate recoverable failures to callers.
  • Some methods return detailed diagnostics through output parameters in addition to their primary status value.

10. Runtime and Security Considerations

  • External commands: command availability, quoting, locale, privileges, and output format can affect behavior.
  • Dynamic command construction: caller-controlled values must be validated and escaped before being inserted into shell commands.
  • Linux-specific paths: the module depends on Linux virtual filesystems or privileged system directories.
  • Concurrency: callbacks and worker state must remain synchronized with object destruction and GTK main-loop ownership.
  • Shared state: static caches and global switches are shared by all callers and are not automatically thread-isolated.

11. Licensing

The source is distributed under the GNU General Public License version 2 or any later version.

The source header identifies:

Copyright 2012-2018 Tony George <teejeetech@gmail.com>

Published on:
Last updated on: