kcore

kcore is the foundation for the rest of libk. it defines types and structs that are needed by every program, and provides the stub that launches a program's "entry" function. unlike the non-core modules, kcore definitions simply use the prefix k-.

entry

when using libk, your program's entry point will not be the int main(int,char**) function that libc opens into. libk will call the function stat entry(kenv) instead. like libc, the value returned by entry will be returned to the host platform.

types

kcore contains fixed-width integer types (in <k/type.h>). note that the availability of each depends on your platform; compilation will fail if e.g. you try to use a u64 or a u128 on a 32-bit platform, so where exact lengths are not required, you may wish to use the built-in C types instead.

• u8 - an unsigned 8-bit integer
• s8 - a signed 8-bit integer
• u16 - an unsigned 16-bit integer
• s16 - a signed 16-bit integer
• u32 - an unsigned 32-bit integer
• s32 - a signed 32-bit integer
• u64 - an unsigned 64-bit integer
• s64 - a signed 64-bit integer
• u128 - an unsigned 128-bit integer
• s128 - a signed 128-bit integer
• word - an unsigned integer of platform word-length (e.g. 32 bits on x86.32; 64 on x86.64)
• sword - a signed integer of platform word-length (e.g. 32 bits on x86.32; 64 on x86.64)
• stat - the type of process return values expected by the platform (usually u8 on linux)

struct kenv

kenv is a struct that encompasses the environment the program was launched in. * kiochan std - a stereo IO channel for reading and writing to and from stdout. * kiochan err - a mono IO channel for writing to stderr. * kvar* vars - a pointer into the program's environment

struct kvar

kvar is a struct that abstracts over platform environment variables. * kstr name - the name of an environment variable * kstr val - the value of an environment variable * char* platform - a pointer into the platform's underlying representation

functions

kstop()

noreturn void kstop(stat) terminates the program immediately, returning the specified integer to the OS as an exit status. the type of integer it takes depends on your operating system. consider using the enum kbad defines in <k/magic.h>, which are designed to standardize exit statuses across different software and are synchronized with a FreeBSD effort to do the same (<sysexit.h).

definitions

kcore is the only module that defines any terms outside the k- namespace. the only terms it so defines are native C terms like noreturn, which are implemented as keywords in a reserved namespace (_ followed by an uppercase letter; in this case, _Noreturn). macros are then defined in new headers for the "natural" version of the term in order to avoid breaking older code. examples of this technique are <stdbool.h> and <stdnoreturn.h>. since libk is designed for new, modern code, breaking old code isn't a concern, and we turn on all these new keywords as soon as you load <k/core.h>.

libk attempts to find the best possible definition and implementation for these various types and keywords, abstracting across different C versions and dialects. you can go ahead and use the normal version of the keywords (e.g. noreturn, bool) no matter what kind of compiler you're using and you're guaranteed that as long as you don't go fiddling with undefined- or implementation behavior, your code will behave the same every time. at worst, it may lack a few optimizations or warnings.

(the one minor exception is null, a new keyword which libk uses in preference to the ugly, hard-to-type C macro NULL.)

bool is implemented as a _Bool typedef if _Bool is available, and as an enum typedef otherwise. either way, and regardless of whether KFclean has been defined, booleans can be used and set to the values true, false, yes, or no. yes and true are synonyms, as are false and no.

macros

if the flag KFclean has not been defined, kcore defines a number of macros to abstract over nonstandard C features. for instance, the KA* macros can be used to specify GNU/clang attributes without worrying about compatibility, as they'll automatically be blanked under an incompatible compiler. the KA series includes:

* `KApure` - marks a "pure" function that changes no state and only takes purely numeric arguments, allowing the compiler to avoid repetetive calls to it or even evaluate it at runtime.
* `KAnoreturn` - the GNU/clang-specific version of `noreturn`.
* `KAunused` - acknowledges that a variable is unused and tells the compiler to shut up about it.
* `KAinline` - forces the compiler to inline a function whether it likes it or not.
* `KAflatten` - placed on a function, will force-inline all function calls *made by* that function — sort of like `KAinline` in reverse.
* `KAformat()` - specifies that the function has printf-style syntax for error-checking purposes. worst hack in history.

if you wish to add more (there are like, hundreds) please consider making a merge request. however, the generic macro KA() is also available in the interim: KA(unused).

however, unlike C++ attributes, GNU-style attributes can only be placed on a function declaration, not its definition.