View source for /var/inst documentation

== Overview ==
Each file under /var/inst is a product definition — an installed-package record created by the IRIX <code>inst</code> subsystem. These files are used by <code>inst</code>, <code>versions</code>, and internal <code>libinst.so</code> routines to reconstruct the system inventory.

They are plain, uncompressed data streams comprising NUL-terminated ASCII records, which describe subsystems, components, conditions, paths, and metadata.

== General Structure ==
{| class="wikitable"
!Element
!Type
!Notes
|-
|Header Record
|Fixed ASCII string
|Always begins with <code>pd001VxxxP00</code>. <code>Vxxx</code> encodes the inst database version (e.g. <code>V630</code> = IRIX 6.3, <code>V650</code> = IRIX 6.5).
|-
|Body Records
|Variable-length, NUL-terminated strings
|Contain subsystem, component, description, condition, path information.
|-
|Footer / Terminator
|EOF
|Files end at EOF; no explicit checksum or final sentinel required.
|}
Encoding: ASCII (7-bit) Delimiter: NUL (\0) Compression: None

== Common Record Types (Observed) ==
{| class="wikitable"
!Token / Prefix
!Likely Meaning
!Example
|-
|(no prefix)
|Product name or subsystem identifier
|<code>sgi_apache</code>, <code>x_eoe</code>
|}

* | Human-readable description | <code>+SGI Web Server based on Apache, 1.3.35</code> ) | Source directory or source-related tag | <code>)d/usr/people/.../dist</code> $, ', & | UI label or alternate descriptor | <code>$SGI Web Server Release Notes, 1.3.35</code> patch*, maint* | Patch / maintenance relationships | <code>patch*sgi_apache_sw</code> T/ | Target installation path | <code>T/var/sgi_apache/server/share/...</code> d | Build or distribution tag | <code>d10.0.0.206:love.6530.app</code> P_ | Timestamp pair (installation/build timestamps) | <code>P1147443119_1279655720</code> Conditionals | <code>!noship</code>, <code>!!noship</code>, <code>!noship && DEV</code>, <code>||</code> | Installation conditions / policy expressions Architecture markers | <code>LE</code>, <code>8wu</code>, <code>OT</code>, <code>NT</code>, etc. | Platform/build variant markers (exact semantics TBD)

== Logical Hierarchy ==
Although stored sequentially, the file encodes a logical tree:

PRODUCT ├─ SUBSYSTEM │ ├─ COMPONENT │ ├─ PATHS / DOCS │ ├─ PATCH / MAINT relationships │ └─ CONDITIONS └─ GLOBAL METADATA (timestamps, build tags)

== Parsing Heuristics ==

# Read the first token; it must match the header <code>pd001VxxxP00</code>.
# Iterate NUL-delimited ASCII strings in order:
#* Short lowercase tokens → subsystem/component names.
#* Tokens beginning with +, &, $, ' → descriptions/labels.
#* Tokens beginning with <code>patch*</code> / <code>maint*</code> → relationships.
#* Tokens beginning with <code>T/</code> or containing <code>/usr/</code>, <code>/var/</code>, <code>/lib/</code> → paths.
#* Tokens containing <code>love.</code> or <code>d<version></code> → build/installer annotations.
# Group contiguous tokens into one logical block until the next subsystem name is encountered.

== Header Versions (Observed) ==
{| class="wikitable"
!Header
!IRIX Family
|-
|pd001V530P00
|IRIX 5.3
|-
|pd001V630P00
|IRIX 6.3
|-
|pd001V650P00
|IRIX 6.5
|}

== Example (Simplified) ==
pd001V650P00 x_eoe &X11 Execution Environment, 6.5.30 d10.0.0.206:love.6530.app P123456789_987654321 books &X11 Documentation patch''x_eoe_books maint''x_eoe_books x_eoe_sw64 &X11 64-bit Executables

== Observations & Notes ==

* Files are mostly human-readable ASCII when examined as strings.
* Fields like descriptions may appear more than once (UI label vs. internal label).
* Repeated binary-looking sequences (e.g. control bytes) appear between string groups; these are likely structural delimiters or metadata bytes.
* The <code>love.*</code> token is used by community installers (miniroot/overlay markers); treat it as an opaque distribution label unless confirmed otherwise.

== Unknowns / Open Research ==

* Exact semantics for architecture/variant tokens like 8wu, LE, OT, NT.
* Full truth table for conditional expressions (!noship, !!noship, and boolean combos).
* Precise internal representation used by libinst.so — RE of libinst would confirm concrete struct layouts.
* Relationship and synchronization logic between /var/inst product files and any central index (e.g., /var/inst/installed if present).

== Recommended Next Steps ==

# Collect /var/inst files from IRIX 6.2–6.5 and diff identical products across versions.
# Cross-validate parsed results against <code>versions -v</code> and <code>inst</code> outputs on IRIX (when possible).
# RE <code>libinst.so</code> (symbols like <code>inst_read_*</code>) to confirm struct field types and ordering.
# Implement a minimal C parser (library) that:
#* Iterates NUL-delimited strings
#* Classifies tokens by the heuristics above
#* Builds an in-memory tree (PRODUCT → SUBSYSTEM → COMPONENT) for <code>versions</code>-like queries

== Goal ==
Produce a portable C library to:

* Read /var/inst product files,
* Reconstruct their logical hierarchy,
* Provide an API for <code>versions</code>-style checks and comparisons on non-IRIX hosts.

This document is a living draft. Contributions and empirical data (dumps, offsets, diffs) are encouraged to refine and finalize the format.