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	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.

typedef void(*	note_func_t) (char *note)
	Note handler function type.

typedef uint64_t(*	atnotify_func_t) (char *note)
	User space `atnotify()` handler function 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_ENV = 1 << 3 , SPAWN_EMPTY_CWD = 1 << 4 , SPAWN_EMPTY_GROUP = 1 << 5 , SPAWN_COPY_NS = 1 << 6 , SPAWN_EMPTY_NS , SPAWN_EMPTY_ALL }
	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...

enum	atnotify_t { ATNOTIFY_ADD = 0 , ATNOTIFY_REMOVE = 1 }
	Action type for atnotify(). More...

enum	arch_prctl_t { ARCH_GET_FS = 0 , ARCH_SET_FS = 1 }
	Architecture specific thread data codes. 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, size_t length, prot_t prot)
	System call to map memory from a file.

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

void *	mprotect (void *address, size_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.

uint64_t	notify (note_func_t handler)
	System call that sets the handler to be called when a note is received.

_NORETURN void	noted (void)
	System call that notifies the kernel that the current note has been handled.

int64_t	wordcmp (const char string, const char word)
	Helper for comparing the first word of a string.

uint64_t	atnotify (atnotify_func_t handler, atnotify_t action)
	Adds or removes a handler to be called in user space when a note is received.

_NORETURN void	exits (const char *status)
	System call that handles pending notes for the current thread.

uint64_t	kill (pid_t pid)
	Helper for sending the "kill" command to a process.

uint64_t	arch_prctl (arch_prctl_t op, uintptr_t addr)
	System call for setting architecture specific thread data.

Macro Definition Documentation

◆ PRIORITY_MAX

#define PRIORITY_MAX 63

The maximum priority value, inclusive.

Definition at line 43 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 44 of file proc.h.

◆ PRIORITY_MIN

#define PRIORITY_MIN 0

The minimum priority value.

Definition at line 45 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 107 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 115 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 203 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 41 of file proc.h.

◆ note_func_t

typedef void(* note_func_t) (char *note)

Note handler function type.

Definition at line 255 of file proc.h.

◆ atnotify_func_t

typedef uint64_t(* atnotify_func_t) (char *note)

User space atnotify() handler function type.

Definition at line 309 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_ENV	Don't inherit the parent's environment variables.
SPAWN_EMPTY_CWD	Don't inherit the parent's current working directory, starts at root (/).
SPAWN_EMPTY_GROUP	Don't inherit the parent's process group, instead create a new group.
SPAWN_COPY_NS	Don't share the parent's namespace, instead create a new copy of it.
SPAWN_EMPTY_NS	Create a new empty namespace, the new namespace will not contain any mountpoints or even a root.
SPAWN_EMPTY_ALL	Empty all inheritable resources.

Definition at line 51 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 121 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 178 of file proc.h.

◆ atnotify_t

enum atnotify_t

Action type for atnotify().

Enumerator
ATNOTIFY_ADD
ATNOTIFY_REMOVE

Definition at line 300 of file proc.h.

◆ arch_prctl_t

enum arch_prctl_t

Architecture specific thread data codes.

Enumerator
ARCH_GET_FS	Get the FS base address.
ARCH_SET_FS	Set the FS base address.

Definition at line 346 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, environment variables, priority and current working directory of the parent process by creating a copy. Additionally the child will exist within the same namespace as the parent.

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,
		size_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/const/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,
		size_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,
		size_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:

◆ notify()

uint64_t notify ( note_func_t handler )

System call that sets the handler to be called when a note is received.

A note handler must either exit the thread or call noted().

If no handler is registered, the thread is killed when a note is received.

Warning: It is preferred to use atnotify() instead of this function as using this will prevent the standard library from handling notes.

See also: Notes

Parameters

handler The handler function to be called on notes, can be NULL to unregister the current handler.

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

Definition at line 5 of file notify.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ noted()

_NORETURN void noted ( void )

System call that notifies the kernel that the current note has been handled.

Should only be called from within a handler registered with notify() but NOT with atnotify().

If a note is not currently being handled, the thread is killed.

See also: Notes

Returns: Never returns, instead resumes execution of the thread where it left off before the note was delivered.

Definition at line 5 of file noted.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ wordcmp()

int64_t wordcmp	(	const char *	string,
		const char *	word
	)

Helper for comparing the first word of a string.

Parameters

string	The string.
word	The word to compare against.

Returns: On match, returns 0. On mismatch, returns a non-zero value.

Definition at line 5 of file wordcmp.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ atnotify()

uint64_t atnotify	(	atnotify_func_t	handler,
		atnotify_t	action
	)

Adds or removes a handler to be called in user space when a note is received.

If the return value of a handler is ERR, the process will exit.

Parameters

handler	The handler function to be modified.
action	The action to perform.

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

Definition at line 7 of file atnotify.c.

Here is the call graph for this function:

◆ exits()

_NORETURN void exits ( const char * status )

System call that handles pending notes for the current thread.

Should only be called from an interrupt context.

If the frame is not from user space, this function will return immediately.

Parameters

frame The interrupt frame of the current interrupt.

Returns: On success, true if a note was handled, false otherwise.

Definition at line 7 of file proc_exit.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ kill()

uint64_t kill ( pid_t pid )

Helper for sending the "kill" command to a process.

Parameters

pid	The PID of the process to send the command to.

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

Definition at line 4 of file kill.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ arch_prctl()

uint64_t arch_prctl	(	arch_prctl_t	op,
		uintptr_t	addr
	)

System call for setting architecture specific thread data.

Parameters

op	The operation to perform.
addr	If getting data, a pointer to store the retrieved address. If setting data, the address to set.

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

Definition at line 6 of file arch_prctl.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ PRIORITY_MAX

◆ PRIORITY_MAX_USER

◆ PRIORITY_MIN

◆ BYTES_TO_PAGES

◆ PAGE_SIZE_OF

◆ FUTEX_ALL

Typedef Documentation

◆ priority_t

◆ note_func_t

◆ atnotify_func_t

Enumeration Type Documentation

◆ spawn_flags_t

◆ prot_t

◆ futex_op_t

◆ atnotify_t

◆ arch_prctl_t

Function Documentation

◆ spawn()

◆ getpid()

◆ gettid()

◆ mmap()

◆ munmap()

◆ mprotect()

◆ futex()

◆ uptime()

◆ nanosleep()

◆ notify()

◆ noted()

◆ wordcmp()

◆ atnotify()

◆ exits()

◆ kill()

◆ arch_prctl()