Differences From
Artifact [a610cab74a]:
1 1 # kcore
2 2 **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-`.
3 3
4 -## entry
5 -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.
4 +# description
5 +**kcore** contains the libk runtime and headers with important typedefs, structures and enumerations.
6 6
7 -## types
8 -kcore contains fixed-width integer types (in `<k/type.h>`). these types are present on every platform. if a platform has a type with a given bit length, it will be used, otherwise, the type will round to the largest available type (except `u8` and `s8`). if you need to be absolutely certain that a type is the appropriate bit length, use sizeof to check its length in a conditional or static assert, for instance `if (sizeof(u16) == 16 / kc_byte_bits)`.
7 +it also provides `boot.o`, the runtime file that must be statically linked into every libk program for it to be able to load. `boot.o` is incorporated in the static library `libk.a` but for architectural reasons cannot be exported from the dynamic library `libk.so`.
8 +
9 +# program entry point
10 +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. entry may have the return type `stat` or `stat_long`. on some operating systems, they are the same; on modern versions of UNIX, however, `stat_long` will allow you to return a 32-bit exit status. most shells will truncate such statuses, but they can be retrieved be the calling process with the appropriate syscall.
11 +
12 +# core types
13 +kcore contains fixed-width integer types (in `<k/type.h>`). these types are present on every platform, and are not prefixed. if a platform has a type with a given bit length, that type will be used will be used, otherwise, the type will round to the largest available type (except `u8` and `s8`, which round to the smallest). if you need to be absolutely certain that a type is the appropriate bit length, use sizeof to check its length in a conditional or static assert, for instance `if (sizeof(u16) == 16 / kc_byte_bits)`.
9 14
10 15 * `u8` - an unsigned 8-bit integer, or the smallest available unsigned type
11 16 * `s8` - a signed 8-bit integer, or the smallest available signed type
12 17 * `u16` - an unsigned 16-bit integer
13 18 * `s16` - a signed 16-bit integer
14 19 * `u32` - an unsigned 32-bit integer
15 20 * `s32` - a signed 32-bit integer
................................................................................
21 26 * `sbig` - the largest available signed integer type. note: ubig and sbig really are the *largest* possible integer types not just the largest native types - if your compiler has extensions for 128-bit types on your arch (as GCC and clang do on x86-64), ubig and sbig will be 128 bits long even if your system word length is less than 128. so only use ubig/sbig if you really, really mean it.
22 27 * `ubyte` - the smallest available unsigned integer type besides \_Bool
23 28 * `sbyte` - the smallest available signed integer type besides \_Bool
24 29 * `stat` - the type of process return values expected by the platform (usually u8 on linux)
25 30 * `sz` - a type large enough to cover a platform's entire address space (libc equivalent size_t)
26 31 * `offset` - a type that can contain the difference between two pointers (libc equivalent ptrdiff_t)
27 32
28 -## constants
29 -in `<k/type.h>`, every type has an associated min and max constant, containing the smallest and largest value that type can hold on your system. these can be access by suffixing a type with `_min` and `_max`, respectively. min and max values of native types can be accessed with the `kc_[us]` prefix - for instance, the minimum value of `signed long` is `kc_slong_min`. (`long long` can be referenced as `llong`).
30 -
31 33 * `byte_bits` - the bit length of ubyte, sbyte, and char; that is, the number of bits in the type `sizeof` measures things in terms of. `sizeof(type) * byte_bits` will always return the number of bits in a type.
32 34
33 -### struct kenv
35 +**kcore** also defines a number of important structs.
36 +
37 +## struct kenv
34 38 `kenv` is a struct that encompasses the environment the program was launched in.
35 39 * `kiochan std` - a stereo IO channel for reading and writing to and from stdout.
36 40 * `kiochan err` - a mono IO channel for writing to stderr.
37 41 * `kvar* vars` - a pointer into the program's environment
38 42
39 -### struct kvar
43 +## struct kvar
40 44 `kvar` is a struct that abstracts over platform environment variables.
41 45 * `kstr name` - the name of an environment variable
42 46 * `kstr val` - the value of an environment variable
43 47 * `char* platform` - a pointer into the platform's underlying representation
44 48
45 -## functions
49 +# constants
50 +in `<k/type.h>`, every type has an associated min and max constant, containing the smallest and largest value that type can hold on your system. these can be access by suffixing a type with `_min` and `_max`, respectively. min and max values of native types can be accessed with the `kc_[us]` prefix - for instance, the minimum value of `signed long` is `kc_slong_min`. (`long long` can be referenced as `llong`).
51 +
52 +# functions
53 +kcore contains only a handful of primitive functions, most of which provide the C runtime.
46 54
47 -### kstop()
55 +## kstop()
48 56
49 57 `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>`).
50 58
51 -## definitions
59 +# definitions
52 60
53 61 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>`.
54 62
55 63 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.
56 64
57 65 (the one minor exception is `null`, a new keyword which libk uses in preference to the ugly, hard-to-type C macro `NULL`.)
58 66
59 67 `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`.
60 68
61 -### macros
69 +# macros
62 70
63 71 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:
64 72
65 - * `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.
66 - * `KAnoreturn` - the GNU/clang-specific version of `noreturn`.
67 - * `KAunused` - acknowledges that a variable is unused and tells the compiler to shut up about it.
68 - * `KAinline` - forces the compiler to inline a function whether it likes it or not.
69 - * `KAflatten` - placed on a function, will force-inline all function calls *made by* that function — sort of like `KAinline` in reverse.
70 - * `KAformat()` - specifies that the function has printf-style syntax for error-checking purposes. worst hack in history.
73 + * `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.
74 + * `KAnoreturn` - the GNU/clang-specific version of `noreturn`.
75 + * `KAunused` - acknowledges that a variable is unused and tells the compiler to shut up about it.
76 + * `KAinline` - forces the compiler to inline a function whether it likes it or not.
77 + * `KAflatten` - placed on a function, will force-inline all function calls *made by* that function — sort of like `KAinline` in reverse.
78 + * `KAformat()` - specifies that the function has printf-style syntax for error-checking purposes. worst hack in history.
71 79
72 80 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)`.
73 81
74 82 however, unlike C++ attributes, GNU-style attributes can only be placed on a function declaration, *not* its definition.