User mode Cross platform APIs for platofrm dependend library calls. More...

#include "pch.h"

Functions
INT	PlatformVsnprintf (char Buffer, SIZE_T BufferSize, const char Format, va_list ArgList)
	Platform independent wrapper for vsprintf_s / vsnprintf.
char *	PlatformStrDup (const char *Str)
	Platform independent wrapper for _strdup / strdup.
VOID	PlatformZeroMemory (PVOID Buffer, SIZE_T Size)
	Platform independent wrapper for RtlZeroMemory / memset.
BOOLEAN	PlatformQueryPerformanceFrequency (LARGE_INTEGER *Frequency)
	Platform independent wrapper for QueryPerformanceFrequency.
BOOLEAN	PlatformQueryPerformanceCounter (LARGE_INTEGER *Count)
	Platform independent wrapper for QueryPerformanceCounter.
INT	PlatformSprintf (char Buffer, SIZE_T BufferSize, const char Format,...)
	Platform independent wrapper for sprintf_s / snprintf.
UINT32	PlatformGetCurrentThreadId (VOID)
	Platform independent wrapper for GetCurrentThreadId / gettid.
UINT32	PlatformGetCurrentProcessorNumber (VOID)
	Platform independent wrapper for GetCurrentProcessorNumber / sched_getcpu.
UINT32	PlatformGetCurrentProcessId (VOID)
	Platform independent wrapper for GetCurrentProcessId / getpid.
CHAR *	PlatformGetCurrentProcessName (VOID)
	Platform independent wrapper to get the current process name.
HANDLE	PlatformCreateEvent (BOOLEAN ManualReset, BOOLEAN InitialState)
	Platform independent wrapper for CreateEvent.
BOOLEAN	PlatformSetEvent (HANDLE EventHandle)
	Platform independent wrapper for SetEvent.
BOOLEAN	PlatformResetEvent (HANDLE EventHandle)
	Platform independent wrapper for ResetEvent.
DWORD	PlatformWaitForSingleObject (HANDLE Handle, DWORD TimeoutMilliseconds)
	Platform independent wrapper for WaitForSingleObject.
BOOLEAN	PlatformCloseHandle (HANDLE Handle)
	Platform independent wrapper for CloseHandle.
DWORD	PlatformGetLastError (VOID)
	Platform independent wrapper for GetLastError.
BOOLEAN	PlatformWriteConsole (const VOID *Buffer, DWORD NumberOfBytes)
	Platform independent wrapper to write raw bytes to the console.
HANDLE	PlatformOpenFileForWriting (const WCHAR *Path)
	Platform independent wrapper to create/open a file for writing.
BOOLEAN	PlatformWriteFile (HANDLE FileHandle, const VOID *Buffer, DWORD NumberOfBytes)
	Platform independent wrapper to write a buffer to an open file.
BOOLEAN	PlatformCloseFile (HANDLE FileHandle)
	Platform independent wrapper to close a file opened by PlatformOpenFileForWriting.
VOID *	PlatformMapFileReadOnly (const WCHAR *Path, PSIZE_T OutFileSize, PHANDLE OutFileHandle)
	Platform independent wrapper to map an entire file read-only into memory.
BOOLEAN	PlatformReadFileAtOffset (HANDLE FileHandle, UINT64 Offset, VOID *Buffer, DWORD NumberOfBytes, LPDWORD BytesRead)
	Platform independent wrapper for a positioned (seek + read) file read.
VOID	PlatformUnmapFile (VOID *BaseAddress, SIZE_T FileSize, HANDLE FileHandle)
	Platform independent wrapper to release a mapping from PlatformMapFileReadOnly.

Detailed Description

User mode Cross platform APIs for platofrm dependend library calls.

Author: Max Raulea (max.r.nosp@m.aule.nosp@m.a@gma.nosp@m.il.c.nosp@m.om)

Version: 0.19

Date: 2026-06-01

Copyright: This project is released under the GNU Public License v3.

Function Documentation

◆ PlatformCloseFile()

BOOLEAN PlatformCloseFile ( HANDLE FileHandle )

Platform independent wrapper to close a file opened by PlatformOpenFileForWriting.

Parameters

FileHandle handle to close

Returns: BOOLEAN TRUE on success

