Changing Linux Page Size: Find Hard-Coded mmap and Buffer-Alignment Assumptions

Obtain the running process’s base page size, use it in mapping arithmetic and qualify every binary that assumes a particular layout. A source constant of 4096 can work for years and fail when an otherwise similar image uses a different page size. The failure can occur in file offsets, protection boundaries, allocator assumptions or binary loading.

This guide uses the Linux man-pages 6.12 release documentation. A bounded host fixture exercised three ordinary file-mapping cases on x86-64 with a reported 4096-byte base page. That is not a test of a 16 KiB or 64 KiB kernel, an embedded target, a device mapping or an ELF loader migration.

Identify which alignment the code actually needs

Inventory hard-coded page constants and bit masks in mmap, munmap, protection changes, mapped-file readers, allocators and runtime loaders. Search for expressions that round by 4095 or clear twelve low bits, not only symbols named PAGE_SIZE. Generated code and third-party libraries can carry the same assumption.

The getpagesize documentation in the official man-pages 6.12 archive warns against hard-coding a userspace page size, including reliance on a PAGE_SIZE macro. Query the runtime value through an appropriate userspace interface such as sysconf(_SC_PAGE_SIZE), and check that the returned value is valid before using it.

Keep base pages distinct from huge pages, cache lines, device DMA alignment, flash programming units and application record size. They are separate contracts. Replacing every alignment constant with the runtime base page size can be just as wrong as retaining every old constant.

Translate a logical file range into a mapping

The mmap reference in that release requires a file offset aligned to the page size. For a desired logical offset O and positive byte count N, let P be the valid runtime page size. Compute base as floor(O/P) multiplied by P, delta as O minus base, and mapping length as delta plus N.

Map from base, then access the requested data at returned_address plus delta. Retain the original mapping address and length for unmapping. The interior data pointer is not the address that should be passed to munmap.

base   = (offset / page_size) * page_size;
delta  = offset - base;
length = delta + requested_bytes;
/* Validate ranges and overflow before mmap(), then retain its base. */

This is integer-arithmetic pseudocode for nonnegative file offsets, not complete C error handling. Check addition overflow, conversion between off_t and size_t, permitted file range and address-space limits before calling the mapping API. The division form makes the dependency visible without relying on an unexplained power-of-two mask.

Separate mapping success from valid file access

A successful mmap does not prove that every later access is valid. The man-page documents SIGBUS for accessing pages beyond the mapped file’s end. Another process truncating the file can change that condition after the initial size check. Define who owns file size and lifetime during the operation.

Do not treat rounded-up page coverage as extra application data. Check the requested logical range against the file contract, including the final partial page. Avoid exposing neighboring mapped bytes through an oversized parser or response merely because the virtual mapping covers them.

For ordinary file mappings, closing the file descriptor after successful mmap does not invalidate the mapping. That lifetime distinction can help a design, but it does not protect against external file changes or establish synchronization with another writer.

Use a page-size boundary matrix

Case	What it establishes
Offset zero, one runtime page	Basic mapping and data comparison
Unaligned raw offset	The caller detects or handles the API alignment rejection
Logical offset P+17	Base/delta translation returns the intended bytes
Range crossing a page boundary	Length arithmetic includes the complete logical range
Near-end and overflow inputs	Validation rejects an invalid or unrepresentable range before access
Different supported base page	The actual target build and binary set remain compatible

The executed Python fixture created its own temporary file, checked one page of data, observed EINVAL for offset one, and verified a sixty-four-byte range beginning at P+17 through the translated mapping. It changed no kernel settings and deliberately avoided invalid memory accesses. Its result is limited to that host and those three cases.

For other page sizes, boot the intended supported target configuration and rerun the real application tests. Changing a variable in a host model can test arithmetic, but it cannot make that host kernel use a different base page size.

Audit binary and library assumptions separately

Record each executable, shared object, plugin and prebuilt runtime that must load on the candidate image. Inspect its ELF program headers with a compatible readelf tool and review load-segment alignment against the target loader’s requirements. Then test actual loading on the candidate kernel; file inspection alone is not a complete loader qualification.

Include rarely loaded plugins, helper utilities and recovery tools. A main application can start while a later module fails. Obtain a supported build from the supplier when a closed binary’s assumptions cannot be established; source changes in the main program do not repair an incompatible library.

Do not prescribe a universal linker flag or page-size value across architectures. The toolchain, ABI, loader and kernel configuration must agree. Preserve those identities with the result and separate an unsupported binary from a bug in mapping arithmetic.

Review protection and fixed-address use

Page-granular protection can cover more neighboring data when the base page grows. Check designs that place writable and read-only objects close together or assume a small guard interval. Verify the complete protected region, not only the requested object pointer.

Avoid using MAP_FIXED as a casual alignment repair. The mmap documentation warns that it can replace overlapping existing mappings. Ordinary mappings with a null address let the kernel choose a suitable address; specialized fixed-address designs need their own reviewed ownership and collision rules.

Make the release decision from two kinds of evidence

Require both runtime-size-aware application arithmetic and successful target qualification of the shipped binary set. Keep expected rejection cases alongside successful maps, and verify that cleanup uses the original mapping identity.

The final record should distinguish host fixture results, alternate-size target results and untested components. A successful 4096-byte-page test proves neither portability to another base page nor compatibility of every prebuilt library. That explicit boundary is what keeps a page-size migration from becoming an unexplained board-specific failure.