README file for getEmu utility. Release 0.0.01
Copyright 2026-2027 by The Software Samurai
Software released under GPL3+, and documentation released under FDL1.3+
=======================================================================

OVERVIEW
========

The getEmu ('getemu') utility is a GNU/Linux console application 
which scans the system's process tree and reports the name of the terminal 
emulator program from which the application was launched.
The scan is performed by moving sequentially upward through the process tree.
This tree consists of a group of files in the system "/proc" directory 
associated with each active process in the system.

Each sequential target file is identified by the process ID for the parent 
processs. Traverse the parent PID records until the terminal emulator name 
is found, or until the top of the process tree is reached.

Example:         Process        procID   DataFile
            ------------------  ------  ----------
            getEmu application: 4475    /proc/4475/stat
            shell program     : 3872    /proc/3872/stat
            terminal emulator : 3821    /proc/3821/stat
            init process      :    1    /proc/1/stat

While this is a tedious "process" (pardon the pun), it is the most reliable 
way we have found so far.

The return value from the getEmulator() function is a string which contains 
either two or three substrings, separated by a colons (" :").
            Example: "gnome-terminal :4495"
                     |               |.... process ID
                     |.............. emulator name

            Example: "gnome-terminal :4495 :3.56.3
                     |               |     |...... process ID
                     |               |.... process ID
                     |.............. emulator name

Each 'stat' file is a plain text file which contains a large amount of encoded 
data. The first four tokens of the first line of the file are decoded by the 
application.
third (2nd) and fourth (4th) tokens that are of interest:
token #1: This is the process ID for the current file.
          (We already have this value so the token is ignored.)
token #2: This is the name of the the process (enclosed in parentheses).
          Note that this may be some variation of the actual name; however, 
          it is the canonical application name that is returned.
token #3: This is the letter 'S'. and we currently don't care what it means.
token #4: This is the parent process's procID.
          This value is used for the next step up through the process tree.

If the name of the terminal emulator application is successfully captured, 
then the version number of the emuator program is added to the return value.

Note that some of the Linux terminal programs may not be identified 
successfully; however, the following will (nearly always) be identified 
correctly. The application has been tested against live data only for the 
first three items of the list.
            1) "gnome-terminal"
            2) "konsole"
            3) "xterm"
            4) "guake"
            5) "tilda"
            6) "terminator"
            7) "yakuake"

---  ---   ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---  ---
This application was designed under Fedora Linux and is built using the 
GNU C compiler, version 15.2.1 or higher (C++17 support required).
If you are not using GCC, then verify that your compiler fully supports 
the C++17 standard.


Download and unpack the distribution archive:
=============================================

Navigate to the base directory where package will be installed (example):
   cd ~/SoftwareDesign
Move the archive file to the base directory:
   mv ~/Dowloads/getemu-0.0.01.tar.bz2 .
Unpack the tar archive:
   tar -xjvf getemu-0.0.01.tar.bz2
Navigate to the target directory:
   cd getEmu

After unpacking the archive, the directories will look something like this:

.../SoftwareDesign/getEmu/
      getEmu.cpp    <== Application definition and implementation
      gString.hpp   <== gString class definition (text analysis and formatting)
      gString.cpp   <== gString class implementation 
      Makefile      <== Build the 'getemu' application
      README        <== Package description, release notes (this file)

Building the application:
=========================

To build the application, type:
   gmake
The application should build without errors and without warnings.

To remove any stale object files and executable, type:
   gmake clean

To test the build, type:
   ./getemu --version

For invocation options, type:
   ./getemu --help

Notes on the current release:
=============================

This is the first public release; however, it is an extremely simple 
application, so it is hoped that the application will build and perform as 
documented. If you encounter a problem, please sent the author a note via website.
- - - - -
Please see the header of "getEmu.cpp" for a list of all changes since the 
previous release.

Known bugs and other issues:
============================
None identified at this time.

