Native Linux C ABI

HotPDFLinuxABI.lpr builds a native x86_64 ELF shared library named libhotpdf.so.1, with SONAME libhotpdf.so.1 and public symbols assigned to HOTPDF_1.0

The library uses THPDFHeadlessDocument and CPU rendering without a Windows component, an active desktop, a PDF viewer, or a Python process at runtime; Python is used by the build and acceptance scripts

Build and acceptance

sh Tests/Linux/Build-LinuxABI.sh
sh Tests/Linux/Run-LinuxABIAcceptance.sh
FPC_EXE=/usr/local/bin/fpc HPDF_LINUX_OUTPUT=Tests/Linux/bin/linux-abi331 sh Tests/Linux/Run-LinuxABIAcceptance.sh

Use native FPC 3.2.2 or newer with FCL and paszlib, a C compiler, binutils, Fontconfig and installed TrueType fonts; the acceptance Python environment also needs pypdf with its AES provider, PyMuPDF, Pillow and NumPy

FPC_EXE, HPDF_LINUX_OUTPUT, and PYTHON_EXE select tool locations; the default acceptance Python environment is /opt/hotpdf-python/bin/python

FPC normally writes an anonymous export block into its ELF linker response; the build names that block using the checked-in symbol map before linking, because adding a second named version script would conflict with the anonymous block

Public interface

Include Lib/hotpdf_abi.h for the shared record layout and status constants; hpdf_abi_io_v1_size and hpdf_abi_operation_v1_size report actual native record sizes

The Linux library exports ABI discovery, capability discovery, document creation and destruction, callback loading and saving, page counting, hpdf_document_execute_json_v1 and the two-document hpdf_document_compare_json_v1 entry point

Discover the current operations through hpdf_capabilities_json_to_io instead of assuming the Windows operation set

{"schemaVersion":1,"type":"render","page":0,"dpi":150,"usage":"print","annotations":false,
 "limits":{"memoryBytes":268435456,"outputBytes":268435456,"pixels":100000000}}

Native signing workflows accept an explicit PEM or Base64 PFX identity, optional new signature fields and Unicode appearances, and certification permissions; successful signing replaces the loaded context with the prepared signed revision, whilst failed signing or publication preserves the original context

Native signing options bind actual SHA256, SHA384 or SHA512 selection, Unicode signature information, legal attestation, explicit trust bytes, validated signed revocation evidence, real appearance presets, and application-asserted credential or timestamp transport provenance

The optional optional-content viewer state supplies explicit automatic View, Print or Export usage applications, zoom, language, user context and operation-local manual selections through unchanged V1 records

The render operation accepts usage: "view" or usage: "print", defaulting to view; discover the choices through the capability renderUsages array, with unchanged V1 callback and operation records

Annotation screen and printing flags follow the selected usage, and annotations: false suppresses annotations in either mode; omitting optionalContent retains the static default configuration, whilst an explicit object activates the documented automatic recommendations and operation-local manual selections

Tests/Linux/Run-LinuxABIRenderUsage.sh verifies actual PNG pixels for plain and AES R5/R6 sources, default-off content, callback failures, budgets, cancellation and same-handle recovery; see Tests/Linux/HeadlessRenderUsage.en-us.md for fixture dependencies and the optional pre-generated fixture directory

Callbacks and lifetime

Form appearance options accept Unicode text, export values or complete selection arrays, explicit button states, font settings and transactional resource limits

Read and write callbacks may return partial transfers; successful transfers must make positive progress and must not exceed the requested count

All callbacks execute synchronously on the calling thread, including cancellation checks inside document parsing, rendering and cryptographic checkpoints

Callback input is copied into an exclusively created private temporary file with mode 0600, so Linux input callbacks and their user data need remain valid only until the load or execute call returns

Operations on a shared document handle serialise internally; each active call holds an independent reference, so destroying a handle from a progress callback invalidates subsequent lookup whilst allowing the current call to finish safely

Do not recursively execute another operation on the same handle from its callback; keep the shared library loaded until all calls have returned and every handle has been destroyed

Budgets and publication

JSON input is limited to 4 MiB and 64 nesting levels, and rejects invalid UTF-8, duplicate members, malformed numeric limits and Int64-to-Int32 parameter truncation

Raw UTF-8 and Unicode escapes carry the same string values, including supplementary characters represented by valid UTF-16 surrogate pairs; unpaired surrogate escapes fail before document mutation or binary publication

Operation limits include memoryBytes, outputBytes, resultBytes, and pixels; document limits also apply to previously loaded handles, whilst managed memory and rendering limits do not promise a process RSS cap

PDF and PNG output is fully prepared and checked before output callbacks begin; a caller-owned output callback can retain a partial transfer after its own I/O failure, but failed binary or result publication does not commit form edits or replace a previously loaded context

Successful PDF mutations commit the prepared output as both the current document and its private source snapshot, so a following same-value FDF or XFDF import returns the exact committed PDF bytes with updated=0, retaining earlier form fills, typed rich appearances, drawn text and imported pages

Private staging files are removed when the context is replaced or destroyed; successful incremental form and signature output preserves the original source prefix and encryption policy

Evidence

Optional archival font repair enables bounded Ghostscript substitution and embedding with genuine PDF/A-4 validation before callbacks

Native annotated review PDF adds actual prepared PDF output, Unicode highlights and authenticated P3 annotation permissions to semantic comparison

Native contract comparison provides bounded two-handle semantic comparison, Unicode review HTML and actual source-line geometry

General native document comparison normalises object graphs and stream encoding, compares real Cairo pixels with explicit thresholds, and preserves document state and callback publication budgets

The acceptance client verifies real C header layouts and versioned symbol lookup, partial callbacks, 80 concurrent shared-handle operations, cancellation, Unicode edits, rollback and encrypted signing

Independent pypdf, MuPDF and OpenSSL readers verify the actual PDFs, PNG pixels, retained passwords, security dictionaries, document IDs, exact ByteRange gaps, valid signatures and rejection of modified signed bytes

Headless document API · Native rendering · Remaining delivery plan