{
#if defined(_WIN32)
    return (BOOLEAN)CloseHandle(FileHandle);
#elif defined(__linux__)
    return (BOOLEAN)(fclose((FILE *)FileHandle) == 0);
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformCloseHandle()

BOOLEAN PlatformCloseHandle ( HANDLE Handle )

Platform independent wrapper for CloseHandle.

{
#if defined(_WIN32)
    return (BOOLEAN)CloseHandle(Handle);
#elif defined(__linux__)
    (void)Handle; // TODO: free the underlying cond/eventfd or close the fd
    return TRUE;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformCreateEvent()

HANDLE PlatformCreateEvent	(	BOOLEAN	ManualReset,
		BOOLEAN	InitialState )

Platform independent wrapper for CreateEvent.

Parameters

ManualReset	TRUE for a manual-reset event, FALSE for auto-reset
InitialState	TRUE if the event starts signaled

Returns: HANDLE to the event, or NULL on failure

{
#if defined(_WIN32)
    return CreateEvent(NULL, ManualReset, InitialState, NULL);
#elif defined(__linux__)
    //
    // TODO: back this with a pthread mutex+cond (or eventfd) when the Linux
    //       kernel-debugger transport is implemented. For now return a dummy
    //       non-NULL handle so existing NULL-checks treat creation as success.
    //
    (void)ManualReset;
    (void)InitialState;
    return (HANDLE)(uintptr_t)1;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformGetCurrentProcessId()

UINT32 PlatformGetCurrentProcessId ( VOID )

Platform independent wrapper for GetCurrentProcessId / getpid.

Returns: UINT32 PID of the calling process

{
#if defined(_WIN32)
    return (UINT32)GetCurrentProcessId();
#elif defined(__linux__)
    return (UINT32)getpid();
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformGetCurrentProcessName()

CHAR * PlatformGetCurrentProcessName ( VOID )

Platform independent wrapper to get the current process name.

Returns: CHAR* pointer to a static buffer holding the process name, or NULL on failure

{
    static CHAR ProcessNameBuf[MAX_PATH] = {0};
 
#if defined(_WIN32)
    //
    // Use base kernel32 only (no psapi/shlwapi) so this compiles in every
    // project that builds platform-lib-calls.c (e.g. script-engine, which has
    // a minimal include set). GetModuleFileNameA(NULL, ...) returns the full
    // path of the current process image.
    //
    if (GetModuleFileNameA(NULL, ProcessNameBuf, MAX_PATH) == 0)
    {
        return NULL;
    }
 
    //
    // Return the basename (strip the directory part)
    //
    char * LastSeparator = strrchr(ProcessNameBuf, '\\');
    if (LastSeparator)
    {
        return LastSeparator + 1;
    }
 
    return ProcessNameBuf;
 
#elif defined(__linux__)
    FILE * f = fopen("/proc/self/comm", "r");
    if (f)
    {
        if (fgets(ProcessNameBuf, sizeof(ProcessNameBuf), f))
        {
            size_t Len = strlen(ProcessNameBuf);
            if (Len > 0 && ProcessNameBuf[Len - 1] == '\n')
                ProcessNameBuf[Len - 1] = '\0';
        }
        fclose(f);
        return ProcessNameBuf;
    }
    return NULL;
 
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformGetCurrentProcessorNumber()

UINT32 PlatformGetCurrentProcessorNumber ( VOID )

Platform independent wrapper for GetCurrentProcessorNumber / sched_getcpu.

Returns: UINT32 logical processor index the calling thread is running on

{
#if defined(_WIN32)
    return (UINT32)GetCurrentProcessorNumber();
#elif defined(__linux__)
    return (UINT32)sched_getcpu();
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformGetCurrentThreadId()

UINT32 PlatformGetCurrentThreadId ( VOID )

Platform independent wrapper for GetCurrentThreadId / gettid.

Returns: UINT32 thread ID of the calling thread

{
#if defined(_WIN32)
    return (UINT32)GetCurrentThreadId();
#elif defined(__linux__)
    return (UINT32)syscall(SYS_gettid);
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformGetLastError()

DWORD PlatformGetLastError ( VOID )

Platform independent wrapper for GetLastError.

{
#if defined(_WIN32)
    return GetLastError();
#elif defined(__linux__)
    return (DWORD)errno;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformMapFileReadOnly()

VOID * PlatformMapFileReadOnly	(	const WCHAR *	Path,
		PSIZE_T	OutFileSize,
		PHANDLE	OutFileHandle )

Platform independent wrapper to map an entire file read-only into memory.

The returned pointer stays valid until released with PlatformUnmapFile; the underlying file/descriptor is closed before returning (the mapping outlives it on both platforms).

Parameters

Path	wide path of the file to map
OutFileSize	output — size of the file in bytes (0 on failure)

Returns: VOID* base address of the mapped file, or NULL on failure

{
#if defined(_WIN32)
    HANDLE        FileHandle;
    HANDLE        MapObjectHandle;
    VOID *        BaseAddr;
    LARGE_INTEGER FileSize;
 
    *OutFileSize   = 0;
    *OutFileHandle = INVALID_HANDLE_VALUE;
 
    FileHandle = CreateFileW(Path, GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
    if (FileHandle == INVALID_HANDLE_VALUE)
    {
        return NULL;
    }
 
    if (!GetFileSizeEx(FileHandle, &FileSize))
    {
        CloseHandle(FileHandle);
        return NULL;
    }
 
    MapObjectHandle = CreateFileMapping(FileHandle, NULL, PAGE_READONLY, 0, 0, NULL);
    if (MapObjectHandle == NULL)
    {
        CloseHandle(FileHandle);
        return NULL;
    }
 
    BaseAddr = MapViewOfFile(MapObjectHandle, FILE_MAP_READ, 0, 0, 0);
 
    //
    // The view stays valid after the mapping object handle is closed. The file
    // handle is kept open and handed back so the caller can still issue raw
    // reads (PlatformReadFileAtOffset); it is closed by PlatformUnmapFile.
    //
    CloseHandle(MapObjectHandle);
 
    if (BaseAddr == NULL)
    {
        CloseHandle(FileHandle);
        return NULL;
    }
 
    *OutFileSize   = (SIZE_T)FileSize.QuadPart;
    *OutFileHandle = FileHandle;
    return BaseAddr;
#elif defined(__linux__)
    //
    // TODO (linux): implement the real mapping. Expected contract:
    //   1. Narrow the 4-byte wchar_t 'Path' to a UTF-8 char* (the project still
    //      lacks a wchar_t->UTF-8 helper; the same one is needed by
    //      PlatformOpenFileForWriting for the dump.cpp write path).
    //   2. fd = open(narrowed_path, O_RDONLY);                  // fail -> NULL
    //   3. fstat(fd, &st) to get the file size.
    //   4. base = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
    //   5. *OutFileHandle = (HANDLE)(intptr_t)fd;  // keep fd open for raw reads
    //   6. *OutFileSize = st.st_size; return base;  (return NULL on any failure)
    // PlatformUnmapFile must then munmap(base, size) and close the fd — which is
    // why both the size and the handle are passed back in on unmap. The raw-read
    // path (PlatformReadFileAtOffset) would pread() from that same fd.
    //
    // Until implemented, fail the map so PE-parser callers print "could not open
    // the file" and bail out cleanly instead of dereferencing a bogus pointer.
    //
    (void)Path;
    *OutFileSize   = 0;
    *OutFileHandle = INVALID_HANDLE_VALUE;
    return NULL;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformOpenFileForWriting()

HANDLE PlatformOpenFileForWriting ( const WCHAR * Path )

Platform independent wrapper to create/open a file for writing.

Parameters

Path	wide path of the file to create (truncated if it exists)

Returns: HANDLE to the opened file, or INVALID_HANDLE_VALUE on failure

{
#if defined(_WIN32)
    return CreateFileW(Path, GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL);
#elif defined(__linux__)
    //
    // TODO: handle this later. The path arrives as a std::wstring (4-byte
    //       wchar_t on Linux) and must be narrowed to a UTF-8 char* before it
    //       can be handed to fopen. Until that conversion is wired up, fail the
    //       open so callers (e.g. dump.cpp) bail out cleanly instead of writing
    //       to a bogus handle.
    //
    (void)Path;
    return INVALID_HANDLE_VALUE;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformQueryPerformanceCounter()

BOOLEAN PlatformQueryPerformanceCounter ( LARGE_INTEGER * Count )

Platform independent wrapper for QueryPerformanceCounter.

Parameters

Count output — current tick count

Returns: BOOLEAN TRUE on success

{
#if defined(_WIN32)
    return (BOOLEAN)QueryPerformanceCounter((LARGE_INTEGER *)Count);
#elif defined(__linux__)
    struct timespec Ts;
    clock_gettime(CLOCK_MONOTONIC, &Ts);
    Count->QuadPart = (INT64)Ts.tv_sec * 1000000000LL + Ts.tv_nsec;
    return TRUE;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformQueryPerformanceFrequency()

BOOLEAN PlatformQueryPerformanceFrequency ( LARGE_INTEGER * Frequency )

Platform independent wrapper for QueryPerformanceFrequency.

Parameters

Frequency output — ticks per second

Returns: BOOLEAN TRUE on success

{
#if defined(_WIN32)
    return (BOOLEAN)QueryPerformanceFrequency((LARGE_INTEGER *)Frequency);
#elif defined(__linux__)
    Frequency->QuadPart = 1000000000LL; // clock_gettime gives nanosecond resolution
    return TRUE;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformReadFileAtOffset()

BOOLEAN PlatformReadFileAtOffset	(	HANDLE	FileHandle,
		UINT64	Offset,
		VOID *	Buffer,
		DWORD	NumberOfBytes,
		LPDWORD	BytesRead )

Platform independent wrapper for a positioned (seek + read) file read.

Parameters

FileHandle	handle handed back by PlatformMapFileReadOnly
Offset	byte offset to read from (absolute, from start of file)
Buffer	destination buffer
NumberOfBytes	number of bytes to read
BytesRead	output — number of bytes actually read

Returns: BOOLEAN TRUE on success

{
#if defined(_WIN32)
    LARGE_INTEGER Distance;
    Distance.QuadPart = (LONGLONG)Offset;
 
    if (!SetFilePointerEx(FileHandle, Distance, NULL, FILE_BEGIN))
    {
        return FALSE;
    }
 
    return (BOOLEAN)ReadFile(FileHandle, Buffer, NumberOfBytes, BytesRead, NULL);
#elif defined(__linux__)
    //
    // TODO (linux): pread((int)(intptr_t)FileHandle, Buffer, NumberOfBytes, Offset)
    //               once PlatformMapFileReadOnly wraps a real fd. Unreached today
    //               because the map returns NULL on Linux, so callers bail first.
    //
    (void)FileHandle;
    (void)Offset;
    (void)Buffer;
    (void)NumberOfBytes;
    if (BytesRead != NULL)
    {
        *BytesRead = 0;
    }
    return FALSE;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformResetEvent()

BOOLEAN PlatformResetEvent ( HANDLE EventHandle )

Platform independent wrapper for ResetEvent.

{
#if defined(_WIN32)
    return (BOOLEAN)ResetEvent(EventHandle);
#elif defined(__linux__)
    (void)EventHandle; // TODO: clear the underlying cond/eventfd
    return TRUE;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformSetEvent()

BOOLEAN PlatformSetEvent ( HANDLE EventHandle )

Platform independent wrapper for SetEvent.

{
#if defined(_WIN32)
    return (BOOLEAN)SetEvent(EventHandle);
#elif defined(__linux__)
    (void)EventHandle; // TODO: signal the underlying cond/eventfd
    return TRUE;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformSprintf()

INT PlatformSprintf	(	char *	Buffer,
		SIZE_T	BufferSize,
		const char *	Format,
			... )

Platform independent wrapper for sprintf_s / snprintf.

Parameters

Buffer	output buffer
BufferSize	size of the output buffer
Format	format string

Returns: INT number of characters written, or -1 on error

{
    va_list Args;
    va_start(Args, Format);
    INT Result;
#if defined(_WIN32)
    Result = vsprintf_s(Buffer, BufferSize, Format, Args);
#elif defined(__linux__)
    Result = vsnprintf(Buffer, BufferSize, Format, Args);
#else
#    error "Unsupported platform"
#endif
    va_end(Args);
    return Result;
}

◆ PlatformStrDup()

char * PlatformStrDup ( const char * Str )

Platform independent wrapper for _strdup / strdup.

Parameters

Str	string to duplicate

Returns: char * pointer to the duplicated string, or NULL on failure

{
#if defined(_WIN32)
    return _strdup(Str);
#elif defined(__linux__)
    return strdup(Str);
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformUnmapFile()

VOID PlatformUnmapFile	(	VOID *	BaseAddress,
		SIZE_T	FileSize,
		HANDLE	FileHandle )

Platform independent wrapper to release a mapping from PlatformMapFileReadOnly.

Parameters

BaseAddress	base address returned by PlatformMapFileReadOnly
FileSize	size that was reported by PlatformMapFileReadOnly (needed by munmap)
FileHandle	file handle handed back by PlatformMapFileReadOnly

{
#if defined(_WIN32)
    (void)FileSize; // not needed by UnmapViewOfFile
    if (BaseAddress != NULL)
    {
        UnmapViewOfFile(BaseAddress);
    }
    if (FileHandle != INVALID_HANDLE_VALUE)
    {
        CloseHandle(FileHandle);
    }
#elif defined(__linux__)
    //
    // TODO (linux): munmap(BaseAddress, FileSize) and close the fd behind
    //               FileHandle once PlatformMapFileReadOnly is implemented.
    //               No-op for now since the map always returns NULL.
    //
    (void)BaseAddress;
    (void)FileSize;
    (void)FileHandle;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformVsnprintf()

INT PlatformVsnprintf	(	char *	Buffer,
		SIZE_T	BufferSize,
		const char *	Format,
		va_list	ArgList )

Platform independent wrapper for vsprintf_s / vsnprintf.

Parameters

Buffer	output buffer
BufferSize	size of the output buffer
Format	format string
ArgList	variadic argument list

Returns: INT number of characters written, or -1 on error

{
#if defined(_WIN32)
    return vsprintf_s(Buffer, BufferSize, Format, ArgList);
#elif defined(__linux__)
    return vsnprintf(Buffer, BufferSize, Format, ArgList);
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformWaitForSingleObject()

DWORD PlatformWaitForSingleObject	(	HANDLE	Handle,
		DWORD	TimeoutMilliseconds )

Platform independent wrapper for WaitForSingleObject.

Returns: 0 (WAIT_OBJECT_0) on success

{
#if defined(_WIN32)
    return WaitForSingleObject(Handle, TimeoutMilliseconds);
#elif defined(__linux__)
    //
    // TODO: wait on the underlying cond/eventfd. For now return immediately as
    //       success — no real transport exists yet to wait on.
    //
    (void)Handle;
    (void)TimeoutMilliseconds;
    return 0;
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformWriteConsole()

BOOLEAN PlatformWriteConsole	(	const VOID *	Buffer,
		DWORD	NumberOfBytes )

Platform independent wrapper to write raw bytes to the console.

Used to emit pre-encoded UTF-8 byte sequences (e.g. box-drawing characters) directly to standard output. On Windows this goes through WriteConsoleA so the console code page is bypassed; on Linux the terminal is UTF-8 native so the bytes are written as-is.

Parameters

Buffer	pointer to the bytes to write
NumberOfBytes	number of bytes to write

Returns: BOOLEAN TRUE on success

{
#if defined(_WIN32)
    return (BOOLEAN)WriteConsoleA(GetStdHandle(STD_OUTPUT_HANDLE), Buffer, NumberOfBytes, NULL, NULL);
#elif defined(__linux__)
    return (BOOLEAN)(fwrite(Buffer, 1, NumberOfBytes, stdout) == NumberOfBytes);
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformWriteFile()

BOOLEAN PlatformWriteFile	(	HANDLE	FileHandle,
		const VOID *	Buffer,
		DWORD	NumberOfBytes )

Platform independent wrapper to write a buffer to an open file.

Parameters

FileHandle	handle returned by PlatformOpenFileForWriting
Buffer	pointer to the bytes to write
NumberOfBytes	number of bytes to write

Returns: BOOLEAN TRUE on success

{
#if defined(_WIN32)
    DWORD BytesWritten;
    return (BOOLEAN)WriteFile(FileHandle, Buffer, NumberOfBytes, &BytesWritten, NULL);
#elif defined(__linux__)
    return (BOOLEAN)(fwrite(Buffer, 1, NumberOfBytes, (FILE *)FileHandle) == NumberOfBytes);
#else
#    error "Unsupported platform"
#endif
}

◆ PlatformZeroMemory()

VOID PlatformZeroMemory	(	PVOID	Buffer,
		SIZE_T	Size )

Platform independent wrapper for RtlZeroMemory / memset.

Zeros a memory block.

Parameters

Buffer	pointer to the memory region to zero
Size	number of bytes to zero
Destination	Memory address.
Size	Number of bytes.

{
#if defined(_WIN32)
    RtlZeroMemory(Buffer, Size);
#elif defined(__linux__)
    memset(Buffer, 0, Size);
#else
#    error "Unsupported platform"
#endif
}

Functions

Detailed Description

Function Documentation

◆ PlatformCloseFile()

◆ PlatformCloseHandle()

◆ PlatformCreateEvent()

◆ PlatformGetCurrentProcessId()

◆ PlatformGetCurrentProcessName()

◆ PlatformGetCurrentProcessorNumber()

◆ PlatformGetCurrentThreadId()

◆ PlatformGetLastError()

◆ PlatformMapFileReadOnly()

◆ PlatformOpenFileForWriting()

◆ PlatformQueryPerformanceCounter()

◆ PlatformQueryPerformanceFrequency()

◆ PlatformReadFileAtOffset()

◆ PlatformResetEvent()

◆ PlatformSetEvent()

◆ PlatformSprintf()

◆ PlatformStrDup()

◆ PlatformUnmapFile()

◆ PlatformVsnprintf()

◆ PlatformWaitForSingleObject()

◆ PlatformWriteConsole()

◆ PlatformWriteFile()

◆ PlatformZeroMemory()