stsp / lfanew

https://codeberg.org/tkchia/lfanew

lfanew

lfanew comprises

• a tool to manipulate fat binary programs wrapped inside MS-DOS MZ files;

• plus a simple C code library for working with binary files, including MS-DOS executables.

Tool

Usage:

• lfanew [-k] -o out-stub-file in-stub-file

• lfanew -S [-kp] -o out-fat-file in-payload-file in-stub-file

• lfanew -U [-kp] -o out-payload-file in-fat-file

Operating modes:

• On default, lfanew adds a .e_lfanew header field^[1] to an old-style MZ executable program, so that the program can potentially be used as an MS-DOS loader stub for a modern "new executable" format.

• -S ("stubify"): tells lfanew to create a fat binary by combining an MZ stub with a "new executable" payload.

• -U ("unstubify"): tells lfanew to extract the "new executable" payload contained inside a fat binary, removing any MZ stub.

Options:

• -k ("keep"): says to keep the output file in case of an error, rather than delete it.

• -p ("pages"): for -S or -U, says to derive the stub size from .e_cp and .e_cblp, rather than from .e_lfanew.

lfanew can add a stub to a Microsoft Portable Executable (PE)^[2] payload, if there is enough RVA space before the PE sections to accommodate the stub (and PE headers). You will likely need to unstubify a PE program before attaching it to a different stub.

Code library

Legend

Compat.	Meaning
P08	Part of the POSIX.1-2008[3] standard.
X	lfanew-specific extension.

Avail.	Meaning
=	Facility is available for all host platforms.
(=)	Facility is available if the host platform does not already define this facility itself.
64	Facility is available only if the host C compiler directly support 64-bit integers (uint64_t etc.).

Types

Compat.	Avail.	Type	Notes
		▗▚▚▚▚ <nexgen/mzendian.h> ▞▞▞▞▖ This header defines types and routines for accessing unaligned little endian binary data in a type-checked manner. <nexgen/mzendian.h> also includes <stdint.h>.
X	=	uint_le16_t	Unaligned 16-, 32-, or 64-bit little endian binary numeral. These types can be used directly inside a struct or union corresponding to a binary file structure, but should otherwise be treated as opaque.
X	=	uint_le32_t
X	=	uint_le64_t
		▗▚▚▚▚ <nexgen/mzhdr.h> ▞▞▞▞▖
X	=	mz_hdr_t	MZ structure[1] at the beginning of an MS-DOS or Windows program.

Functions

Compat.	Avail.	Function	Notes
		▗▚▚▚▚ <lfanew/dirent.h> ▞▞▞▞▖
P08	(=)	scandir (*path, *names, *filt, *comp);	Scans the directory given by path, filters them with filt, then returns a malloc'd list of directory entries in *names sorted with the comparator comp. (POSIX places this function in <dirent.h>.)
		▗▚▚▚▚ <lfanew/io.h> ▞▞▞▞▖
X	=	_binmode (handle);	Sets the POSIX-style file handle to do untranslated (binary) I/O — so that read and write calls with the handle will not translate between LF and CRLF, nor specially interpret bytes that look like end-of-file indicators. Upon an error, this function returns -1 and sets errno.
		▗▚▚▚▚ <nexgen/mzendian.h> ▞▞▞▞▖
X	=	uint_le16_t _hle16 (uint16_t x);	Converts x from host byte order to little endian.
X	=	uint_le32_t _hle32 (uint32_t x);
X	64	uint_le64_t _hle64 (uint64_t x);
X	=	uint16_t _leh16 (uint_le16_t x);	Converts x from little endian to host byte order.
X	=	uint32_t _leh32 (uint_le32_t x);
X	=	uint16_t _leh32hi (uint_le32_t x);	Converts x from little endian to host byte order, and returns the high or low 16-bit half respectively.
X	=	uint16_t _leh32lo (uint_le32_t x);
X	64	uint64_t _leh64 (uint_le64_t x);	Converts x from little endian to host byte order.
X	=	uint32_t _leh64hi (uint_le64_t x);	Converts x from little endian to host byte order, and returns the high or low 32-bit half respectively.
X	=	uint32_t _leh64lo (uint_le64_t x);

---

1. M. Pietrek. Inside Windows: an in-depth look into the Win32 Portable Executable file format. MSDN Magazine, Feb 2002. https://learn.microsoft.com/en-us/archive/msdn-magazine/2002/february/inside-windows-win32-portable-executable-file-format-in-detail.

2. Microsoft Corporation. PE Format. Microsoft Learn, 24 Mar 2023. https://learn.microsoft.com/en-us/windows/win32/debug/pe-format. Archived on 26 Jul 2023 at https://web.archive.org/web/20230726221442/https://learn.microsoft.com/en-us/windows/win32/debug/pe-format.

3. Institute of Electrical and Electronics Engineers, and The Open Group. IEEE Std 1003.1™-2008, 2008. https://pubs.opengroup.org/onlinepubs/9699919799.2008edition/.