Process management header. More...

Collaboration diagram for Process management:

Detailed Description

Process management header.

The sys/proc.h header handles process management, including process spawning, managing a processes address space, scheduling, and similar.

Data Structures
struct	sync_t
	Synchronization object. More...

Macros
#define	PRIORITY_MAX 63
	The maximum priority value, inclusive.

#define	PRIORITY_MAX_USER 31
	The maximum priority user space is allowed to specify, inclusive.

#define	PRIORITY_MIN 0
	The minimum priority value.

#define	PAGE_SIZE 0x1000
	The size of a memory page in bytes.

#define	BYTES_TO_PAGES(amount) (((amount) + PAGE_SIZE - 1) / PAGE_SIZE)
	Convert a size in bytes to pages.

#define	PAGE_SIZE_OF(object) BYTES_TO_PAGES(sizeof(object))
	Size of an object in pages.

#define	FUTEX_ALL UINT64_MAX
	Futex wake all constant.

Typedefs
typedef uint8_t	priority_t
	Priority type.

Enumerations
enum	spawn_flags_t { SPAWN_DEFAULT = 0 , SPAWN_SUSPEND = 1 << 0 , SPAWN_EMPTY_FDS = 1 << 1 , SPAWN_STDIO_FDS = 1 << 2 , SPAWN_EMPTY_NS = 1 << 3 , SPAWN_EMPTY_ENV = 1 << 4 , SPAWN_EMPTY_CWD = 1 << 5 }
	Spawn behaviour flags. More...

enum	prot_t { PROT_NONE = 0 , PROT_READ = (1 << 0) , PROT_WRITE = (1 << 1) , PROT_EXECUTE = (1 << 2) }
	Memory protection flags. More...

enum	futex_op_t { FUTEX_WAIT , FUTEX_WAKE }
	Futex operation enum. More...

Functions
pid_t	spawn (const char **argv, spawn_flags_t flags)
	System call for spawning new processes.

pid_t	getpid (void)
	System call to retrieve the current pid.

tid_t	gettid (void)
	System call to retrieve the current tid.

void *	mmap (fd_t fd, void *address, uint64_t length, prot_t prot)
	System call to map memory from a file.

void *	munmap (void *address, uint64_t length)
	System call to unmap mapped memory.

void *	mprotect (void *address, uint64_t length, prot_t prot)
	System call to change the protection flags of memory.

uint64_t	futex (atomic_uint64_t *addr, uint64_t val, futex_op_t op, clock_t timeout)
	System call for fast user space mutual exclusion.

clock_t	uptime (void)
	System call for retreving the time since boot.

uint64_t	nanosleep (clock_t timeout)
	System call for sleeping.

Variables
char **	environ
	The environment variables of the current process.

Macro Definition Documentation

◆ PRIORITY_MAX

#define PRIORITY_MAX 63

The maximum priority value, inclusive.

Definition at line 48 of file proc.h.

◆ PRIORITY_MAX_USER

#define PRIORITY_MAX_USER 31

The maximum priority user space is allowed to specify, inclusive.

Definition at line 49 of file proc.h.

◆ PRIORITY_MIN

#define PRIORITY_MIN 0

The minimum priority value.

Definition at line 50 of file proc.h.

◆ PAGE_SIZE

#define PAGE_SIZE 0x1000

The size of a memory page in bytes.

Definition at line 102 of file proc.h.

◆ BYTES_TO_PAGES

#define BYTES_TO_PAGES ( amount ) (((amount) + PAGE_SIZE - 1) / PAGE_SIZE)

Convert a size in bytes to pages.

Parameters

amount The amount of bytes.

Returns: The amount of pages.

Definition at line 110 of file proc.h.

◆ PAGE_SIZE_OF

#define PAGE_SIZE_OF ( object ) BYTES_TO_PAGES(sizeof(object))

Size of an object in pages.

Parameters

object The object to calculate the page size of.

Returns: The amount of pages.

Definition at line 118 of file proc.h.

◆ FUTEX_ALL

#define FUTEX_ALL UINT64_MAX

Futex wake all constant.

The FUTEX_ALL constant can be used as the val argument when using the FUTEX_WAIT operating in the futex() function to wake upp all waiters.

Definition at line 206 of file proc.h.

Typedef Documentation

◆ priority_t

priority_t

Priority type.

The priority_t type is used to store the scheduling priority of a process.

Definition at line 46 of file proc.h.

Enumeration Type Documentation

◆ spawn_flags_t

enum spawn_flags_t

Spawn behaviour flags.

Enumerator
SPAWN_DEFAULT	Default spawn behaviour.
SPAWN_SUSPEND	Starts the spawned process in a suspended state. The process will not begin executing until a "start" note is received. The purpose of this flag is to allow the parent process to modify the child process before it starts executing, for example modifying its environment variables.
SPAWN_EMPTY_FDS	Dont inherit the file descriptors of the parent process.
SPAWN_STDIO_FDS	Only inherit stdin, stdout and stderr from the parent process.
SPAWN_EMPTY_NS	Dont inherit the mountpoints of the parent's namespace.
SPAWN_EMPTY_ENV	Don't inherit the parent's environment variables.
SPAWN_EMPTY_CWD	Don't inherit the parent's current working directory, starts at root (/).

Definition at line 56 of file proc.h.

◆ prot_t

enum prot_t

Memory protection flags.

Enumerator
PROT_NONE	Invalid memory, cannot be accessed.
PROT_READ	Readable memory.
PROT_WRITE	Writable memory.
PROT_EXECUTE	Executable memory.

Definition at line 124 of file proc.h.

