1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
..
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
|
# 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
................................................................................
* `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.
|
|
|
|
|
|
|
|
>
>
>
>
>
>
>
>
>
|
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
..
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
# 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>`). 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)`.
* `u8` - an unsigned 8-bit integer, or the smallest available unsigned type
* `s8` - a signed 8-bit integer, or the smallest available signed type
* `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 (uses GCC and clang extensions to offer 128-bit integer support on x86-64)
* `s128` - a signed 128-bit integer (ibid)
* `ubig` - the largest available unsigned integer type
* `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.
* `ubyte` - the smallest available unsigned integer type besides \_Bool
* `sbyte` - the smallest available signed integer type besides \_Bool
* `stat` - the type of process return values expected by the platform (usually u8 on linux)
* `sz` - a type large enough to cover a platform's entire address space (libc equivalent size_t)
* `offset` - a type that can contain the difference between two pointers (libc equivalent ptrdiff_t)
## constants
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`).
* `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.
### 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
................................................................................
* `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.
|