Platform Helpers

These functions/structures/types are used to perform actions that typically don’t have shared functions across different operating systems and platforms.

#include <util/platform.h>

File Functions

FILE *os_wfopen(const wchar_t *path, const char *mode)

Opens a file with a wide string path.


FILE *os_fopen(const char *path, const char *mode)

Opens a file with a UTF8 string path.


int64_t os_fgetsize(FILE *file)

Returns a file’s size.


int os_stat(const char *file, struct stat *st)

Equivalent to the posix stat function.


int os_fseeki64(FILE *file, int64_t offset, int origin)

Equivalent to fseek.


int64_t os_ftelli64(FILE *file)

Gets the current file position.


size_t os_fread_utf8(FILE *file, char **pstr)

Reads a UTF8 encoded file and allocates a pointer to the UTF8 string.


char *os_quick_read_utf8_file(const char *path)

Reads a UTF8 encoded file and returns an allocated pointer to the string.


bool os_quick_write_utf8_file(const char *path, const char *str, size_t len, bool marker)

Writes a UTF8 encoded file.


bool os_quick_write_utf8_file_safe(const char *path, const char *str, size_t len, bool marker, const char *temp_ext, const char *backup_ext)

Writes a UTF8 encoded file with overwrite corruption prevention.


int64_t os_get_file_size(const char *path)

Gets a file’s size.


int64_t os_get_free_space(const char *path)

Gets free space of a specific file path.


String Conversion Functions

size_t os_utf8_to_wcs(const char *str, size_t len, wchar_t *dst, size_t dst_size)

Converts a UTF8 string to a wide string.


size_t os_wcs_to_utf8(const wchar_t *str, size_t len, char *dst, size_t dst_size)

Converts a wide string to a UTF8 string.


size_t os_utf8_to_wcs_ptr(const char *str, size_t len, wchar_t **pstr)

Gets an bmalloc-allocated wide string converted from a UTF8 string.


size_t os_wcs_to_utf8_ptr(const wchar_t *str, size_t len, char **pstr)

Gets an bmalloc-allocated UTF8 string converted from a wide string.


Number/String Conversion Functions

double os_strtod(const char *str)

Converts a string to a double.


int os_dtostr(double value, char *dst, size_t size)

Converts a double to a string.



CPU Usage Functions

os_cpu_usage_info_t *os_cpu_usage_info_start(void)

Creates a CPU usage information object.


double os_cpu_usage_info_query(os_cpu_usage_info_t *info)

Queries the current CPU usage.


void os_cpu_usage_info_destroy(os_cpu_usage_info_t *info)

Destroys a CPU usage information object.


Sleep/Time Functions

bool os_sleepto_ns(uint64_t time_target)

Sleeps to a specific time with high precision, in nanoseconds.


bool os_sleepto_ns_fast(uint64_t time_target)

Sleeps to a specific time without high precision, in nanoseconds. The function won’t return until reaching the specific time.


void os_sleep_ms(uint32_t duration)

Sleeps for a specific number of milliseconds.


uint64_t os_gettime_ns(void)

Gets the current high-precision system time, in nanoseconds.


Other Path/File Functions

int os_get_config_path(char *dst, size_t size, const char *name)
char *os_get_config_path_ptr(const char *name)

Gets the user-specific application configuration data path.


int os_get_program_data_path(char *dst, size_t size, const char *name)
char *os_get_program_data_path_ptr(const char *name)

Gets the application configuration data path.


bool os_file_exists(const char *path)

Returns true if a file/directory exists, false otherwise.


size_t os_get_abs_path(const char *path, char *abspath, size_t size)
char *os_get_abs_path_ptr(const char *path)

Converts a relative path to an absolute path.


const char *os_get_path_extension(const char *path)

Returns the extension portion of a path string, including the dot (.).


typedef struct os_dir os_dir_t

A directory object.

struct os_dirent

A directory entry record.

char os_dirent.d_name[256]

The directory entry name.

bool os_dirent.directory

true if the entry is a directory.


os_dir_t *os_opendir(const char *path)

Opens a directory object to enumerate files within the directory.


struct os_dirent *os_readdir(os_dir_t *dir)

Returns the linked list of directory entries.


void os_closedir(os_dir_t *dir)

Closes a directory object.


struct os_globent

A glob entry.

char *os_globent.path

The full path to the glob entry.

bool os_globent.directory

true if the glob entry is a directory, false otherwise.

struct os_glob_info

A glob object.

size_t os_glob_info.gl_pathc

Number of glob entries.

struct os_globent *os_glob_info.gl_pathv

Array of glob entries.

typedef struct os_glob_info os_glob_t

int os_glob(const char *pattern, int flags, os_glob_t **pglob)

Enumerates files based upon a glob string.


void os_globfree(os_glob_t *pglob)

Frees a glob object.


Deletes a file.


int os_rmdir(const char *path)

Deletes a directory.


char *os_getcwd(char *path, size_t size)

Returns a new bmalloc-allocated path to the current working directory.


int os_chdir(const char *path)

Changes the current working directory.


int os_mkdir(const char *path)

Creates a directory.


int os_mkdirs(const char *path)

Creates a full directory path if it doesn’t exist.


int os_rename(const char *old_path, const char *new_path)

Renames a file.


int os_copyfile(const char *file_in, const char *file_out)

Copies a file.


int os_safe_replace(const char *target_path, const char *from_path, const char *backup_path)

Safely replaces a file.


char *os_generate_formatted_filename(const char *extension, bool space, const char *format)

Returns a new bmalloc-allocated filename generated from specific formatting.


Sleep-Inhibition Functions

These functions/types are used to inhibit the computer from going to sleep.

struct os_inhibit_info
typedef struct os_inhibit_info os_inhibit_t

os_inhibit_t *os_inhibit_sleep_create(const char *reason)

Creates a sleep inhibition object.


bool os_inhibit_sleep_set_active(os_inhibit_t *info, bool active)

Activates/deactivates a sleep inhibition object.


void os_inhibit_sleep_destroy(os_inhibit_t *info)

Destroys a sleep inhibition object. If the sleep inhibition object was active, it will be deactivated.


Other Functions

void os_breakpoint(void)

Triggers a debugger breakpoint (or crashes the program if no debugger present).


int os_get_physical_cores(void)

Returns the number of physical cores available.


int os_get_logical_cores(void)

Returns the number of logical cores available.


uint64_t os_get_sys_free_size(void)

Returns the amount of memory available.


uint64_t os_get_sys_total_size(void)

Returns the amount of memory installed.

Added in version 29.0.0.


struct os_proc_memory_usage

Memory usage structure.

uint64_t os_proc_memory_usage.resident_size

Resident size.

uint64_t os_proc_memory_usage.virtual_size

Virtual size.

typedef struct os_proc_memory_usage os_proc_memory_usage_t

bool os_get_proc_memory_usage(os_proc_memory_usage_t *usage)

Gets memory usage of the current process.


uint64_t os_get_proc_resident_size(void)

Returns the resident memory size of the current process.


uint64_t os_get_proc_virtual_size(void)

Returns the virtual memory size of the current process.


bool os_get_emulation_status(void)

Returns true if the current process is an x64 binary and is being emulated or translated by the host operating system. On macOS, it returns true when an x64 binary is being translated by Rosetta and running on Apple Silicon Macs. On Windows, it returns true when an x64 binary is being emulated on Windows ARM64 PCs. On all other platforms, it will always returns false.


char *os_generate_uuid(void)

Creates a version 4 UUID and returns a NULL-terminated 36-character string. Must be freed with bfree().

Added in version 29.1.