◆ futex_op_t

enum futex_op_t

Futex operation enum.

The futex_op_t enum is used to specify the desired futex operation in the futex() function.

Enumerator

FUTEX_WAIT

Wait until the timeout expires or the futex value changes.

If the value at the futex address is not equal to val, the call returns immediately with EAGAIN. Otherwise, the calling thread is put to sleep until another thread wakes it up or the specified timeout expires.

FUTEX_WAKE

Wake up one or more threads waiting on the futex.

Wakes up a maximum of val number of threads that are currently waiting on the futex at the specified address. If val is FUTEX_ALL, all waiting threads are woken up.

Definition at line 181 of file proc.h.

Function Documentation

◆ spawn()

pid_t spawn	(	const char **	argv,
		spawn_flags_t	flags
	)

System call for spawning new processes.

By default, the spawned process will inherit the file table, namespace, environment variables, priority and current working directory of the parent process.

Parameters

argv	A NULL-terminated array of strings, where `argv[0]` is the filepath to the desired executable.
flags	Spawn behaviour flags.

Returns: On success, the childs pid. On failure, ERR and errno is set.

Definition at line 6 of file spawn.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getpid()

pid_t getpid ( void )

System call to retrieve the current pid.

Returns: The running processes pid.

Definition at line 6 of file getpid.c.

Here is the call graph for this function:

◆ gettid()

tid_t gettid ( void )

System call to retrieve the current tid.

Returns: The running threads tid.

Definition at line 6 of file gettid.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mmap()

void * mmap	(	fd_t	fd,
		void *	address,
		uint64_t	length,
		prot_t	prot
	)

System call to map memory from a file.

The mmap() function maps memory to the currently running processes address space from a file, this is the only way to allocate virtual memory from userspace. An example usage would be to map the /dev/zero file which would allocate zeroed memory.

Parameters

fd	The open file descriptor of the file to be mapped.
address	The desired virtual destination address, if equal to `NULL` the kernel will choose a available address, will be rounded down to the nearest page multiple.
length	The length of the segment to be mapped, note that this length will be rounded up to the nearest page multiple by the kernel factoring in page boundaries.
prot	Protection flags, must have at least `PROT_READ` set.

Returns: On success, returns the address of the mapped memory, will always be page aligned, on failure returns NULL and errno is set.

Definition at line 6 of file mmap.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ munmap()

void * munmap	(	void *	address,
		uint64_t	length
	)

System call to unmap mapped memory.

The munmap() function unmaps memory from the currently running processes address space.

Parameters

address	The starting virtual address of the memory area to be unmapped.
length	The length of the memory area to be unmapped.

Returns: On success, returns the address of the unmapped memory, on failure returns NULL and errno is set.

Definition at line 6 of file munmap.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mprotect()

void * mprotect	(	void *	address,
		uint64_t	length,
		prot_t	prot
	)

System call to change the protection flags of memory.

The mprotect() changes the protection flags of a virtual memory area in the currently running processes address space.

Parameters

address	The starting virtual address of the memory area to be modified.
length	The length of the memory area to be modifed.
prot	The new protection flags of the memory area, if equal to `PROT_NONE` the memory area will be unmapped.

Returns: On success, returns the address of the modified memory area, on failure returns NULL and errno is set.

Definition at line 6 of file mprotect.c.

Here is the call graph for this function:

◆ futex()

uint64_t futex	(	atomic_uint64_t *	addr,
		uint64_t	val,
		futex_op_t	op,
		clock_t	timeout
	)

System call for fast user space mutual exclusion.

The futex() function provides a fast user-space syncronization mechanism. It can be used to implement userspace mutexes, conditional variables, etc.

Parameters

addr	A pointer to an atomic 64-bit unsigned integer.
val	The value used by the futex operation, its meaning depends on the operation.
op	The futex operation to perform (e.g., `FUTEX_WAIT` or `FUTEX_WAKE`).
timeout	An optional timeout for `FUTEX_WAIT`. If `CLOCKS_NEVER`, it waits forever.

Returns: On success, depends on the operation. On failure, ERR and errno is set.

Definition at line 6 of file futex.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ uptime()

clock_t uptime ( void )

System call for retreving the time since boot.

The uptime() function retrieves the system uptime since boot in clock ticks.

Returns: The system uptime in clock ticks.

Definition at line 6 of file uptime.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ nanosleep()

uint64_t nanosleep ( clock_t timeout )

System call for sleeping.

The nanosleep() function suspends the execution of the calling thread for a specified duration.

Parameters

timeout The duration in nanoseconds for which to sleep, if equal to CLOCKS_NEVER then it will sleep forever, not sure why you would want to do that but you can.

Returns: On success, 0. On failure, ERR and errno is set.

Definition at line 6 of file nanosleep.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ environ

char** environ

extern

The environment variables of the current process.

The environ variable is a NULL-terminated array of strings representing the environment variables of the current process in the format "KEY=VALUE".

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Macro Definition Documentation

◆ PRIORITY_MAX

◆ PRIORITY_MAX_USER

◆ PRIORITY_MIN

◆ PAGE_SIZE

◆ BYTES_TO_PAGES

◆ PAGE_SIZE_OF

◆ FUTEX_ALL

Typedef Documentation

◆ priority_t

Enumeration Type Documentation

◆ spawn_flags_t

◆ prot_t

◆ futex_op_t

Function Documentation

◆ spawn()

◆ getpid()

◆ gettid()

◆ mmap()

◆ munmap()

◆ mprotect()

◆ futex()

◆ uptime()

◆ nanosleep()

Variable Documentation

◆ environ