Browser Shell: Cross-Platform Technical Documentation

1. Overview

Browser Shell is a lightweight, cross-platform desktop utility written in C that provides a unified graphical interface for controlling web browsers. It allows users to manage browser instances, manipulate URLs, handle bookmarks, and perform maintenance tasks (such as cache clearing) through a simple command-line-like input within a native GUI window.

The application features platform-specific implementations for Windows, Linux, and macOS, utilizing the native windowing and system APIs of each operating system to ensure optimal integration and performance.

---

2. Platform Support & Architecture

The codebase uses preprocessor directives to compile distinct implementations based on the target operating system:

Platform	Windowing System	Key Libraries	Entry Point
Windows	Win32 API	windows.h, shlobj.h	WinMain
Linux	X11 (Xlib)	X11/Xlib.h, X11/Xutil.h	main
macOS	Cocoa (Objective-C Runtime)	AppKit/AppKit.h, objc/runtime.h	main

2.1. Windows Implementation

• GUI: Uses standard Win32 controls (EDIT, BUTTON) created via CreateWindowW.
• Encoding: Handles UTF-8 to Wide Character conversion (utf8_to_wide, wide_to_utf8) to support international characters in commands and output.
• System Interaction: Uses system() calls to execute browser binaries and tasklist/taskkill for process management.
• Storage: Bookmarks are stored in %USERPROFILE%\browser_shell_bookmarks.txt.

2.2. Linux Implementation

• GUI: Uses raw X11 calls (XCreateSimpleWindow, XDrawString) to render a basic interface. Input is handled via KeyPress events.
• System Interaction: Uses system() with standard Linux commands (xdg-open, ps aux, pkill, rm).
• Storage: Bookmarks are stored in $HOME/.browser_shell_bookmarks.txt.

2.3. macOS Implementation

• GUI: Uses the Objective-C Runtime API (objc_msgSend) to dynamically create Cocoa objects (NSWindow, NSTextField, NSButton, NSTextView) without requiring separate .m files or Interface Builder.
• System Interaction: Uses system() with macOS-specific commands (open -a, ps aux, pkill).
• Storage: Bookmarks are stored in $HOME/.browser_shell_bookmarks.txt.

---

3. Installation and Compilation

Prerequisites

• Windows: MinGW-w64 or Microsoft Visual Studio (MSVC).
• Linux: GCC, X11 Development Libraries (libx11-dev).
• macOS: Clang, macOS SDK (included with Xcode Command Line Tools).

Build Instructions

Windows (MinGW)

gcc -o browser_shell.exe main.c -lgdi32 -lcomdlg32 -lole32

Linux

gcc -o browser_shell main.c -lX11 -lm

macOS

gcc -framework AppKit -framework CoreFoundation -o browser_shell main.c

---

4. Usage Guide

Upon launching the application, a window appears with an input field, an "Execute" button, and an output area. Type commands into the input field and press Enter or click "Execute".

4.1. Command Reference

Command	Syntax	Description
Help	help	Displays the list of available commands.
Open URL	open <url> [browser]	Opens the specified URL. Optional browser: chrome, firefox, edge (Win), safari (Mac). Defaults to system default if no browser specified.
Add Bookmark	bookmark add <url> <name>	Saves a URL with a given name to the local bookmark file.
List Bookmarks	bookmark list	Reads and displays all saved bookmarks from the local file.
Clear Cache	clearcache [browser]	Deletes the browser cache directory. Supports chrome, firefox, edge (Win), safari (Mac). Defaults to chrome (Win/Linux) or safari (Mac).
New Tab	newtab [browser]	Opens a new blank tab in the specified browser.
New Window	newwindow [browser]	Opens a new browser window.
List Processes	listbrowsers	Lists currently running browser processes (Chrome, Firefox, Edge/Safari).
Close Browser	close [browser]	Forcefully terminates the specified browser process.

4.2. Examples

Opening a URL in Chrome:

open https://www.example.com chrome

Adding a Bookmark:

bookmark add https://github.com GitHub

Clearing Firefox Cache (Linux/macOS):

clearcache firefox

Closing All Chrome Instances:

close chrome

---

5. Technical Implementation Details

5.1. Command Parsing

The core logic resides in the event handler for the "Execute" button (or Enter key). The input string is parsed using standard C string functions:

• strcmp / strncmp: Identifies the command verb.
• strchr / strrchr: Splits arguments (e.g., separating URL from browser name, or URL from bookmark name).
• system(): Executes shell commands constructed via snprintf.

5.2. Bookmark Management

Bookmarks are stored in a plain text file using a pipe-delimited format:

Name|URL

• Write: Opens the file in append mode ("a").
• Read: Opens the file in read mode ("r") and concatenates lines to the output buffer.

5.3. Process Management

• Listing: Uses popen (Linux/macOS) or _popen (Windows) to run ps aux or tasklist and captures the stdout.
• Killing: Uses pkill (Linux/macOS) or taskkill (Windows) to terminate processes by image name.

5.4. Cache Clearing

The application constructs paths to known cache directories based on the OS and user home directory:

• Windows: %LOCALAPPDATA%\Google\Chrome\User Data\Default\Cache
• Linux: $HOME/.cache/google-chrome
• macOS: $HOME/Library/Caches/Google/Chrome It then executes a recursive delete command (del /q /s on Windows, rm -rf on Unix-like systems).

---

6. Limitations and Security Considerations

1. Hardcoded Paths: Browser executable paths (especially on Windows) are hardcoded. If a user installs Chrome in a non-standard directory, the open, newtab, and newwindow commands may fail.
2. Security Risks:
   • Command Injection: The use of system() with user-supplied input (URLs, browser names) poses a potential command injection risk if input validation is not strict. Currently, the code assumes trusted input.
   • Cache Deletion: The clearcache command forcefully deletes cache directories. This may cause data loss if the browser is currently running and writing to these files.
3. Process Killing: The close command uses forceful termination (/F on Windows, pkill -f on Unix). This may result in unsaved data loss in the browser.
4. Linux GUI: The Linux implementation uses basic X11 drawing. It does not support modern input methods (IME) or complex text rendering, limiting it to ASCII/basic Latin characters.
5. macOS Runtime: The macOS version uses direct objc_msgSend calls. While functional, this approach is fragile and harder to maintain than standard Objective-C or Swift code. It lacks automatic reference counting (ARC), relying on manual pool draining.

---

7. Future Improvements

• Input Validation: Sanitize inputs before passing them to system() to prevent command injection.
• Configuration File: Allow users to define custom browser paths.
• Async Execution: Run long-running commands (like cache clearing) in background threads to prevent the GUI from freezing.
• Enhanced Linux GUI: Migrate to GTK or Qt for better input handling and visual appeal.
• Bookmark Editing: Add functionality to delete or edit existing bookmarks.

Built With

• c